File format spec

App. C

Reference implementation map

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

Concern	`@kimo/core-schema` export
Schemas and static types	`KimoDocument`, `Node`, `FrameNode`, …, `Variable`, `Paint`, `Size`, … (TypeBox; `Static<>` types of the same names)
JSON Schema	`buildJsonSchema()`, `schema/kimo-1.0.schema.json` (`schema/kimo-0.1.schema.json` is the frozen 0.1 schema) (`bun run build:schema`; `check:generated` fails when stale)
Validation	`validate(doc, { libraries, assetFiles, supportedFeatures, lints })`, `ISSUE_CODES`
Defaults	`DEFAULTS`, `applyDefaults`, `stripDefaults`
Serialization	`serialize`, `parse`, `canonicalize`, `isCanonical`, `KEY_ORDER`, `parseJson`, `KimoParseError`
Versioning	`FORMAT_VERSION`, `SCHEMA_URL`, `formatStatus`, `MIGRATIONS` (`MIGRATE_0_1_TO_1_0`), `migrate`, `openDocument`
Resolution (§10.4)	`effectiveTheme`, `defaultTheme`, `resolveVariable`, `selectThemedValue`, `defaultTextFill`
Tree	`buildTree`, `compareSiblings`
Pages (§5.6)	`listPages`, `pageOfRoot`, `isOnPage`, `rootsByPage`, `DEFAULT_PAGE_NAME`
Components (§9)	`locate`, `derivedChain`, `baseRoot`, `resolveIdPath`, `declaredProps`, `argEffect`, `instancesOf`, `localComponents`, `COMPONENT_DESCRIPTION_META_KEY`
Expansion (§9.8)	`createExpandedView`, `documentLookup`, `virtualId`, `parseVirtualId`, `qualifyNodeData`
Merge conflicts (§21)	`Conflict`, `MergeInfo`, `listConflicts`, `conflictCounts`, `applyConflictSide`, `applyAllConflicts`, `markConflictEdited`, `finishMerge`, `attachConflicts`, `conflictMatchesBody`, `ThreeWayMerge` (contract), `MERGE_EXIT`
Edit planners (M3)	`plan*` (components, instances, overrides, props, slots, variables, themes, pins, imports), `applyPlan`, `libraryUsage`

Schemas and static types

@kimo/core-schema export KimoDocument, Node, FrameNode, …, Variable, Paint, Size, … (TypeBox; Static<> types of the same names)

JSON Schema

@kimo/core-schema export buildJsonSchema(), schema/kimo-1.0.schema.json (schema/kimo-0.1.schema.json is the frozen 0.1 schema) (bun run build:schema; check:generated fails when stale)

Validation

@kimo/core-schema export validate(doc, { libraries, assetFiles, supportedFeatures, lints }), ISSUE_CODES

Defaults

@kimo/core-schema export DEFAULTS, applyDefaults, stripDefaults

Serialization

@kimo/core-schema export serialize, parse, canonicalize, isCanonical, KEY_ORDER, parseJson, KimoParseError

Versioning

@kimo/core-schema export FORMAT_VERSION, SCHEMA_URL, formatStatus, MIGRATIONS (MIGRATE_0_1_TO_1_0), migrate, openDocument

Resolution (§10.4)

@kimo/core-schema export effectiveTheme, defaultTheme, resolveVariable, selectThemedValue, defaultTextFill

Tree

@kimo/core-schema export buildTree, compareSiblings

Pages (§5.6)

@kimo/core-schema export listPages, pageOfRoot, isOnPage, rootsByPage, DEFAULT_PAGE_NAME

Components (§9)

@kimo/core-schema export locate, derivedChain, baseRoot, resolveIdPath, declaredProps, argEffect, instancesOf, localComponents, COMPONENT_DESCRIPTION_META_KEY

Expansion (§9.8)

@kimo/core-schema export createExpandedView, documentLookup, virtualId, parseVirtualId, qualifyNodeData

Merge conflicts (§21)

@kimo/core-schema export Conflict, MergeInfo, listConflicts, conflictCounts, applyConflictSide, applyAllConflicts, markConflictEdited, finishMerge, attachConflicts, conflictMatchesBody, ThreeWayMerge (contract), MERGE_EXIT

Edit planners (M3)

@kimo/core-schema export plan* (components, instances, overrides, props, slots, variables, themes, pins, imports), applyPlan, libraryUsage

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative