A layout document describes one screen as a flat list of nodes with parent references. It holds only ids, keys and values from your catalog: no code, no expressions, no URLs.
{
"schemaVersion": 1,
"screen": "home",
"root": "root",
"nodes": [
{ "id": "root", "type": "vstack", "order": 0 },
{ "id": "header", "parent": "root", "type": "component", "component": "header", "order": 0 },
{ "id": "section", "parent": "root", "type": "vstack", "order": 1, "label": "Section" },
{ "id": "stats", "parent": "section", "type": "component", "component": "stats.list", "order": 0,
"props": { "title": "Steps" } },
{ "id": "account", "parent": "root", "type": "component", "component": "account.delete", "order": 2 },
{ "id": "grid", "parent": "root", "type": "grid", "order": 3, "columns": 2 },
{ "id": "a", "parent": "grid", "type": "component", "component": "tile", "order": 0 }
]
}
Containers
A node's type is component or one of the container types:
| Container | Draws |
|---|---|
vstack, hstack, zstack |
stacks; a row whose parts don't fit wraps onto more lines |
grid |
columns 1–12, children use size.span |
scroll |
a scrolling section (axis) |
list, form |
system list or form: each child container is a section, each component a row |
pager |
one page per child |
Containers may carry surface: card.
Node fields
| Field | Meaning |
|---|---|
order |
position among siblings |
hidden |
hidden by the user (shown in the tray to restore) |
size |
height multiplier and grid span |
alignment |
leading, center or trailing (never left/right, so right-to-left mirrors) |
label, showsLabel |
label key; in a list or form the label becomes the section header |
options |
values for the part's content options |
style |
per-part style: textSize (−2…+3), emphasis, color, surface, corners, padding |
User screens also carry title and icon. The theme, user-screen index, navigation, designs and
versions are separate documents with their own routes.
Validation order
Every stored or received document passes, in order:
- decode (field types)
- schema version
- screen id
- each component exists in the catalog, is allowed at this schema version and has valid props (otherwise the node is dropped)
- size hints in range (clamped)
- structure: one root container, unique ids, parents exist and are containers, every node reachable, no cycles, grid columns 1–12
- locks from your default document and catalog
- limits: 1–500 nodes, ids up to 128 characters, labels up to 200, document up to 64 KB
On the device, a structural or lock failure renders your default document, and a repairable issue (an unknown option, a style the part no longer allows) drops just that value. On the server, a write with any issue is refused with HTTP 422 and the list of issues. The SDKs and the server run the same shared fixture cases.