Token-Oriented Object Notation

Token-Oriented Object Notation
Filename extension	.toon
Internet media type	text/toon
Type of format	Data serialization
Extended from	JSON
Website	toonformat.dev

Token-Oriented Object Notation (TOON) is a text-based data serialization format designed to represent structured data in prompts for large language models (LLMs). It uses indentation for nested objects and a tabular layout for arrays of uniform objects. Its aim is to reduce token consumption compared with JSON while preserving the same data model and allowing conversion between the formats.

TOON can use fewer tokens than JSON when representing large arrays of similar records, but its efficiency depends on the data structure. In April 2026, Thoughtworks included TOON in the "Assess" ring of its Technology Radar and recommended testing it against alternatives with representative workloads.

History

TOON was released as an open-source project on GitHub in 2025 under the MIT License. InfoQ reported on 23 November 2025 that version 1.0 had been released about two weeks earlier.

Syntax

TOON documents use UTF-8 encoding. The format combines an indentation-based layout for nested objects with a comma-separated layout for uniform arrays, resembling aspects of YAML and CSV. Strings do not require quotation marks unless they contain structural characters. TOON is generally generated by converting existing JSON data rather than written by hand.

A single object is written as lines of key: value pairs, with nested objects indented beneath their parent key. Arrays of primitive values can be written inline with a length prefix, as in friends[3]: ana,luis,sam.

TOON's distinguishing feature is its tabular representation of uniform arrays of objects whose fields contain primitive values. The field names appear once in a header, followed by one row per object. For example, this JSON document:

{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob",   "role": "user"  }
  ]
}

can be represented in TOON as:

users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user

The [2] declares the array length, and the {id,name,role} header gives the field order. TOON also supports alternative row delimiters, including tabs and pipes.

Arrays containing nested structures or non-uniform elements use an expanded list form, with each element introduced by a hyphen. Inner arrays of uniform objects can still use the tabular layout:

departments[2]:
  - name: Engineering
    members[2]{name,age}:
      Alice,28
      Bob,34
  - name: Marketing
    members[2]{name,age}:
      Eve,29
      Frank,45

Expanded lists repeat field names for each object and can therefore offer fewer token savings than tabular arrays.

Token efficiency and comparison with other formats

TOON aims to reduce the overhead of JSON, particularly in large arrays of records with repeated field names. Published benchmarks have reported lower token counts than JSON in some cases, but the reported savings vary with the data and test method. One comparison found reductions against both pretty-printed and compact JSON, while other tests have reported smaller gains or no advantage for particular structures. These results are not directly interchangeable because they use different inputs and comparison conditions.

TOON is less advantageous for irregular or deeply nested data, where JSON or YAML may be more compact. CSV can use fewer tokens for flat data, while JSON has a broader tooling ecosystem and established validation options such as JSON Schema. TOON is therefore primarily an option for formatting data sent to LLMs, rather than a general replacement for JSON in APIs, storage, or exchanges between software systems. Token count is not the only consideration: model accuracy, latency, parsing requirements, and interoperability may also affect the choice of format.

Research and evaluation

An arXiv preprint by Ivan Matveev compared TOON generation with plain JSON generation and JSON generation using constrained decoding. The study reported that plain JSON achieved the highest accuracy in the tests, while constrained decoding often used fewer tokens for simple structures. TOON's results depended on output complexity and the instructions needed to teach the model its syntax, which the author called the "prompt tax". The study examined model generation of TOON, rather than only the use of TOON as input, and its findings concern that specific task.

The Thoughtworks Technology Radar described TOON as a possible optimization for large, regular datasets, while cautioning against its use for deeply nested or non-uniform structures and latency-critical paths. It recommended benchmarking TOON against JSON and CSV with an organization's own data and model stack.

Implementations

The reference implementation is a TypeScript library published on npm as @toon-format/toon, which provides encoding and decoding functions and a command-line converter. Implementations are also available in languages including Python, Go, Rust, and Java. Java implementations include JToon and json-io, which supports TOON serialization in addition to JSON.

See also

• JSON
• YAML
• Comparison of data-serialization formats

References

Category:Data serialization formats Category:Open formats Category:Large language models Category:Computer file formats Category:2025 introductions