TOON Format Grammar: A Complete Overview

TOON is intentionally small. The full grammar fits on a coffee-stained napkin, but the corner cases matter when you start writing parsers or generating test fixtures.

Top-level shape

A TOON document is a sequence of tables separated by blank lines. Each table is either a list of records, a flat key-value object, or a scalar.

Indentation

TOON uses 2-space indentation. Tabs are forbidden. Mixing tabs and spaces is a parse error, not a warning.

Headers

Headers declare column names and optional types: id[int] name[str] created[iso]. The type tag is informational; parsers must not silently coerce on read.

Key-value rows

Objects are written as key: value. Strings may be unquoted if they contain no colon, leading/trailing space, or #. Otherwise wrap in double quotes and escape with backslash.

Comments

Lines beginning with # (after optional whitespace) are comments and must be preserved by readers that support round-tripping.

Error surface

Good TOON parsers fail loud with line and column on the first structural problem, not at end-of-file. Streaming parsers should expose the same error channel.

For dataset authors, the takeaway is simple: keep your tables short, name columns explicitly, and let the parser tell you exactly where you broke it.