# AAC sub-spec — The board data model

Normative refinement of [SPEC §2](../SPEC.md). Reference: `aac_core::{Board, Cell, GridLayout, GridPosition, CellContent, CellAction, BoardType}`.

A **board** is a person's communication surface. It is a small, text-like document — artwork is referenced, not embedded (§4) — so a voice travels cheaply between devices and implementations.

```
Board = (id: BoardId, name: String, board_type: BoardType,
         layout: GridLayout, cells: [Cell])
Cell  = (id: CellId, position: GridPosition, content: CellContent,
         action: CellAction, style: CellStyle, frequency: u64, locked: bool,
         [hidden: bool], [sound: String], [symbol: String], [lang: String])
```

The bracketed fields are optional (proposed, [SPEC §2.1](../SPEC.md)) and omitted at their defaults, so a board that uses none of them serializes as it did before them (§8).

## 1. Identity — `id: BoardId`, `id: CellId`

Both are UUIDs, stable for the life of the structure. A `BoardId` is the target of a `Navigate` action, so it is also the edge label of the board graph (§5). Two openings of the same logical board MUST present the same `BoardId` and the same set of `CellId`s.

## 2. Board type — `board_type`

One of `Grid` (a symbol grid), `VisualScene` (photo-based with hotspots, for emerging communicators), `Keyboard` (text input, for literate users), `Hybrid` (mixed symbol + text), `QuickAccess` (high-frequency phrases — the home board). The type is a rendering hint and a vocabulary-strategy marker; it MUST NOT change a cell's `position` semantics (§3 of SPEC).

## 3. Layout — `layout: GridLayout { rows: u16, cols: u16 }`

The grid dimensions. `capacity = rows × cols` is the maximum number of non-overlapping cells. A board MAY hold fewer cells than its capacity; absent positions render as empty grid (distinct from a `Blank` cell, which is an explicit, addressable reservation — see §5).

## 4. Position — `position: GridPosition { row: u16, col: u16 }`

0-indexed. A position is assigned once and is **immutable** for the life of the cell (motor stability — see [`motor_stability.md`](motor_stability.md)). No two cells on a board MAY share a position.

## 5. Content — `content: CellContent`

One of:

- `Symbol { symbol_id, label }` — a symbol referenced by registry id plus its text label. The label MUST survive round-trip even where the artwork cannot be rendered ([`../SPEC.md` §4]).
- `Text(String)` — plain text, for keyboard boards and literate users.
- `Photo { image_ref, label }` — a referenced image with a label, for visual scenes.
- `Blank` — an intentional, addressable empty. A `Blank` reserves its position to preserve the surrounding motor grid and MUST NOT be elided on round-trip.

## 6. Action — `action: CellAction`

What activation does: `Speak(text)`, `Navigate(BoardId)`, `Modifier(GrammarModifier)`, `Backspace`, `Clear`, `Predict`, `SpeakAll`, `Buffer(text)`. `Navigate` edges the board graph; `Modifier` applies a grammatical transform (`Plural`, `PastTense`, `PresentProgressive`, `FutureTense`, `Possessive`, `Negation`, `Question`, `Pronoun(name)`) to the message bar; `Buffer` adds to the message bar without speaking.

The board graph is the source of truth; a grid is one projection of it. A conforming editor MUST keep the `Navigate` edges referentially intact: deleting a board MUST report, not silently break, any cell that navigates to it.

## 7. Optional fields *(proposed — SPEC §2.1)*

- `hidden` — the word is hidden in place ([`motor_stability.md`](motor_stability.md) §3). Default `false`.
- `sound` — a recording the cell plays in place of speaking its words (the person's own voice: message banking), as a reference the client resolves (`media:<id>` in the reference app, or a `data:` URI). A client that cannot play it speaks the words. Default absent.
- `symbol` — the symbol concept chosen for the cell in place of the one its words name; `""` is words only. Default absent.
- `lang` — the language the cell's words are written in (`fr`, `es`, `ar`…) when they are the person's own words: shown and spoken exactly as written, never glossed. Absent: the words are keys the client glosses into the person's language. Default absent.

## 8. Canonicality

A board serializes to the canonical interchange form of [SPEC §7](../SPEC.md). Round-trip MUST preserve every `position`, `content`, `action`, and `symbol_id` byte-for-byte. Conformance suite **C4** pins the wire round-trip; the published vectors live in [`../conformance/v1/`](../conformance/v1/).