TOON vs JSON: A Reality Check — When It Saves Tokens and When It Doesn't

Source: Dev.to

Introduction

There’s been a wave of articles lately about TOON (Token‑Oriented Object Notation), many proclaiming it saves “50 % tokens” or calling JSON “outdated” for LLM applications. After analyzing the actual numbers, the verdict is clear:

• TOON is genuinely useful, but the marketing oversimplifies reality.
• The “50 % savings” figure is usually measured against formatted (pretty‑printed) JSON, not the minified JSON that is actually sent to LLMs.

When you compare against minified JSON—the real‑world baseline—the picture changes dramatically.

Token‑Savings Overview

Key takeaway: TOON can increase token usage by 15‑20 % depending on your data structure.

How TOON Saves Tokens

TOON declares field names once in a header and then streams values in CSV‑like rows for uniform arrays.

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

Equivalent minified JSON

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

The savings come from not repeating "id":, "name":, and "role": for every record. With 100 records the token reduction becomes significant.

When TOON Becomes Less Efficient

For non‑tabular data TOON falls back to a YAML‑style indentation, which can be more verbose than minified JSON because:

• Whitespace (indentation) consumes tokens.
• Keys still repeat for each nested object.
• Small objects incur more overhead than JSON’s compact braces.

Example: Configuration Object

Minified JSON

{"debug":true,"maxRetries":3,"timeout":5000,"features":{"darkMode":true,"beta":false}}

TOON representation

debug: true
maxRetries: 3
timeout: 5000
features:
  darkMode: true
  beta: false

The minified JSON is more token‑efficient because it has no newlines or indentation, and its punctuation tokens are already minimal.

Practical Guidance: When to Use Which Format

Use TOON when

• You have large arrays of uniform objects (≈ 100+ records with consistent fields).
• Your data is primarily tabular (user lists, product catalogs, log entries, analytics data).
• Every object in the array shares the same fields.

Use JSON (minified) when

• You are processing paginated API results that include metadata alongside arrays.
• Your data has deep nesting (org charts, recursive trees).
• You are sending configuration objects or feature flags.
• Objects have varying fields (sparse data).
• You have mixed structures (some arrays, some nested objects).
• You are dealing with single flat objects.

Consider plain CSV when

• Your data is purely tabular with no hierarchy.
• You need maximum token efficiency (CSV beats TOON by ~30 % for flat tables).

YAML vs. JSON vs. TOON

• YAML is typically the worst choice for token efficiency, using ~21 % more tokens than minified JSON because whitespace carries meaning and keys repeat for every array item.
• JSON remains the most compact for most nested or mixed structures.
• TOON provides a tabular optimization that JSON lacks, but only when the data fits that pattern.

LLM Compatibility Considerations

• Most LLMs were trained predominantly on JSON.
• Using TOON often requires format explanations in prompts, which partially negates token savings.
• Smaller models (e.g., gpt‑3.5‑turbo) sometimes struggle to output valid TOON even when they understand TOON input.
• TOON lacks an RFC‑level standard; implementations may vary, making debugging harder than with JSON.
• Existing tools, loggers, and validators expect JSON, so integrating TOON can add friction.

Real‑World API Response Example

{"total":150,"page":1,"users":[...]}

Only the users array benefits from TOON optimization; the surrounding metadata (total, page) does not. The overhead of TOON’s format declarations for the small metadata objects can actually increase total tokens.

Recommendations

1. Test with real data – paste your production payloads into a converter (e.g., json2toon.de) and compare token counts.
2. Always compare against minified JSON, not pretty‑printed JSON.
3. Profile your specific structure – uniform arrays save tokens; config objects don’t.
4. Include any format‑explanation prompts in your token calculations.
5. Verify LLM comprehension – ensure the target model can reliably parse and generate TOON.

Conclusion

• Uniform arrays → TOON (20‑35 % token savings).
• Flat tabular data → CSV (up to ~30 % savings).
• Everything else → Minified JSON (most token‑efficient and widely supported).

Don’t let hype drive your architecture decisions. Measure your specific use case, understand the trade‑offs, and choose the format that truly minimizes token usage for your workload.

Built json2toon.de to help developers make data‑driven format decisions. Try it with your real payloads and see the actual numbers.