Specification

Spec v4.4 (2026-10-08)

The TOON specification is the authoritative reference for encoders, decoders, and validators. Implementers work through the conformance checklist (§13) for their class, the CHANGELOG records each version, and CONTRIBUTING covers how to propose changes.

NOTE

The TOON specification is stable, but also an idea in progress. Nothing's set in stone – help shape where it goes by contributing to it or sharing feedback.

Sections

• §1 Terminology and Conventions – key terms and RFC 2119 keywords.
• §2 Data Model – the JSON data model, ordering, and canonical numbers.
• §3 Encoding Normalization – how non-JSON values are normalized before encoding.
• §4 Decoding Interpretation – how tokens map to strings, numbers, booleans, and null.
• §5 Concrete Syntax and Root Form – line structure, comment lines, and root detection.
• §6 Header Syntax – the ABNF for array headers and field lists.
• §7 Strings and Keys – quoting rules and escape sequences.
• §8 Objects – fields, nesting, and empty objects.
• §9 Arrays and Tabular Forms – inline, tabular, list, and keyed tabular forms.
• §10 Objects as List Items – indentation of objects inside lists.
• §11 Delimiters – comma, tab, and pipe, and their scope.
• §12 Indentation and Whitespace – what encoders emit and decoders accept.
• §13 Conformance and Options – conformance classes, options, and checklists.
• §14 Decode Errors and Non-Strict Recoveries – every decode error, and the five recoveries strict: false applies.
• §15 Security Considerations – injection risks and the checks against them.
• §16 Internationalization – Unicode and locale-independent numbers.
• §17 IANA Considerations – the provisional text/toon media type.
• §18 Versioning – what a major or minor version may change.
• Appendix C: Test Suite – the fixtures implementations run.