TOON (Token-Oriented Object Notation)

TOON (Token-Oriented Object Notation) provides significant savings in both file size and LLM token usage compared to JSON. Across 50 real-world datasets, TOON achieved an average of 63.9% smaller file sizes and 54.1% fewer tokens for LLM APIs.

Key Benefits for LLM Users

• Lower API Costs: Reduces token usage by over half on average.
• Faster Responses: Less data to transmit results in lower latency.
• Increased Context: More data can fit within the LLM's context window.

Performance by Category

TOON reduces size and token counts through three primary mechanisms:

1. Eliminates Repeated Keys in Arrays: Unlike JSON, which repeats keys for every object in an array, TOON declares headers once for the entire collection.
   • JSON Example: [{"id": 1, "name": "Laptop"}, {"id": 2, "name": "Mouse"}]
   • TOON Example: [2]{id,name}: 1,Laptop 2,Mouse
2. Minimal Syntax Overhead: TOON replaces heavy JSON syntax (braces {}, brackets [], quotes around keys/values, and commas) with indentation-based structure (similar to YAML), colons for key-value pairs, and quotes only when strictly necessary.
3. Intelligent Type Handling: Automatically detects and preserves types (numbers, booleans, null) without requiring explicit quotes, maintaining human readability while minimizing tokens.

TOON reduces overhead through three primary mechanisms:

1. Compact Array Representation: Unlike JSON, which repeats keys for every object in an array, TOON declares headers once for uniform arrays.

   • JSON: [{"id": 1, "name": "A"}, {"id": 2, "name": "B"}]
   • TOON: [2]{id,name}: 1,A 2,B

2. Minimal Syntax Overhead: TOON eliminates the need for braces {}, brackets [] (except for array declarations), quotes around all keys, and excessive commas. It uses indentation for structure and colons for key-value pairs.

3. Intelligent Type Handling: TOON automatically detects when quotes are unnecessary and preserves types like numbers, booleans, and null while maintaining human readability.

TOON provides advanced features for managing complex or deeply nested data structures.

Key Folding

Reduces a single key chain into a dot-separated path. Use key_folding='safe' in encode().

data = {'api': {'response': {'product': {'title': 'Wireless Keyboard'}}}}
toon = encode(data, {'key_folding': 'safe'})
# Output: api.response.product.title: Wireless Keyboard

Path Expansion

Expands dot-separated keys back into nested objects. Use expand_paths='safe' in decode().

toon = 'store.location.zipcode: 10001'
data = decode(toon, {'expand_paths': 'safe'})
# Result: {'store': {'location': {'zipcode': 10001}}}

TOON (Token-Oriented Object Notation) is designed to be more efficient than JSON, specifically for LLM contexts.

Use TOON when:

• Passing data to LLM APIs (reduces token costs).
• Working with uniform tabular data.
• Context window is limited.
• Human readability is required.

Use JSON when:

• Maximum compatibility is required.
• Data is highly irregular or deeply nested.
• Working with existing JSON-only tools.

TOON (Token-Oriented Object Notation) is designed to provide massive memory and token savings compared to JSON, particularly for structured and tabular data.

Key Performance Metrics

On average, TOON achieves:

• 63.9% reduction in file size and network bandwidth.
• 54.1% reduction in token count for LLM APIs.

Best Use Cases

TOON excels in the following scenarios:

• Tabular Data (e.g., database results, inventory): Up to 73.4% size reduction.
• Uniform Arrays (e.g., ML training data): Up to 63.4% token savings.
• Structured Records (e.g., e-commerce products): ~66% size reduction.
• Analytics Data (e.g., surveys, metrics): Consistently 65-73% savings.

When to Expect Lower Savings

Savings may be lower (e.g., ~39%) when dealing with deeply nested objects with non-uniform structures.

✅ Use TOON for:

• LLM API Payloads: To cut token costs significantly.
• Database Query Results: Efficiently handling tabular data.
• Analytics & Metrics: Time series and aggregates.
• E-commerce Data: Product catalogs and inventory.
• IoT Sensor Data: Regular, structured readings.
• API Logs & Traces: Structured log entries.
• ML Training Data: Feature vectors and labels.

⚠️ Use JSON for:

• Highly irregular/nested data: While TOON still saves 20-40%, the efficiency is lower than for structured data.
• Maximum compatibility: JSON is the universal standard for web interoperability.
• Microsecond-level performance: JSON parsers are often faster for extremely high-frequency, low-latency requirements.

To set up the repository for development, clone the repo and install the package with the [dev] extra.

git clone https://github.com/ScrapeGraphAI/toonify.git
cd toonify
pip install -e .[dev]

To run the benchmarks and evaluate performance on your own datasets, follow these steps:

1. Add your dataset to sample_datasets.py.
2. Execute the benchmark suite (refer to the repository's main instructions for the specific execution command).
3. Submit a Pull Request with your findings to contribute to the benchmark data.

To run the benchmark suite yourself and compare TOON against JSON, follow these steps:

1. Clone the repository.
2. Install the project and the tiktoken dependency.
3. Execute the specific benchmark scripts.

# Clone the repo
git clone https://github.com/ScrapeGraphAI/toonify.git
cd toonify

# Install dependencies
pip install -e .
pip install tiktoken

# Run specific benchmarks
python benchmark/compare_formats.py
python benchmark/memory_benchmark.py

# Or run all benchmarks at once
python benchmark/run_all.py