Introducing TOON: The Token-Oriented Object Notation

In the age of Large Language Models (LLMs), every token counts. JSON has been the de-facto standard for data exchange for decades, but it wasn't built for the token-constrained world of AI. Enter TOON (Token-Oriented Object Notation) a new, schema-aware data serialization format specifically designed to optimize structured data exchange with LLMs.

Why TOON?

JSON is verbose. Braces, quotes, and commas add significant overhead when you are paying per token or limited by context windows. TOON adopts a minimalistic, indentation-based syntax that removes this clutter, resulting in 30-60% token savings for uniform datasets.

TOON vs JSON: A Comparison

Let's look at a simple example. Here is a list of users in JSON:

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

How TOON Syntax Works

TOON is designed to be as minimal as possible while retaining structure. It supports three delimiter modes to fit your workflow:

1. Pipe Mode (Default)

Ideal for clean, visually separated data.

• Arrays: [count]{key1|key2}| followed by rows.
• Objects: key|value.

2. Comma Mode (CSV-style)

Great for compactness and familiarity with CSV tools.

• Arrays: [count]{key1,key2}, followed by rows.
• Objects: key,value.

3. Tab/Standard Mode (YAML-like)

Best for readability, resembling YAML but more compact.

• Arrays: [count]{key1,key2}: followed by rows.
• Objects: key: value.

Comparative Example

Original JSON:

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

TOON (Pipe Mode):

[2]{id|name|role}|
  1|Alice|admin
  2|Bob|user
                    

TOON (Tab/Standard Mode):

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

Notice the difference? TOON leverages a tabular structure for arrays of objects, eliminating repetitive keys and punctuation. This not only saves tokens but also makes it easier for LLMs to parse and understand the structure.

Key Benefits

• Token Efficiency: Reduce API costs and latency by sending fewer tokens.
• Human Readability: Clean, tabular, and indentation-based syntax.
• LLM Optimized: Designed to align with how models process information.
• Schema-Aware: Improved reliability in data extraction tasks.

Getting Started

Ready to optimize your AI workflows? You can install the TOON package via npm:

npm install @toon-format/toon

When to Use TOON

Perfect For:

• LLM Communication: Sending structured data to AI models where every token costs money
• Uniform Data: Arrays of objects with consistent structure (databases, logs, reports)
• High-Volume Scenarios: When processing millions of records, token savings compound
• Context Window Optimization: Fitting more data into limited model contexts

Stick with JSON For:

• Web APIs: JSON is the universal standard for REST/GraphQL APIs
• Highly Nested Data: Complex, irregular structures where TOON's tabular format doesn't fit
• Human-Edited Configs: When developers need to manually edit configuration files
• Browser Storage: localStorage, sessionStorage expect JSON strings

TOON Syntax Deep Dive

Array Header Format

The array header [count]{keys} tells the parser:

• How many rows to expect
• What keys each row contains
• What delimiter separates values

Object Format

For single objects or nested structures, TOON uses key-value pairs:

name|Alice
age|30
role|admin
                    

Nested Structures

TOON supports nested objects using indentation:

user|Alice
  profile|
    email|alice@example.com
    role|admin
                    

Real-World Example

Consider a customer database with 10,000 users. Sending this to an LLM for analysis:

• JSON: ~250,000 tokens (repetitive keys, punctuation)
• TOON: ~100,000 tokens (header once, values only)
• Savings: 60% reduction = significant cost savings

Try TOON Now

You can convert between JSON and TOON using our JSON to TOON Converter and TOON to JSON Converter. These tools help you:

• See token savings in real-time
• Test different delimiter modes
• Understand TOON syntax through examples
• Convert data for use in AI workflows

Conclusion

As we build more complex AI agents and applications, efficiency becomes critical. TOON offers a pragmatic solution to the token bloat problem, helping you build faster, cheaper, and smarter AI systems. While JSON remains the standard for web APIs, TOON is the logical choice for LLM communication where every token matters.

Start optimizing your AI workflows today. The token savings will compound, and your models will process more data within the same context windows.