File format spec

§2

Container

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

The canonical working form is one UTF-8 .kimo JSON file plus an assets/ folder next to it. Files MUST NOT be encrypted or compressed.
Writers MUST NOT emit a byte-order mark and MUST use LF line endings. Readers MUST ignore a leading BOM and MUST accept CRLF (it is JSON whitespace).
A library is an ordinary .kimo document with meta.library: true; its file name SHOULD end in .lib.kimo.
.kimoz is a ZIP used only for transport ("Export as package"): it holds the .kimo, its assets/ and imported libraries. It is never the working form.
Every relative path in a document (imports, assets, shaders, scripts) resolves against the directory of the .kimo file.

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative