How TOON Handles Nested and Non-Uniform Data

TOON handles nested data using YAML-style indentation for objects and CSV-style tabular rows for uniform arrays. Token savings are highest on flat data (58.8% vs JSON) and shrink with nesting depth — down to 33.3% for e-commerce orders and 21.9% for mixed structures. For highly non-uniform or very deep nesting, JSON or YAML win.

How TOON Represents Nested Data

TOON was designed by Johann Schopplich and contributors around two complementary syntaxes. For uniform arrays of objects — the case where TOON excels — it uses a CSV-style tabular block: a single header line that declares the array length and field names, followed by one plain-value row per object. For nested objects and non-uniform structures, it falls back to YAML-style indentation.

The header line for a tabular block looks like orders[3]{id,customer,total}:. That one line gives the LLM an explicit schema and a row count to validate against — roughly 5% overhead above the theoretical minimum, traded for higher extraction accuracy. When an object property is itself an object rather than a scalar, TOON indents it beneath the parent key using the same whitespace-significant convention as YAML.

This two-mode design means TOON is not a single homogeneous format but a hybrid that picks the right representation for each sub-structure. The practical consequence is that savings depend on how much of your payload is uniform-array versus irregular-object.

JSON vs TOON on a Nested Object: A Concrete Example

Consider an order object that contains a uniform array of line items. Here is the same data expressed as JSON and then as TOON:

// JSON — nested object with a uniform array inside
{
  "order_id": "ORD-9041",
  "customer": "Priya Nair",
  "status": "shipped",
  "items": [
    {"sku": "HDMI-4K", "qty": 2, "unit_price": 14.99},
    {"sku": "USB-C-HUB", "qty": 1, "unit_price": 39.99},
    {"sku": "PATCH-CAT8", "qty": 3, "unit_price": 8.49}
  ]
}

// TOON — outer object uses YAML-style indentation;
// inner uniform array uses a tabular block
order_id: ORD-9041
customer: Priya Nair
status: shipped
items[3]{sku,qty,unit_price}:
  HDMI-4K, 2, 14.99
  USB-C-HUB, 1, 39.99
  PATCH-CAT8, 3, 8.49

The outer object (four scalar fields) gets YAML-style key-value pairs — TOON does not try to tabularize it because there is only one object, not a repeating array. The inner items array is uniform (three objects, same three fields), so it becomes a tabular block. That inner block saves roughly 50% on the array portion. The outer object saves less because there is nothing to amortize the key names across.

For a deeper look at how TOON compares to JSON on flat data, see the JSON vs TOON token comparison.

Token Savings by Data Shape: What the Benchmark Shows

The official toonformat.dev benchmarks ran 5,016 LLM calls across 209 questions, six formats, and four models. Token reduction vs JSON breaks down by data shape as follows:

• Flat uniform tables: 58.8% (67,778 vs 164,452 tokens)
• Time-series (60 days): 59.0% (9,115 vs 22,245 tokens)
• GitHub repo data: 42.3% (8,744 vs 15,144 tokens)
• E-commerce orders (nested): 33.3% (73,126 vs 109,599 tokens)
• Mixed structures: 21.9% (227,830 vs 291,711 tokens)

The e-commerce and mixed categories are the most instructive. E-commerce orders are real-world nested data — a uniform outer array of orders, each containing a nested shipping address and a nested line-items array. Despite the nesting, TOON still saves a third of the tokens because the outer array and the line-items arrays are both uniform. Mixed structures, where objects vary significantly in their field sets, compress the least because TOON cannot exploit tabular repetition.

Overall accuracy held at 76.4% versus JSON's 75.0%, with the efficiency ratio reaching 27.7 accuracy-points per 1,000 tokens compared to JSON's 16.4. That ratio holds across nesting levels because the field retrieval accuracy of 99.6% is measured at the field level, not the document level.

Data Shape, TOON Representation, and Token Reduction: Full Comparison

Source: token reduction figures from the official toonformat.dev benchmark. The "better alternative" column reflects design guidance from the TOON GitHub repository and the arXiv paper 2603.03306.

When Does JSON Beat TOON on Nested Data?

Three conditions push the balance toward JSON. First, highly non-uniform data: if the objects in your array do not share a consistent field set — think a heterogeneous event log where each event type has different keys — TOON cannot form a tabular block and falls back to YAML indentation. At that point the savings shrink to the 21.9% mixed-structure range, and the format-instruction overhead may eat into that.

Second, small payloads. A February 2026 arXiv study (2603.03306) on TOON vs JSON confirmed a scaling threshold: below roughly 10 objects, the token cost of format instructions — explaining TOON's header syntax to an unfamiliar model — can exceed the per-row savings TOON provides. For a three-item nested cart, stick with JSON.

Third, very deep, non-repetitive nesting. A six-level-deep configuration tree where every sub-key is unique offers TOON nothing to tabularize. YAML handles this more naturally and requires no format instructions because every current LLM has seen extensive YAML in training. The YAML vs TOON comparison quantifies the crossover point.

TOON Specification: How Nesting Is Defined Formally

The TOON specification defines two structural primitives. A table block opens with a line matching the pattern name[count]{field1,field2,...}: and is followed by indented comma-separated value rows. A scalar block is a key-value pair using the pattern key: value, identical to YAML. When a value is itself a complex object, the sub-keys are indented one level and follow the same rules recursively. When a value is a uniform array, it becomes a nested table block at the next indentation level.

The result is a format that composes cleanly: an outer table block can contain rows whose cells are themselves table blocks. This is how e-commerce order data achieves 33.3% savings despite nesting — the outer orders array is a table, and the inner line-items array inside each order is also a table. Only the address sub-object, which has no repeating rows, is expressed as YAML indentation.

For the full syntax grammar and edge cases — null values, empty arrays, mixed types within a column — see the toonformat.dev documentation.

Practical Guidance: Choosing a Format by Data Shape

The benchmark numbers map directly onto a decision rule. If your data contains at least one uniform array of objects with ten or more rows, TOON will save a meaningful number of tokens — likely 33% or more. If the top-level structure is a single object with a handful of scalar fields and one small nested array, the savings are modest and may not justify the integration cost.

A useful diagnostic: count the number of times the same key repeats across your payload. In JSON, every key in every object is a token. If the word customer_id appears 500 times in a response, that alone is several hundred tokens of pure overhead. TOON collapses that to a single declaration in the header. The more repetitive your keys, the steeper the savings curve.

For HTML tables scraped from web pages — which are typically uniform and flat — see the companion post on converting HTML tables to TOON for LLM extraction. For a format-agnostic comparison covering JSON, TOON, YAML, CSV, and TONL, the TOON format comparison guide is the most complete reference.

If your nested data also requires schema validation, streaming, or complex queries, consider TONL (Token-Optimized Notation Language), which adds a SQL-like query API, type hints, and 50GB+ streaming on top of similar token savings.

Frequently Asked Questions