File format spec

§17

Validation

Status

Stable (format version 1.0.0, frozen 2026-10). Backward compatible within 1.x (§16.4). Supersedes the draft v0.1, kept as a historical record; 0.1 files open through the 0.1 → 1.0 migration (§16.2).

Schema

https://getkimo.design/schema/kimo-1.0.json (JSON Schema draft 2020-12), generated into packages/core-schema/schema/kimo-1.0.schema.json. The 0.1 schema stays published at …/kimo-0.1.json (schema/kimo-0.1.schema.json, frozen).

Reference

@kimo/core-schema (packages/core-schema). Where this document and the implementation disagree, that is a bug in one of them; file an issue.

Plan of record

docs/teardown.md §10. Every place where this spec resolves an ambiguity in, or deviates from, that section is listed in §20.

License

MIT

A validator checks, in order: the format version; the structure (the JSON Schema, with clear errors for unions); feature declarations; then the semantic rules. Every issue has a JSON Pointer path, a code and a message. Errors make the document invalid; warnings are lints. The table is normative.

Code	Severity	Meaning
`NOT_AN_OBJECT`	error	The document root is not a JSON object.
`SCHEMA`	error	A value does not match the structural schema.
`UNKNOWN_PROPERTY`	error	A property not defined by this format version (preserved, but invalid).
`UNKNOWN_NODE_TYPE`	error	A node `type` not defined by this format version.
`FORMAT_INVALID`	error	`format` is not a `major.minor.patch` version.
`FORMAT_NEWER`	error	The document's format is newer than this reader; it opens read-only.
`FORMAT_OLDER`	error	The document's format is older; migrate it before validating.
`SCHEMA_URL_MISMATCH`	warning	`$schema` does not name the document's format version.
`FEATURE_UNKNOWN`	warning	`features` lists a feature this reader does not know; the file opens read-only.
`FEATURE_NOT_DECLARED`	error	A feature-gated construct is used but its feature is not listed in `features`.
`PARENT_MISSING`	error	`parent` names a node that does not exist.
`PARENT_CYCLE`	error	Following `parent` links leads back to the node.
`PARENT_NOT_CONTAINER`	error	The parent's type cannot have children.
`AT_WITHOUT_INSTANCE`	error	`at` is set but the parent is not an instance.
`INSTANCE_CHILD_WITHOUT_AT`	error	A node whose parent is an instance has no `at`.
`AT_WITHOUT_OVERRIDE`	error	`at` does not name a `slot` or `replace` override of the parent instance.
`REPLACE_COUNT`	error	A `replace` override does not have exactly one replacement node.
`ORDER_DUPLICATE`	warning	Two siblings share an `order` key (legal; ties sort by id).
`INSTANCE_VISUAL_FIELD`	error	A visual field at an instance's top level; it belongs in `props`.
`REF_MISSING`	error	A component reference (`of`, `set.of`, an instance prop's `default` or `args` value, `slot.suggested`) names a node that does not exist.
`REF_NOT_COMPONENT`	error	A component reference names a node that is not a component.
`INSTANCE_CYCLE`	error	A component contains (directly or transitively, including through `set.of`, instance-prop `args` and instance-prop `default`s) an instance of itself.
`OVERRIDE_PATH_UNRESOLVED`	error	An override key, `at` or prop target does not resolve to a descendant.
`OVERRIDE_INVALID`	error	A `set` override or instance `props` would make the target invalid.
`SLOT_TARGET_INVALID`	error	A `slot` override or slot prop targets a node that is not a slot frame.
`PROP_TARGET_INVALID`	error	A declared component prop targets a node of the wrong kind.
`ARG_UNKNOWN`	error	An instance `args` key is not a declared prop of the component.
`ARG_INVALID`	error	An instance `args` value does not fit the declared prop.
`COMPONENTS_INDEX_INVALID`	error	The `components` index lists a node that is not a component.
`VARIABLE_MISSING`	error	A binding names a variable that does not exist.
`VARIABLE_TYPE_MISMATCH`	error	A binding's variable type does not fit the bound property.
`VARIABLE_CYCLE`	error	Variable aliases form a cycle.
`THEME_AXIS_UNKNOWN`	error	A theme pin or `when` names an undeclared axis.
`THEME_VALUE_UNKNOWN`	error	A theme pin or `when` names a value its axis does not declare.
`THEME_NO_MATCH`	warning	A bound variable has no themed entry for the node's effective theme.
`ALIAS_UNKNOWN`	error	A qualified id, id path segment, binding or axis uses an alias not declared in `imports`.
`LIBRARY_NOT_LOADED`	warning	References into a library were not checked because it was not supplied.
`ASSET_MISSING`	error	An asset reference is not in the asset manifest / asset folder.
`ASSET_UNUSED`	warning	An asset manifest entry is not referenced.
`MESH_SIZE`	error	A mesh paint's `colors` / `points` length is not `cols * rows`.
`TEXT_INVISIBLE`	warning	A text node's fill paints nothing.
`FIT_ALL_FILL`	warning	A `fit` frame whose children all `fill` the same axis (circular sizing).
`PROMPT_TARGET_MISSING`	warning	A prompt's `target` names no frame of this document.
`PAGE_UNKNOWN`	warning	A root node's `page` names no page of `pages`; the node is shown on the first page.
`PAGE_NOT_ROOT`	warning	A node that is not a root node has `page`; it is ignored.
`VARIABLE_UNUSED`	warning	A variable is not referenced (not reported for library documents).
`MERGE_WITHOUT_CONFLICTS`	error	`merge` labels are present but there is no `conflicts` table.
`CONFLICT_PATH_INVALID`	error	A conflict `path` addresses what another kind owns (`type`/`parent`/`order`/`at`, or a root member other than meta/themes/imports/assets/components/pages).
`CONFLICT_DUPLICATE`	error	Two conflicts address the same target, or one contains the other.
`CONFLICT_OPEN`	warning	A merge conflict is not resolved yet.
`CONFLICT_STALE`	warning	The document body no longer holds the conflict's `applied` side (edited by hand); editors mark it `edited`.

NOT_AN_OBJECT

Severity error

Meaning The document root is not a JSON object.

SCHEMA

Severity error

Meaning A value does not match the structural schema.

UNKNOWN_PROPERTY

Severity error

Meaning A property not defined by this format version (preserved, but invalid).

UNKNOWN_NODE_TYPE

Severity error

Meaning A node type not defined by this format version.

FORMAT_INVALID

Severity error

Meaning format is not a major.minor.patch version.

FORMAT_NEWER

Severity error

Meaning The document's format is newer than this reader; it opens read-only.

FORMAT_OLDER

Severity error

Meaning The document's format is older; migrate it before validating.

SCHEMA_URL_MISMATCH

Severity warning

Meaning $schema does not name the document's format version.

FEATURE_UNKNOWN

Severity warning

Meaning features lists a feature this reader does not know; the file opens read-only.

FEATURE_NOT_DECLARED

Severity error

Meaning A feature-gated construct is used but its feature is not listed in features.

PARENT_MISSING

Severity error

Meaning parent names a node that does not exist.

PARENT_CYCLE

Severity error

Meaning Following parent links leads back to the node.

PARENT_NOT_CONTAINER

Severity error

Meaning The parent's type cannot have children.

AT_WITHOUT_INSTANCE

Severity error

Meaning at is set but the parent is not an instance.

INSTANCE_CHILD_WITHOUT_AT

Severity error

Meaning A node whose parent is an instance has no at.

AT_WITHOUT_OVERRIDE

Severity error

Meaning at does not name a slot or replace override of the parent instance.

REPLACE_COUNT

Severity error

Meaning A replace override does not have exactly one replacement node.

ORDER_DUPLICATE

Severity warning

Meaning Two siblings share an order key (legal; ties sort by id).

INSTANCE_VISUAL_FIELD

Severity error

Meaning A visual field at an instance's top level; it belongs in props.

REF_MISSING

Severity error

Meaning A component reference (of, set.of, an instance prop's default or args value, slot.suggested) names a node that does not exist.

REF_NOT_COMPONENT

Severity error

Meaning A component reference names a node that is not a component.

INSTANCE_CYCLE

Severity error

Meaning A component contains (directly or transitively, including through set.of, instance-prop args and instance-prop defaults) an instance of itself.

OVERRIDE_PATH_UNRESOLVED

Severity error

Meaning An override key, at or prop target does not resolve to a descendant.

OVERRIDE_INVALID

Severity error

Meaning A set override or instance props would make the target invalid.

SLOT_TARGET_INVALID

Severity error

Meaning A slot override or slot prop targets a node that is not a slot frame.

PROP_TARGET_INVALID

Severity error

Meaning A declared component prop targets a node of the wrong kind.

ARG_UNKNOWN

Severity error

Meaning An instance args key is not a declared prop of the component.

ARG_INVALID

Severity error

Meaning An instance args value does not fit the declared prop.

COMPONENTS_INDEX_INVALID

Severity error

Meaning The components index lists a node that is not a component.

VARIABLE_MISSING

Severity error

Meaning A binding names a variable that does not exist.

VARIABLE_TYPE_MISMATCH

Severity error

Meaning A binding's variable type does not fit the bound property.

VARIABLE_CYCLE

Severity error

Meaning Variable aliases form a cycle.

THEME_AXIS_UNKNOWN

Severity error

Meaning A theme pin or when names an undeclared axis.

THEME_VALUE_UNKNOWN

Severity error

Meaning A theme pin or when names a value its axis does not declare.

THEME_NO_MATCH

Severity warning

Meaning A bound variable has no themed entry for the node's effective theme.

ALIAS_UNKNOWN

Severity error

Meaning A qualified id, id path segment, binding or axis uses an alias not declared in imports.

LIBRARY_NOT_LOADED

Severity warning

Meaning References into a library were not checked because it was not supplied.

ASSET_MISSING

Severity error

Meaning An asset reference is not in the asset manifest / asset folder.

ASSET_UNUSED

Severity warning

Meaning An asset manifest entry is not referenced.

MESH_SIZE

Severity error

Meaning A mesh paint's colors / points length is not cols * rows.

TEXT_INVISIBLE

Severity warning

Meaning A text node's fill paints nothing.

FIT_ALL_FILL

Severity warning

Meaning A fit frame whose children all fill the same axis (circular sizing).

PROMPT_TARGET_MISSING

Severity warning

Meaning A prompt's target names no frame of this document.

PAGE_UNKNOWN

Severity warning

Meaning A root node's page names no page of pages; the node is shown on the first page.

PAGE_NOT_ROOT

Severity warning

Meaning A node that is not a root node has page; it is ignored.

VARIABLE_UNUSED

Severity warning

Meaning A variable is not referenced (not reported for library documents).

MERGE_WITHOUT_CONFLICTS

Severity error

Meaning merge labels are present but there is no conflicts table.

CONFLICT_PATH_INVALID

Severity error

Meaning A conflict path addresses what another kind owns (type/parent/order/at, or a root member other than meta/themes/imports/assets/components/pages).

CONFLICT_DUPLICATE

Severity error

Meaning Two conflicts address the same target, or one contains the other.

CONFLICT_OPEN

Severity warning

Meaning A merge conflict is not resolved yet.

CONFLICT_STALE

Severity warning

Meaning The document body no longer holds the conflict's applied side (edited by hand); editors mark it edited.

The five conflict codes (§21.3) are reported by whole-document runs only, like the usage lints.

Parse-level failures (PARSE_ERROR, DUPLICATE_KEY, NOT_AN_OBJECT) are raised by the reader before validation. Lints are reader behaviour, not format: a later release may add lints (clipped content, unused components) without a format change.

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative