File format spec

§4

Document root

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

Member	Required	Type	Meaning
`$schema`	yes	string	`https://getkimo.design/schema/kimo-<major>.<minor>.json` for the document's format. For 1.0: `https://getkimo.design/schema/kimo-1.0.json`.
`format`	yes	`major.minor.patch`	Format version (§16). This spec defines `1.0.x`.
`features`	no	string[] (unique)	Feature flags used by the document (§13). Writers MUST list every feature they use and MUST sort the list by code unit.
`meta`	no	struct	`name` (string), `library` (boolean: this is a library), `createdWith` (string), plus namespaced keys (Meta key grammar) with any JSON value. Kimo-owned root keys: `kimo.themes.order` (string[]: display order of theme axes; axes not listed follow by name).
`themes`	no	record axis → string[]	Theme axes. Each list is non-empty with unique values; the first value is the axis default.
`imports`	no	record alias → relative path	Imported libraries (§11).
`variables`	no	record Name → Variable	§10.
`assets`	no	record asset file name → AssetEntry	Optional asset manifest (§12).
`components`	no	Id[] (unique)	Optional index of component node ids. Derived data; when present every entry MUST be a component.
`pages`	no	record Id → Page	The document's pages (§5.6). Absent or empty = one implicit page.
`merge`	no	struct MergeInfo	Labels of an in-progress semantic merge (§21). Only with `conflicts`. Feature `merge/conflicts`.
`conflicts`	no	record Id → Conflict (non-empty)	Stored merge conflicts written by `kimo merge` (§21). Feature `merge/conflicts`.
`nodes`	yes	record Id → Node	The flat node table (§5).

$schema

Required yes

Type string

Meaning https://getkimo.design/schema/kimo-<major>.<minor>.json for the document's format. For 1.0: https://getkimo.design/schema/kimo-1.0.json.

format

Required yes

Type major.minor.patch

Meaning Format version (§16). This spec defines 1.0.x.

features

Required no

Type string[] (unique)

Meaning Feature flags used by the document (§13). Writers MUST list every feature they use and MUST sort the list by code unit.

meta

Required no

Type struct

Meaning name (string), library (boolean: this is a library), createdWith (string), plus namespaced keys (Meta key grammar) with any JSON value. Kimo-owned root keys: kimo.themes.order (string[]: display order of theme axes; axes not listed follow by name).

themes

Required no

Type record axis → string[]

Meaning Theme axes. Each list is non-empty with unique values; the first value is the axis default.

imports

Required no

Type record alias → relative path

Meaning Imported libraries (§11).

variables

Required no

Type record Name → Variable

Meaning §10.

assets

Required no

Type record asset file name → AssetEntry

Meaning Optional asset manifest (§12).

components

Required no

Type Id[] (unique)

Meaning Optional index of component node ids. Derived data; when present every entry MUST be a component.

pages

Required no

Type record Id → Page

Meaning The document's pages (§5.6). Absent or empty = one implicit page.

merge

Required no

Type struct MergeInfo

Meaning Labels of an in-progress semantic merge (§21). Only with conflicts. Feature merge/conflicts.

conflicts

Required no

Type record Id → Conflict (non-empty)

Meaning Stored merge conflicts written by kimo merge (§21). Feature merge/conflicts.

nodes

Required yes

Type record Id → Node

Meaning The flat node table (§5).

No other members are defined in 1.0. A 1.0 validator reports any other member as UNKNOWN_PROPERTY; every reader MUST nevertheless preserve it (§16.3).

The published JSON Schema accepts any $schema of the form https://getkimo.design/schema/kimo-<major>.<minor>.json; that the URL names the document's own format version is checked by validators only (SCHEMA_URL_MISMATCH, a warning), so JSON Schema tooling and validate() agree.

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative