Specification

The TOON specification is the authoritative reference for implementing encoders, decoders, and validators. It defines the concrete syntax, normative encoding/decoding behavior, and strict-mode validation rules.

You don't need this page to use TOON. It's mainly for implementers and contributors. If you're looking to learn how to use TOON, start with the Getting Started guide instead.

[!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.

Current Version

Spec v{{ $spec.version }} (2026-07-22) is the current published Working Draft. It is stable for implementation but not yet finalized; see "Status of This Document" in the spec for details.

Media Type & File Extension

The spec defines a provisional media type and file extension in §17:

• Media type: text/toon (provisional, not yet IANA‑registered; UTF‑8 only)
• File extension: .toon

TOON documents are always UTF‑8 with LF (\n) line endings; the optional charset parameter, when present, is utf-8.

Guided Tour of the Spec

Core Concepts

§1 Terminology and Conventions: Defines key terms like "indentation level", "active delimiter", "strict mode", and RFC2119 keywords (MUST, SHOULD, MAY).

§2 Data Model: Specifies the JSON data model (objects, arrays, primitives), array/object ordering requirements, and canonical number formatting (canonical decimal for values in [1e-6, 1e21) or zero; exponent form permitted outside).

§3 Encoding Normalization: Defines how non-JSON types (Date, BigInt, NaN, Infinity, undefined, etc.) are normalized before encoding. Required reading for encoder implementers.

§4 Decoding Interpretation: Specifies how decoders map text tokens to host values (quoted strings, unquoted primitives, numeric parsing with leading-zero handling). Decoders default to strict mode (strict = true) in the reference implementation; strict-mode errors are enumerated in §14.

Syntax Rules

§5 Concrete Syntax and Root Form: Defines TOON's line-oriented, indentation-based notation and how to determine whether the root is an object, array, or primitive. §5.1 defines full-line comment lines, removed in a lexical pre-pass before any other processing.

§6 Header Syntax: Normative ABNF grammar for array and keyed headers: key[N<delim?>]{fields}: and key[N:<delim?>]{fields}:. Specifies bracket segments, delimiter symbols, and field lists, including nested field groups.

§7 Strings and Keys: Complete quoting rules (when strings MUST be quoted), escape sequences (only \\, \", \n, \r, \t, and \uXXXX for other U+0000–U+001F controls are valid), and key encoding requirements.

§8 Objects: Object field encoding (key: value), nesting rules, key order preservation, and empty object handling.

§9 Arrays and Tabular Forms: Covers all array forms – primitive (inline), arrays of objects (tabular, including nested field groups), mixed/non-uniform (list), and arrays of arrays – plus the keyed tabular form for objects of uniform objects (§9.5). Includes the detection requirements for each form.

§10 Objects as List Items: Indentation rules for objects appearing in list items (first field on the hyphen line), including the canonical pattern when the first field is a tabular array or keyed tabular object (header on the hyphen line, rows at depth +2, sibling fields at depth +1).

§11 Delimiters: Delimiter scoping (document vs active), delimiter-aware quoting, and parsing rules for comma/tab/pipe delimiters.

§12 Indentation and Whitespace: Encoding requirements (consistent spaces, no tabs in indentation, no trailing spaces/newlines) and decoding rules (strict vs non-strict indentation handling).

Conformance and Validation

§13 Conformance and Options: Defines conformance classes (encoder, decoder, validator), standardized options, and conformance checklists.

§14 Strict Mode Errors and Diagnostics: Authoritative checklist of all strict-mode errors: array and entry count and width mismatches (§14.1), syntax and structural errors (§14.2), and duplicate sibling keys (§14.3).

Implementation Guidance

§15 Security Considerations: Injection risks, quoting rules, and strict-mode checks relevant to security.

§16 Internationalization: Unicode handling and locale-independent number formatting.

§17 IANA Considerations: Media type registration plans and provisional status.

§18 Versioning and Extensibility: How the spec evolves: major vs minor bumps and the extensibility policy.

§19 Intellectual Property Considerations: Licensing and IP terms for the specification.

Appendix F: Host Type Normalization Examples: Non-normative guidance for Go, JavaScript, Python, Rust, and Java implementations on normalizing language-specific types.

Appendix C: Test Suite and Compliance: Reference test suite at github.com/toon-format/spec/tree/main/tests for validating implementations.

Spec Sections at a Glance

Section	Topic	When to Read
§1–4	Data model, normalization, decoding	Implementing encoders/decoders
§5–6	Syntax, headers, root form	Implementing parsers
§7	Strings, keys, quoting, escaping	Implementing string handling
§8–10	Objects, arrays, list items	Implementing structure encoding
§11–12	Delimiters, indentation, whitespace	Implementing formatting and validation
§13	Conformance and options	Implementing options and features
§14	Strict-mode errors	Implementing validators
§15–16	Security, internationalization	Operational considerations
§17–19	IANA, versioning, IP	Ecosystem and licensing

Conformance Checklists

The spec includes three conformance checklists:

Encoder Checklist (§13.1) ^{↗ SPEC.md}

Key requirements:

• Produce UTF-8 with LF line endings
• Use consistent indentation (default 2 spaces, no tabs)
• Escape \\, \", \n, \r, \t in quoted strings, and use \uXXXX for any other U+0000–U+001F control character; lone surrogates are rejected
• Quote strings with active delimiter, colon, or structural characters, and strings starting with - or #
• Emit array lengths [N] matching the actual item or entry count
• Preserve object key order
• Emit numbers per §2 (canonical decimal in [1e-6, 1e21) or zero; exponent form permitted outside)
• Convert -0 to 0, NaN/±Infinity to null
• Emit booleans and null as lowercase literals (true, false, null)
• No trailing spaces or trailing newline
• Never emit comment lines

Decoder Checklist (§13.2) ^{↗ SPEC.md}

Key requirements:

• Strip full-line comment lines in a lexical pre-pass (§5.1)
• Parse array and keyed headers per §6 (length, keyed marker, delimiter, fields including nested field groups)
• Split inline arrays, tabular rows, and keyed entry rows using active delimiter only
• Unescape quoted strings with only valid escapes
• Type unquoted primitives: true/false/null → booleans/null, numeric → number, else → string
• Enforce strict-mode rules when strict=true
• Preserve array order and object key order

Validator Checklist (§13.3) ^{↗ SPEC.md}

Validators should verify:

• Structural conformance (headers, indentation, list markers)
• Whitespace invariants (no trailing spaces/newlines)
• Delimiter consistency between headers and rows
• Row, item, and entry counts match declared [N]
• All strict-mode requirements

Versioning

The spec uses semantic versioning (major.minor):

• Major version (e.g., v2 → v3): Breaking changes, incompatible with previous versions
• Minor version (e.g., v3.1 → v3.2): Clarifications, additional requirements, or backward-compatible additions

See Appendix D: Document Changelog for detailed version history.

Contributing to the Spec

The spec is community-maintained at github.com/toon-format/spec. We welcome contributions of all kinds: reporting ambiguities or errors, proposing clarifications and examples, adding test cases to the reference suite, or discussing edge cases and normative behavior. Your feedback helps shape the format.