Question 1

What does TOON stand for?

Accepted Answer

TOON stands for Token-Oriented Object Notation. It's a compact, human-readable serialization format designed specifically for passing structured data to Large Language Models while significantly reducing token usage compared to JSON.

Question 2

How is TOON different from JSON?

Accepted Answer

TOON achieves 30-60% fewer tokens than JSON by removing redundant punctuation (braces, brackets, most quotes) and using an indentation-based structure similar to YAML. For uniform arrays of objects, TOON uses a tabular format that's dramatically more compact. However, JSON remains better for non-uniform data and deeply nested structures.

Question 3

When should I use TOON instead of JSON?

Accepted Answer

Use TOON when you have uniform arrays of objects with the same structure (TOON's sweet spot), especially for large datasets. If token costs matter to your use case, TOON reduces them significantly. For small payloads or non-uniform data, JSON works fine.

Question 4

Is TOON a replacement for JSON?

Accepted Answer

Not entirely. TOON is a translation layer: use JSON programmatically, convert to TOON for LLM input. TOON is optimized for LLM contexts, not general-purpose APIs or storage systems.

Question 5

How do I install TOON?

Accepted Answer

You can install TOON via npm, pnpm, or yarn:
- npm: npm install @toon-format/toon
- pnpm: pnpm add @toon-format/toon
- yarn: yarn add @toon-format/toon

Question 6

How do I use TOON in my project?

Accepted Answer

Import the encode and decode functions:
import { encode, decode } from '@toon-format/toon'
const toon = encode(data)
const original = decode(toon)

Question 7

Can I use TOON from the command line?

Accepted Answer

Yes! Use the CLI tool: npx @toon-format/cli [options] [input]. It automatically detects whether you're encoding JSON or decoding TOON based on file extension.

Question 8

What does TOON output look like?

Accepted Answer

Here's a simple example comparing JSON and TOON:

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

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

Question 9

What's the tabular format?

Accepted Answer

When all objects in an array share the same primitive fields, TOON uses a compact tabular format. The header declares the array length [N] and field names {field1,field2}, then each row contains only the values, comma-separated.

Question 10

Do I need to quote strings in TOON?

Accepted Answer

TOON quotes strings only when necessary to maximize token efficiency. Leading/trailing spaces, special characters, and values that look like booleans or numbers require quotes. Most regular strings don't need quotes.

Question 11

What are the main advantages of TOON?

Accepted Answer

TOON offers four key advantages: (1) Token-efficient (30-60% fewer tokens than JSON), (2) LLM-friendly with explicit length markers and field headers for validation, (3) Minimal syntax with removed redundant punctuation, and (4) Indentation-based structure like YAML.

Question 12

How much can I save on tokens with TOON?

Accepted Answer

Token savings vary by data structure and model. Benchmarks show 30-60% reduction compared to formatted JSON. For large GitHub repository data, TOON used 8,745 tokens vs JSON's 15,145 (42.3% savings). For analytics data, TOON used 4,507 tokens vs JSON's 10,977 (58.9% savings).

Question 13

How accurate are LLMs with TOON data?

Accepted Answer

Benchmarks across four LLMs (gpt-5-nano, Claude Haiku, Gemini 2.5 Flash, Grok-4 Fast) show TOON achieves 70.1% accuracy while using 46.3% fewer tokens than JSON's 65.4% accuracy. TOON often outperforms other formats in retrieval accuracy.

Question 14

How should I present TOON data to LLMs?

Accepted Answer

TOON works best when shown rather than described. Wrap encoded data in a fenced code block labeled ```toon. The indentation and headers are self-documenting – models parse it naturally once they see the pattern. Explicit length markers ([N]) and field headers help models track structure for large tables.

Question 15

How do I prompt an LLM to generate TOON output?

Accepted Answer

Show the expected header and state the rules:
- Show the header format: users[N]{id,name,role}:
- State the rules: "2-space indent, no trailing spaces, [N] matches row count"
- Ask for TOON format explicitly
- Request only the code block as output

Question 16

What are TOON's main limitations?

Accepted Answer

TOON works best with uniform arrays of objects having primitive values only. When data is non-uniform (mixed types, varying field sets) or deeply nested, TOON switches to list format where JSON may be more efficient. CSV is more compact for flat tables without nesting.

Question 17

Is TOON suitable for all data structures?

Accepted Answer

No. TOON excels at uniform arrays of objects with identical keys and primitive values. JSON is better for non-uniform data, deeply nested structures, and objects with varying field sets. CSV is better for flat, uniform tables.

🔄 Format Converters

🛠️ Utilities

🔗 Resources

☕ Support

Modern Data SerializationBuilt for Blockchain

JSON (Traditional)

Toon (Optimized)

What is Toon?

Efficient by Design

Type-Safe

Human-Readable

Why Toon?

JSON is Too Verbose

Protocol Buffers Too Complex

CBOR Lacks Adoption

Compact & Efficient

Developer-Friendly

Blockchain-Native

Key Features

Compact Encoding

Schema Support

Zero Dependencies

Fast Parsing

Blockchain-Ready

Open Source

Developer Tools

🔄 Format Converters

JSON to Toon

XML to Toon

YAML to Toon

CSV to Toon

🛠️ Utilities

✓ Toon Validator

📊 Size Calculator

Frequently Asked Questions

What is TOON?

Getting Started

Format Basics

Key Features

Working with LLMs

Limitations

Ready to Get Started?

Modern Data Serialization
Built for Blockchain