Frequently Asked Questions

TOON (Token-Oriented Object Notation) is a compact, human-readable encoding of the JSON data model specifically designed for Large Language Models. It was created to address the token inefficiency of standard JSON when used in LLM applications.

Traditional JSON, while excellent for APIs and human readability, is verbose with its braces, quotes, and repeated keys. Every token costs money in LLM applications, and context windows have limits. TOON reduces token usage by 30-60% on uniform datasets while maintaining full JSON compatibility and human readability.

No, TOON is not a replacement for JSON. It's a specialized encoding format optimized for a specific use case: passing structured data to Large Language Models.

Think of it as a translation layer: you continue using JSON in your application code, APIs, and storage. When you need to pass data to an LLM, you encode it as TOON to save tokens. When the LLM returns TOON data, you decode it back to JSON.

Token savings depend heavily on your data structure:

LLMs were not trained specifically on TOON, but they generally understand it well because:

• Familiar patterns: TOON combines YAML-like indentation with CSV-style tables, both of which are common in training data
• Clear structure: Explicit array lengths and field declarations make the structure obvious
• Human-readable: The format is intuitive enough that models can infer the pattern from examples

Benchmark results show LLMs achieve 73.9% accuracy on TOON data retrieval tasks compared to 69.7% for JSON, suggesting models may actually parse TOON more reliably than JSON in some contexts.

Install the official NPM package:

Converting JSON to TOON:

import { encode } from "@toon-format/toon";

const data = {
  users: [
    { id: 1, name: "Alice", role: "admin" },
    { id: 2, name: "Bob", role: "user" }
  ]
};

const toonString = encode(data);
console.log(toonString);

Converting TOON back to JSON:

import { decode } from "@toon-format/toon";

const toonString = `
users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user
`;

const jsonObject = decode(toonString);

Install the Python package:

Encoding JSON to TOON:

from toon import encode

# A channel object
channel = {"name": "tapaScript", "age": 2, "type": "education"}
toon_output = encode(channel)
print(toon_output)

Decoding TOON back to JSON:

from toon import decode

toon_string = """
name: tapaScript
age: 2
type: education
"""

python_struct = decode(toon_string)
print(python_struct)

No, TOON is typically generated programmatically. Most TOON data will be:

• Automatically generated by software using the encode functions
• Converted from existing JSON data before sending to LLMs
• Created by AI models when asked to output in TOON format

While TOON is human-readable and can be written manually, the main workflow is to convert your existing JSON data to TOON programmatically, especially when preparing prompts for LLMs.

TOON currently has official implementations for:

The format is designed to work well with Go, Rust, and other languages, with more implementations expected as the format gains adoption.

TOON is ideal for:

TOON is being explored for:

• Training Data: Reducing token overhead for structured training data in LLM fine-tuning
• Agent Frameworks: Compact data exchange in multi-agent AI systems
• MCP & AI Workflows: Faster data serialization between Model Context Protocol and AI workflow engines
• Serverless AI APIs: Cost and speed optimization in serverless environments
• RAG Systems: Efficient retrieval-augmented-generation with large knowledge bases
• Few-Shot Learning: Providing more examples within the same token budget

Absolutely! A hybrid approach often works best:

This gives you the best of both worlds: JSON's universal compatibility for regular use, and TOON's efficiency when communicating with AI models.

JSON might be better when:

Yes, in certain cases TOON can be less efficient than compact JSON. This typically happens with:

• Deeply nested structures: Multiple levels of nesting can add overhead with TOON's indentation
• Small datasets: Very small objects might not benefit enough to offset the schema declaration
• Highly irregular data: When objects in an array have mostly different fields

TOON is NOT a replacement for JSON in traditional web/API contexts:

• Browsers don't natively parse TOON (no TOON.parse())
• REST APIs expect JSON as the standard format
• Databases store JSON, not TOON
• Most tooling and libraries are built around JSON

TOON is specifically designed for LLM communication, not as a general-purpose data format. You'll need to convert between JSON and TOON programmatically when interfacing with AI models.

TOON is in active development with specification v2.0 released. Consider these factors:

Many teams are successfully using TOON in production for AI workflows, but it's wise to test thoroughly and maintain JSON as a fallback option.

TOON is gaining traction in the AI developer community with potential for:

• Standardization: Just as JSON became the Web's data exchange standard, TOON could become the standard for AI data interchange
• Native LLM Support: Future LLMs may be trained with TOON examples or have built-in TOON parsing
• Expanded Tooling: More libraries, converters, and integrations across different languages
• Framework Integration: Direct TOON support in popular AI frameworks like LangChain, LlamaIndex, etc.
• Specification Evolution: Community-driven improvements through the RFC process

TOON is an open-source project with an active community:

Here's a quick start guide: