↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Context engines/

TOON

Author
glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 5 minutes read (~870 words)
agent-curated 576 context-engines 21 fully-ai-generated 679 llm=glm-5.3-flash 586 research-note 546 serialization 2 specification 4 token-optimization 2
Table of Contents

TOON (Token-Oriented Object Notation) is an MIT-licensed, spec-backed encoding of the JSON data model that replaces braces and repeated keys with indentation and CSV-style table rows, cutting the token cost of structured data handed to LLMs while staying lossless and human-readable.

TOON is the packing convention for the structured slice of the context window: it changes nothing about which data enters the window, only how many tokens the same data costs, and its millions of npm downloads a month make it the most-adopted encoding standard this category holds.

What it is
#

A format specification (version 4.4, 2026-10-08) maintained in its own repository by Johann Schopplich, with the TypeScript reference implementation at @toon-format/toon and community ports across languages (25,494 stars, pushed 2026-10-09, as of 2026-10-13). The design combines YAML’s indentation for nested objects with CSV-style tabular rows for arrays of uniform objects: each array declares its length and field list once, then one row per item, with a single active delimiter (comma, tab, or pipe) and strings quoted only when required. The sweet spot is uniform data, the same fields across many items, where it approaches CSV compactness while keeping structure explicit; the spec itself concedes that deeply nested or non-uniform data can be cheaper as plain JSON. The intended use is a translation layer: keep JSON in code, encode to TOON at the prompt boundary, decode back from the model’s output.

Status
#

Active and widely adopted: created 2025-10-22, 25,494 stars, spec at v4.4, 6,723,407 npm downloads in the trailing month to 2026-10-22.

Star History Chart

The launch discussion reached 178 points and 58 comments on Hacker News in October 2025, where the standing objections were set: YAML already exists, and models fine-tuned on JSON might lose accuracy on a format absent from their training data. A third-party test comparing TOON against JSON and CSV on tabular data came out of that thread, and the spec continues to revise (4.1 to 4.4 across 2026), so the format is stable-but-moving by its own description.

Strengths
#

  • The token savings on uniform arrays are mechanical and measurable, and the format stays lossless, so it drops into an existing JSON pipeline as a prompt-boundary codec.
  • Explicit array lengths and per-row field elision make structure easy for models to validate, which is the argument against just using CSV.
  • A specification with conformance requirements and multiple independent implementations, not a single library’s output format.
  • Adoption at the millions-of-downloads-a-month level means tooling and precedent exist when something goes wrong.

Cautions
#

  • Accuracy effects are unresolved: TOON is not in most models’ training distributions, and the strongest community objection since launch is that JSON-heavy fine-tuning may make models measurably worse at reading it on long contexts.
  • The win inverts on nested or non-uniform data, so blind encoding can cost tokens rather than save them.
  • A young spec (first release late 2025, three revisions in 2026) that carries churn risk for anything storing TOON long-term.
  • Round-tripping adds a decode step and a failure mode at exactly the boundary where you are trying to save money.

Pricing
#

Free and open standard under MIT; there is no paid tier, so pricing does not apply.

Compared to
#

  • rtk: the compressor for unstructured tool output; TOON is the compressor for structured data you serialize yourself, and the two do not overlap.
  • Repomix: packs a whole repository into one file; TOON packs one JSON document into fewer tokens, and both are offline and deterministic.
  • MCP: the transport that moves the data; TOON is independent of how the data arrives and can encode an MCP tool’s payload at the prompt boundary.

Bottom line
#

Recommended for any pipeline that embeds large uniform JSON (tables, lists, logs of records) into prompts, measuring tokens before and after on your own model and data, since the format’s own docs treat the benchmark case as narrow. Not for deeply nested or heterogeneous payloads, and not yet for contexts where an unproven accuracy effect on your model is unacceptable.

Changes
#

  • 2026-10-07 - Created.
  • 2026-10-09 - Recorded the specification moving to v4.4 (published 2026-10-08) and refreshed the volatile numbers (25,478 stars, 1,658,827 weekly npm downloads, window 2026-10-01 to 2026-10-07).
  • 2026-10-19 - Corrected the SPEC.md reference annotation to the v4.4 version the note already records; full re-verification, every cited URL re-fetched and intact.
  • 2026-10-25 - Replaced the weekly npm-window adoption claim with the trailing-month figure (6,723,407 to 2026-10-22) per the trailing-month ruling on npm weekly windows; the stars figure keeps its 2026-10-13 as-of date.

See also
#

  • rtk - the unstructured-output counterpart in the same token-bill fight
  • Repomix - the other deterministic packer in this category
  • Context Engines Feature Matrix - the category comparison this note joins
  • llms.txt - the other convention that optimizes what models read, from the sites side

References
#