File format spec

§12

Assets

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

Binary assets live in assets/ next to the .kimo file, content-addressed: assets/<sha256-16>.<ext> where <sha256-16> is the first 16 lowercase hex digits of the SHA-256 of the file bytes. They are referenced as ./assets/<hash>.<ext>, deduplicate, never collide across branches and merge as add-only. kimo gc removes unreferenced files; the docs recommend Git LFS above a size threshold.
The optional header member assets is a manifest: asset file name → { mime: string, bytes?: integer, width?: integer, height?: integer, name?: string } (name is the original file name, informative). When the manifest is present, every asset reference MUST be listed (ASSET_MISSING) and unreferenced entries are linted (ASSET_UNUSED); font entries (a font/* MIME type or a .ttf / .otf / .woff / .woff2 name) are used by family, never by path, and are not linted. A validator given the folder listing MUST also report references to missing files.
Fonts fetched from a font service SHOULD be stored as document assets so the file renders offline. A reader matches a font asset to text by the family, weight and style in the font's own name / OS/2 tables; when it cannot inspect the file (WOFF2 needs a Brotli decoder), it reads them from the manifest name, which writers SHOULD then set to <Family>-<Style>.<ext> with the family verbatim and the style one of Thin, ExtraLight, Light, Regular, Medium, SemiBold, Bold, ExtraBold, Black, optionally followed by Italic (Italic alone for 400 italic), e.g. "Space Grotesk-SemiBold.woff2". Family names compare case-insensitively, ignoring spaces. (Informative: Kimo writes each Google face it fetches to assets/ on first use and lists it in the manifest, with this name, when the file is saved — the font never becomes an edit of the open document; files over 20 MB are skipped.)

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative