Frequently Asked Questions

Common questions about TOON format and how to use it effectively.

General Questions

What is TOON?

TOON (Token-Oriented Object Notation) is a compact, human-readable encoding of the JSON data model designed to minimize token usage for LLM input while maintaining full lossless round-trip conversion.

How much can I save?

Token savings depend on your data structure:

  • Uniform arrays of objects: 40-60% savings
  • Mixed structures: 20-40% savings
  • Deeply nested objects: 10-30% savings
  • Pure flat tables: Use CSV instead (~5-10% smaller than TOON)

Is TOON lossless?

Yes! TOON encodes the same data model as JSON with 100% lossless round-trip conversion. You can convert JSON → TOON → JSON without any data loss.

Can I use TOON instead of JSON everywhere?

TOON is best for:

  • ✅ LLM prompts and responses
  • ✅ Data-heavy API responses
  • ✅ Log files and analytics data
  • ✅ Configuration files with tabular data

Consider JSON for:

  • ❌ Browser APIs (limited support)
  • ❌ Databases (most expect JSON)
  • ❌ Legacy systems

Is TOON a standard?

TOON is an open format with a full specification. Multiple language implementations exist (TypeScript, Python, Go, Rust, .NET, Ruby, PHP, and more).

Technical Questions

What's the difference between TOON and YAML?

TOON is optimized specifically for token efficiency:

  • TOON: Tabular arrays, length declarations, field headers
  • YAML: More features (anchors, tags, multi-line), but less token-efficient

TOON saves ~5-15% more tokens than YAML on uniform arrays.

What's the difference between TOON and CSV?

  • CSV: Pure flat tables only, no nesting, no structure
  • TOON: Supports nested objects, mixed data types, multiple arrays in one document

TOON is ~5-10% larger than CSV for pure flat tables but adds structural guarantees that help LLMs parse data correctly.

Can I use TOON with any LLM?

Yes! TOON works with all LLMs:

  • GPT-4, GPT-5
  • Claude (all versions)
  • Gemini
  • Llama models
  • Local/open source models

No special model training required - models parse TOON naturally after seeing the format once.

Does TOON support comments?

Currently, no. The TOON specification does not include comments. If you need to document your data, use separate documentation or add a _comment field in your objects.

What character encoding does TOON use?

TOON uses UTF-8 encoding, just like JSON.

Usage Questions

Should I use comma or tab delimiters?

For production/LLMs: Use tab delimiters for ~5-10% extra token savings.

For human readability: Use comma delimiters (default).

Use our Minifier tool for maximum compression with tab delimiters.

How do I handle special characters?

Quote strings that contain special characters:

name: "John, Jr."
message: "Value: 100"
key: "data[0]"

The converter handles this automatically.

What if my array isn't uniform?

TOON falls back to inline arrays for non-uniform data:

mixed[3]: 1,"text",true

Or each item on its own line:

items[3]:
  - first_item
  - second_item
  - third_item

Can I nest arrays?

Yes! Arrays can contain objects with nested arrays:

departments[2]{name,employees}:
  Engineering,"[alice,bob,carol]"
  Sales,"[dave,eve]"

Or use nested object syntax:

departments[2]:
  -
    name: Engineering
    employees[3]: alice,bob,carol
  -
    name: Sales
    employees[2]: dave,eve

How do I validate TOON syntax?

Use the Validator Tool on this site to check your TOON data for syntax errors.

Performance Questions

Is TOON fast?

Yes! TOON conversion is very fast:

  • Small files (under 1MB): Instant
  • Medium files (1-10MB): Under 1 second
  • Large files (over 10MB): Streaming supported

Does TOON work in the browser?

Yes! All conversions on this site run directly in your browser for privacy and speed.

Can I use TOON with LLMs like ChatGPT?

Yes! Simply convert your JSON data to TOON using our Converter, then paste the TOON output into your LLM prompt. This reduces token usage and can improve model comprehension of structured data.

Can I store TOON in a database?

Yes! TOON is plain text, so you can store it in any text/varchar column just like you would store JSON.

Troubleshooting

My conversion is failing

Common issues:

  1. Invalid JSON input: Validate your JSON first
  2. Special characters: Ensure strings with special chars are quoted
  3. Mixed data types: Check array uniformity
  4. File encoding: Ensure UTF-8 encoding

Use the Validator to debug.

Token savings are less than expected

TOON works best with:

  • ✅ Uniform arrays of objects (many items, same structure)
  • ✅ Short field names
  • ✅ Tab delimiters
  • ✅ Minimal nesting

If savings are low, your data might be:

  • ❌ Deeply nested objects
  • ❌ Non-uniform arrays
  • ❌ Very small datasets

Decoded data doesn't match original

TOON is lossless, but check:

  1. Number precision: Very large numbers may lose precision (use strings)
  2. Undefined values: Use null instead of undefined
  3. Special types: Date objects → ISO strings, RegEx → strings

Need More Help?

Check out our other documentation pages: