SpecThe spec layerscreen_spec.json is the contract everything else is generated from. These articles cover its anatomy, the six ways to split one, and how validation keeps spec and code from drifting.

ArticlesRead Anatomy first; the split patterns build on it.

The anatomy of a screen spec

A field-by-field walk through screen_spec.json — every top-level section, what it declares, and how it cross-references the others.

/spec/anatomy

Six ways to split a spec

A single screen_spec.json is fine until the file passes 300 lines, or until two screens need to share the same shape. This article is the map: six established split patterns, what each one buys you, and how to pick.

/spec/split-overview

Separating the layout file

Pattern 1 of spec splitting, in detail. Move the visual tree out of the spec into a sibling Layout JSON, point `metadata.layoutFile` at it, and let `layout_importer` stitch the two back together at generate time. This is the most common split pattern on the site and the easiest starting point.

/spec/layout-file

Parent + sub specs

Pattern 2 of spec splitting, in detail. One screen, several spec files: since jsonui-cli 1.7.6 the parent is a pure container — it names the sub-specs and little else — and every section that describes behaviour is supplied by the subs. Declaring one of those in the parent is now an error rather than a section that quietly did nothing. Fits screens whose state partitions cleanly by region.

/spec/parent-sub-spec

Component specs

Pattern 3 of spec splitting, in detail. When a custom UI shows up on two or more screens, extract its contract into `docs/components/json/<name>.component.json`. Screens import it through `structure.customComponents`; the generator emits a platform-native component per target. This site ships five of these today — CodeBlock, Sidebar, TableOfContents, TopBar, and DocSamplePreview — and the same pattern scales to dozens.

/spec/component-spec

Custom types

Pattern 4 of spec splitting, in detail. Declare reusable row / entry shapes once inside `dataFlow.customTypes` and reference them by name (`[ActivityRow]`) from any `uiVariables` or VM var. A lighter-weight DRY knob than splitting into sub-specs — the unit of reuse here is the *type shape*, not a slice of state.

/spec/custom-types

Collection cell classes

Pattern 5 of spec splitting, in detail. When a Collection needs more than one cell layout, or when the same cell shape shows up in two or more Collections, hoist each cell into `docs/screens/layouts/cells/<name>.json` and reference it by path. `jui build` inlines the referenced cell at generate time and emits one typed component per cell.

/spec/cell-classes

Validation + drift detection

Two tools guard specs, and they check different things. `jsonui-doc validate spec` checks the spec file on its own — schema, required fields, cross-references inside the spec. `jui verify` checks drift — whether the on-disk Layout JSON / data section / custom-type registrations match what the current spec would generate. Run both in CI; the combination is what keeps a spec honest end-to-end.

/spec/validation-and-drift