Revision label
A document that only carries its own revision number, written by an author.
JSON 3 lines
{
"version": 3
}The rules every .carter layout document obeys — the one place the app, carterkit, the MCP and the on-device designer read them from. Layout Config describes the fields that draw a layout; this page describes the envelope around them: which grammar a file speaks, where tools may keep their own data, what is reserved, how things are identified, the size limits, and where binary content may live.
doc.badge.gearshape6 fields, each with what it does.
| Field | Type | Default | What it does |
|---|---|---|---|
schemaVersionschemaVersion | number1–2 | — | Which file format version this is Tells the app which grammar the file uses (1 inline, 2 sectioned); a newer number than the app knows opens the file read-only. |
versionversion | number1–9999 | — | Your own revision number Records the author's revision label shown as Revision in the Layout Hub; the app never refuses or changes a file because of it. |
formatformat | text | — | Marks an exported file Written as the text carter when a layout is exported; no reader requires it. |
extensionsextensions | object | — | Room for other tools' notes Holds data a tool keeps under its own reverse-DNS key; the app carries it through load, save, share and export untouched and never acts on it. |
provenanceprovenance | object | — | Where this layout came from Records the immediate parents of the document, such as the template or package it was copied from. |
requiresrequires | object | — | What the layout needs from the app Lists the features the layout depends on; an app missing one shows an update banner and still draws what it can. |
3 examples, each one a control you can paste into a layout.
A document that only carries its own revision number, written by an author.
{
"version": 3
}An exported file in the sectioned grammar that needs a feature the app may lack.
{
"schemaVersion": 2,
"format": "carter",
"version": 1,
"requires": { "features": ["control.symbol", "sync.sensor"] }
}A copy of a template, with one tool's private notes kept under its own key.
{
"version": 2,
"extensions": {
"com.example.plantdb": { "catalogRef": "ficus-lyrata" }
},
"provenance": {
"parents": [
{ "id": "5C1E0000", "relation": "copy",
"source": { "kind": "template", "ref": "plant-care", "version": "3" } }
]
}
}Two different numbers, never confused:
| Field | Meaning | Who sets it |
|---|---|---|
schemaVersion |
The grammar the file is written in. Optional; absent means 1. |
The writer (app, kit, MCP) — never a person |
version |
The author's revision label ("Revision" in the Layout Hub). Any positive integer. | The author |
version never gates anything: an app must never refuse, migrate or downgrade a
file because of it (people bump it freely, and real files already hold any number).
Bump policy. schemaVersion goes up only when an older app would misread
the document — read it and show something different from what the author wrote.
Additive fields never bump it: an older app ignores a field it doesn't know, and
the file still says what it says. Today there are two grammars:
schemaVersion |
Grammar |
|---|---|
1 (or absent) |
The inline form: every control carries its own position, span, theme and sync |
2 |
The sectioned form (see Sectioned document) |
An app that meets a schemaVersion above the newest one it knows opens the file
read-only (it renders what it can and never writes the file back), so an
older phone can't flatten a newer author's work.
format: "carter" marks an exported file. Writers emit it on export only; no
reader requires it. The document type (UTI) net.carterbeaudoin.carter-layout
is frozen — it will not change with a domain switch.
extensions is where a tool keeps data the app doesn't understand. It may appear
at the top level of the layout and on any control or group:
{
"name": "Greenhouse",
"version": 3,
"extensions": {
"editor": { "canvasZoom": 1.5 },
"com.example.plantdb": { "catalogRef": "ficus-lyrata" }
},
"tabs": [{ "title": "Plants", "icon": "leaf", "children": [
{ "type": "gauge", "id": "c_7f3a9e", "name": "Soil moisture", "position": [0, 0],
"extensions": { "com.example.plantdb": { "sensorModel": "SM-2" } } }
]}]
}
com.example.tool).
A tool reads and writes only its own key.extensions block
through load, edit, save, share and export untouched, and never changes
behavior because of one. Nothing in it may be required to render the layout.extensions block, measured as compact UTF-8 JSON. A strict
load (wire push, import, room join, model output) refuses a larger block; a
disk load drops it and lists the repair in the Layout Hub. carterkit's
validator reports it as an error.extensions.editor is reserved for the app's own editor state (the one key that
is not reverse-DNS); it is left out of the document digest (see
Provenance).A key the app doesn't model and that is not inside extensions is a
core-key guess: the app still tolerates it, but carterkit and the MCP warn
(unknown_field) and suggest moving it into extensions — a future version of
the grammar may give that name a meaning.
provenance (top level, optional) records where the document came from — its
immediate parents only, never the whole family tree:
"provenance": {
"parents": [
{ "id": "5C1E…", "relation": "copy", "digest": "sha256:…",
"source": { "kind": "template", "ref": "plant-care", "version": "3" } }
],
"package": { "id": "com.example.plants", "version": "1.2.0", "params": { "zones": 4 } }
}
relation is one of copy, package, remix, import; source.kind is one of
template, package, file. More than one parent is allowed (a remix).
Digest. A document's digest is SHA-256 over the RFC 8785 (JCS) canonical JSON
of the credential-stripped document, minus provenance, attestations and
extensions.editor, written sha256:<hex>. The app and
carterkit share golden fixtures for it.
Reserved top-level keys — do not author them; a later grammar defines them:
revision, attestations. No metrics or usage counters ever go in a document.
Ids are the stable keys for stored values, sync targeting, visibility
references, glance tiles, sections and edits. Display text is never identity.
id = the installation. A layout's top-level id names this
installed copy and its data. Copy, Make It Mine and copy-to-edit re-mint it
(and record the original in provenance). Importing a file whose id is already
installed asks Update (keep the data) or Install a copy (new id, new
data). Joining a shared room keeps the room's id.c_ + 6 lowercase hex for controls
(c_7f3a9e), g_ for groups and pages, t_ for tabs. Hand-written and
carterkit slugs ("pump-speed") stay valid forever and are never rewritten.
Nothing parses an id or shows it to people.name (controls and groups) is the readable label the editor shows —
name, else label, else the type. Names may repeat; renaming never moves data.label is display text on the control. Changing it changes nothing else.renameId operation, which
rewrites every reference (visibility, glance, sections) in the same edit.
Never rename an id by hand-editing one place.id; without one the tab's title is its id,
so give a tab an id before renaming it.id from day one.id~2, an empty one type-N) and refused by strict loads and carterkit.A control that shows a measurement carries one unit field, and it is a real
measurement unit (Foundation unit names: celsius, fahrenheit, kph, mph,
percent, kilowattHours, …), not display text. The app converts and formats the
value for the reader's locale — the author writes "unit": "celsius" once and an
American sees °F. A unit string the app doesn't recognize is shown literally, so
"unit": "pots" still reads "12 pots". There is no separate display-unit field.
Controls adopt unit one at a time (the stat tile first); until a control's own
doc lists it, the field is ignored there.
requires says what a document needs from the app. Features are name@N
strings — a capability name plus an optional version, e.g.
"requires": { "features": ["control.symbol", "sync.sensor"] } (sync.sensor =
sync.sensor@1). The names the app speaks come in four families:
control.<type>, sync.<method>, action.<method>, and layout.<key>
(layout.requires, layout.fallback, layout.derive); get-device-info reports the full list as
features. A name the app does not know counts as unmet.
An app missing a requirement shows one update banner and still renders what it
can. requires is the author's soft gate; schemaVersion is the grammar marker
and decides whether the app may write the file.
schemaVersion: 2 lets a document keep a control's facets out of line, in
top-level sections keyed by control or group id, instead of on the control:
| Section | Holds, per id |
|---|---|
placements |
position, span (the default presentation), plus optional landscape and regular variants — each {position, span} or {hidden: true}. default: {position, span} is accepted as an alias of the flat keys (the flat keys win) |
styles |
theme, tint, icon, hideLabel, hideValue, hideBackground, animation |
connectivity |
sync, action, longPressAction |
{
"schemaVersion": 2,
"name": "Greenhouse", "version": 4,
"tabs": [{ "id": "t_a01b2c", "title": "Plants", "icon": "leaf",
"children": [{ "type": "gauge", "id": "c_7f3a9e", "name": "Soil moisture" }] }],
"placements": { "c_7f3a9e": { "position": [0, 0], "span": [2, 2],
"landscape": { "position": [0, 2], "span": [2, 1] } } },
"styles": { "c_7f3a9e": { "tint": "#34C759" } },
"connectivity": { "c_7f3a9e": { "sync": [{ "method": "meshsocket", "event": "broadcast", "filter": { "msg_type": "soil" }, "valuePath": "moisture" }] } }
}
appearance is the app-shell block (Appearance), not a section.children and, recursively, group
children (container panels and long-press groups are not addressable). If two
children share an id, the entry applies to the first.landscape renders when the page has compact height (an iPhone on its side),
regular on an iPad-width page; the default position/span renders
everywhere else. The same two keys are also accepted inline on a child. Rules
(reflow, obstacles, hidden) are in Landscape and iPad.schemaVersion 1 opens those files
read-only.The single table every layer reads. The app's sanitizer and renderer and carterkit's validator take these numbers from here (the app's unit tests and carterkit's loader both parse this table), so a layout the kit accepts is a layout the device renders. A strict load (wire, import, join, model output) refuses a document past a limit; a disk load clamps or trims it and lists the repair in the Layout Hub.
| Limit | Value | Applies to |
|---|---|---|
maxTabs |
24 | Tabs per layout |
maxControls |
2000 | Controls per layout (groups not counted) |
maxNestingDepth |
8 | Groups/containers enclosing a control (a tab's own children are 0). Deeper content is refused, or trimmed with a "Nested too deeply" placeholder |
maxStringBytes |
4096 | Any string value |
maxDataImageBytes |
524288 | A data:image/… URL in a url / baseURL field |
softDataImageBytes |
65536 | Advisory only: carterkit warns inline_blob on a data:image/… URL past it; no load refuses it |
maxExtensionsBytes |
65536 | One extensions block, compact UTF-8 JSON |
maxPosition |
256 | Each position coordinate (0…256) |
maxSpan |
64 | Each span value (1…64) |
maxGridColumns |
64 | grid.columns |
maxGridRows |
512 | grid.rows |
minTimerSeconds |
0.25 | interval, autoAdvance, webRefreshInterval (autoAdvance / webRefreshInterval 0 = off) |
minSendRateSeconds |
0.02 | Joystick sendRate (an event throttle) |
minPublisherIntervalSeconds |
0.05 | Sensor publishers[].interval |
maxBufferPoints |
5000 | sparklinePoints, minLines, maxLines, historyCount |
maxWireBytes |
2097152 | A pushed, imported, joined or model-written document |
maxFileBytes |
8388608 | A layout file loaded from disk |
data:image/… URL in a url / baseURL field, up to maxDataImageBytes.
Anything else base64-encoded (fonts, audio, other data: URLs, long base64
strings) is refused as an oversized string and flagged by carterkit as
inline_blob. Host the file and link it by https:// URL.backgroundImage.asset names an image bundled in the app; it cannot point
at a file of your own.asset:// URL scheme is reserved for a future package asset store.
No runner resolves it today. Every load accepts it (so an asset store can ship
additively), an image pointing at it shows its placeholder, and carterkit warns
reserved_scheme. Don't author it yet.name and extensionsGenerated from ControlDocs/document-contract.md. Something unclear or missing? Tell me.