Record Format Evidence

Answer#

Measured over the largest consumer on 2026-10-31, .litespec/behavior holds 2,450 pages with 403k lines of JSON frontmatter against 32k non-blank body lines. Every body uses fixed sections: Goal (1,273), Example (1,211), Risk (1,022), What Happens (984), Notes (476), and Screen Summary (380). Aggregate transitions and data live only as body tables, 164 and 179 of them, so a Markdown table is the source of truth for every aggregate state set. Checks read the frontmatter and the merged tables but not the body prose, so Goal, Risk, and What Happens can change without any check noticing. Behavior bodies hold 1,551 Markdown links to .md file paths. Research pages are articles: 181 distinct headings, 160 subsections, 85 tables, 584 distinct cited URLs, and 486 of those URLs are missing from the dated sources list. A rough converter puts YAML at 78% of the JSON lines and 81% of its characters; the gain is mainly structural, not size.

The format survey compared KDL, TOML, JSON5, JSONC, KSON, HUML, NestedText, MAML, TOON, Ziggy, RON, EDN, CUE, Pkl, Nickel, Dhall, Jsonnet, and HCL, and found nothing that beats a strict YAML subset. KSON is the closest by design but is in beta with no .NET implementation. Because KSON is a JSON superset with [JSON Schema][json-schema] support, converting from strict YAML to it later would be mechanical. The reader is YamlDotNet: it accepts the YAML YamlDotNet reads, except it refuses an empty document, a document that does not start at the first column, document markers, tabs in indentation, folded blocks, and duplicate keys, each with the line it sits on. Scalars resolve by the core schema of [the YAML 1.2 specification][yaml-spec-1-2]. Key order comes from [the record schema][record-schema], which validates the parsed YAML unchanged. A scalar that would resolve to a non-string where a string is meant is quoted, and multi-line text uses | block scalars.

Anything a check reads is a YAML field; anything that only helps someone understand goes in the explanation file. Research and decision require their explanation file. Prose cites records by identifier, and each research source carries a key the article cites.

Notes on Sources#

Three sources were read on 2026-10-31. yaml-spec-1-2 is the YAML 1.2 specification, read for the core schema resolution rules behind the strict subset. json-schema is the JSON Schema site, read for the validation claim the subset relies on and the KSON superset claim behind later conversion. record-schema is the shipped record schema, read for the validation target and the key order. The eighteen-format survey and the consumer counts are the researcher's own comparison and measurement, carried in the Answer.