Why savvy AI developers are abandoning JSON for this token-efficient alternative—and how Python makes the switch effortless
If you’re building AI applications with Python and Large Language Models (LLMs) like GPT-4, Claude, or Gemini, there’s a hidden tax you’re probably paying: the JSON tax. Every curly brace, every comma, every repeated field name in your data is costing you real money—and you might not even realize it.
Enter TOON (Token-Oriented Object Notation), a revolutionary data format that’s quietly transforming how developers structure data for AI applications. Think of it as “JSON for the AI era”—delivering the same information with 30-60% fewer tokens, which translates directly to lower costs and faster processing.
Table of Contents
What Exactly Is TOON Format?
Token-Oriented Object Notation is a compact, human-readable serialization format designed specifically for passing structured data to Large Language Models with significantly reduced token usage. Unlike JSON, which was built for general machine-to-machine communication back in the early 2000s, TOON is laser-focused on optimizing how we feed data to AI models.
The philosophy is simple yet powerful: Use JSON in your application code, convert to TOON when sending data to LLMs, then work with JSON results. You’re not replacing your entire tech stack—you’re adding a smart translation layer exactly where it matters most.
Here’s the magic in action. This JSON payload:
{
"users": [
{ "id": 1, "name": "Alice", "role": "admin" },
{ "id": 2, "name": "Bob", "role": "user" }
]
}
Becomes this lean TOON format:
users[2]{id,name,role}:
1,Alice,admin
2,Bob,user
Notice what disappeared? The curly braces, the repetitive field names, the excessive commas. TOON borrows YAML’s indentation-based structure for nested objects and CSV’s tabular format for uniform data rows, then optimizes both for token efficiency in LLM contexts.
The Real-World Impact: Show Me The Money
Let’s talk numbers, because that’s what matters. TOON achieves 73.9% accuracy versus JSON’s 69.7% while using 39.6% fewer tokens in benchmark tests across multiple AI models.
But what does that mean for your wallet?
For 100 repositories with 8-10 fields each, TOON saves 6,400 tokens compared to JSON. At $0.03 per 1K tokens, that’s about $0.19 per call. For an app making 1,000 such calls monthly, that’s $190 saved.
Scale that up. If you’re processing 10,000 API calls per month with structured data—common for customer support chatbots, data analysis tools, or AI-powered applications—you could save $2,500 monthly just by switching your data format.
A real-world test showed compelling results: With a dataset of employees, asking GPT to calculate average salary by department, TOON delivered roughly a 56% reduction in prompt tokens and a noticeable 5-second speed improvement.
Getting Started with TOON in Python: Installation Made Easy
Python developers have multiple robust implementations to choose from. The most popular and battle-tested option is the official toon_format package.
Installation
The official community-driven Python implementation is available at toon-format/toon-python with 100% compatibility with the official TOON specification v1.3.
# Using pip (standard installation)
pip install toon_format
# Using uv (recommended for modern Python projects)
uv add toon_format
The package supports Python 3.8+ and comes with battle-tested quality: 792 tests, 91% coverage, with 85% coverage enforced through CI/CD with GitHub Actions.
Basic Python Usage: From Zero to Hero in 5 Minutes
Here’s how simple TOON encoding is in Python:
from toon_format import encode, decode
# Simple object encoding
data = {
"name": "Alice",
"age": 30,
"active": True
}
toon_output = encode(data)
print(toon_output)
# Output:
# name: Alice
# age: 30
# active: true
The real power shines with tabular data—arrays of uniform objects:
# Tabular array (the sweet spot for TOON)
users = [
{"id": 1, "name": "Alice", "email": "[email protected]"},
{"id": 2, "name": "Bob", "email": "[email protected]"}
]
toon_output = encode(users)
print(toon_output)
# Output:
# [2]{id,name,email}:
# 1,Alice,[email protected]
# 2,Bob,[email protected]
Decoding back to Python is equally straightforward:
toon_str = """
items[2]: apple,banana
"""
data = decode(toon_str)
print(data) # {'items': ['apple', 'banana']}
Power User Features: Command-Line Interface
TOON comes with a command-line tool for converting between JSON and TOON formats with auto-detection by file extension:
# Encode JSON to TOON (auto-detected by .json extension)
toon input.json -o output.toon
# Decode TOON to JSON (auto-detected by .toon extension)
toon data.toon -o output.json
# Use stdin/stdout (perfect for pipelines)
echo '{"name": "Ada"}' | toon -
# Output: name: Ada
# Custom delimiter (tabs can be more efficient)
toon data.json --delimiter "\t" -o output.toon
# With length markers for extra validation
toon data.json --length-marker -o output.toon
Measuring Your Savings: The Proof Is in the Numbers
Want to see exactly how much you’re saving? TOON includes built-in benchmarking tools:
from toon_format import estimate_savings, compare_formats, count_tokens
data = {
"users": [
{"id": 1, "name": "Alice", "role": "admin"},
{"id": 2, "name": "Bob", "role": "user"}
]
}
# Get savings estimate
result = estimate_savings(data)
print(f"Saves {result['savings_percent']:.1f}% tokens")
# Output: Saves 42.3% tokens
# Visual comparison table
print(compare_formats(data))
# Format Comparison
# ────────────────────────────────────────────────
# Format Tokens Size (chars)
# JSON 45 123
# TOON 28 85
# ────────────────────────────────────────────────
# Savings: 17 tokens (37.8%)
Note: These benchmarking features require the tiktoken package: pip install tiktoken or pip install toon-format[benchmark].
Understanding TOON Syntax: The Three Building Blocks
1. Simple Key-Value Pairs (Like YAML, But Leaner)
encode({"id": 123, "name": "Ada"})
# id: 123
# name: Ada
2. Nested Objects (Indentation Shows Hierarchy)
encode({
"user": {
"id": 1,
"profile": {
"bio": "Engineer"
}
}
})
# user:
# id: 1
# profile:
# bio: Engineer
3. Tabular Arrays (The Game-Changer)
This is TOON’s sweet spot. When you have multiple objects with the same structure, TOON declares the keys once:
products = [
{"sku": "A1", "qty": 2, "price": 9.99},
{"sku": "B2", "qty": 1, "price": 14.5}
]
encode({"items": products})
# items[2]{sku,qty,price}:
# A1,2,9.99
# B2,1,14.5
TOON only includes field names in the header, not in each row. This is where massive savings come from.
When TOON Shines (And When It Doesn’t)
TOON’s Sweet Spots
Uniform Tabular Data: TOON’s sweet spot is uniform arrays of objects—multiple fields per row, same structure across items. Perfect for:
- User lists and customer records
- Product catalogs
- Log entries and analytics data
- Database query results
- Time-series metrics
Real-World Example: For 180 days of web metrics with views, clicks, conversions, and revenue, TOON saves 6,470 tokens, a 58.9% reduction versus JSON.
When to Stick with JSON
- Deeply nested structures: Complex hierarchies with many levels
- Non-uniform data: Objects in arrays with different field sets
- Single small objects: The overhead isn’t worth it for tiny payloads
- API responses: JSON remains the standard for web APIs and external communication
For deeply nested or non-uniform data, JSON may be more efficient.
Advanced Configuration Options
TOON in Python supports customization for power users:
# Custom delimiter (tabs can save additional tokens)
encode(data, {"delimiter": "\t", "indent": 4})
# Length markers for extra LLM validation
encode(data, {"lengthMarker": "#"})
# Output: items[#3]: ...
# Lenient decoding (disable strict validation)
decode(toon_str, strict=False)
Integrating TOON with LLMs: Practical Patterns
Here’s a real-world pattern for using TOON with OpenAI’s API:
from toon_format import encode
import openai
# Your structured data
user_data = [
{"id": 1, "name": "Alice", "purchases": 42, "tier": "gold"},
{"id": 2, "name": "Bob", "purchases": 18, "tier": "silver"},
# ... hundreds more users
]
# Convert to TOON before sending to LLM
toon_data = encode({"users": user_data})
# Use in your prompt
response = openai.ChatCompletion.create(
model="gpt-4o",
messages=[{
"role": "user",
"content": f"""
Here's user data in TOON format:
```toon
{toon_data}
Analyze the purchasing patterns and suggest promotions for silver tier users. “”” }] )
TOON works best when you show the format instead of describing it. The structure is self-documenting—models parse it naturally once they see the pattern.
## Benchmark Results: The Proof from Multiple AI Models
Benchmarks test LLM comprehension across different input formats using 209 data retrieval questions on 4 models. The results are impressive:
**Overall Performance (Accuracy vs Token Efficiency)**:
- TOON: 73.9% accuracy, 2,744 tokens ⭐
- JSON compact: 70.7% accuracy, 3,081 tokens
- YAML: 69.0% accuracy, 3,719 tokens
- JSON: 69.7% accuracy, 4,545 tokens
- XML: 67.1% accuracy, 5,167 tokens
TOON achieves better accuracy while using significantly fewer tokens—it's not just cheaper, it's actually more reliable.
## TOON vs Other Formats: Making the Right Choice
### TOON vs CSV
For flat tabular data, CSV is more compact. TOON adds minimal overhead (approximately 5-10%) to provide explicit structure with length markers, field headers, and delimiter scoping that improves LLM reliability.
CSV can't handle nested data or mixed schemas. TOON gives you structure without sacrificing much efficiency.
### TOON vs YAML
YAML is human-readable but verbose. TOON strips away unnecessary syntax while maintaining clarity.
### TOON vs JSON
JSON is universal and works everywhere. TOON is specialized for LLM inputs. The core philosophy is simple: use JSON in your application code, convert to TOON when sending data to LLMs.
## Python Implementation Options: Choosing Your Library
Several Python TOON implementations exist:
1. **`toon_format`** (Official, recommended): Community-driven Python implementation with 100% compatibility with the official TOON specification, battle-tested with 792 tests and 91% coverage
2. **`python-toon`** (by xaviviro): Alternative implementation with similar features
3. **`toon-py`** (by shammi22): Python port with CLI tooling
All follow the TOON format specification and reference implementation by Johann Schopplich and contributors, currently at specification v1.3.
## Real-World Adoption Stories
Smart teams are ditching JSON for TOON. A founder spending about $15K monthly on OpenAI API calls found that nearly 40% of their token budget was just JSON formatting—braces, brackets, and quotes.
The adoption pattern is predictable:
1. Team realizes LLM costs are unsustainable
2. They try prompt optimization and caching
3. They analyze payloads and see formatting overhead
4. Someone tests TOON, sees 40-50% reduction
5. They implement it for highest-traffic endpoints
It's not a wholesale replacement of JSON across the stack. It's surgical—used specifically for LLM communication where token efficiency matters most.
## Common Pitfalls and How to Avoid Them
### 1. Not All Data Benefits Equally
Small, irregular payloads won't see dramatic savings. TOON excels with large, uniform datasets.
### 2. Forgetting About Delimiter Choice
Tab delimiters can be more token-efficient than commas, especially for tabular data. Test with your specific data:
```python
# Compare delimiters
comma_version = encode(data, {"delimiter": ","})
tab_version = encode(data, {"delimiter": "\t"})
print(f"Comma tokens: {count_tokens(comma_version)}")
print(f"Tab tokens: {count_tokens(tab_version)}")
3. Mixing TOON Where JSON Makes More Sense
Keep your API responses, database schemas, and configuration files in JSON. Use TOON specifically for LLM prompts.
The Future of Data Formats in AI
TOON represents a fundamental shift in how we think about data serialization in the AI era. As AI becomes a foundational layer of the tech stack, optimizing the interface to AI becomes as important as optimizing algorithms or database queries.
The format has gained serious traction, with implementations now available in over 15 programming languages including JavaScript, TypeScript, Go, PHP, Ruby, Swift, Rust, and .NET.
Quick Start Checklist: Your 5-Minute Action Plan
- Install:
pip install toon_format - Test with sample data: Run
estimate_savings()on your typical payloads - Benchmark: Compare token counts and costs
- Integrate gradually: Start with one high-volume endpoint
- Measure results: Track token usage and costs over a week
- Scale up: Expand to more endpoints if savings justify it
FAQs: Everything You Need to Know
Q: Does TOON work with all LLMs? A: Yes, TOON works with any LLM including OpenAI GPT models, Claude, Gemini, and open-source models. Since it’s a text-based format, any model that can process structured text can handle TOON.
Q: Will switching to TOON break my existing code? A: No. TOON operates as a translation layer. Your application continues using JSON internally. You only convert to TOON right before sending to the LLM.
Q: How much can I realistically save? A: Savings depend on your usage patterns, but with 30-60% token reduction, if you’re spending $1000/month on LLM API costs, you could potentially save $300-600/month.
Q: Does TOON affect model accuracy? A: Benchmarks show TOON can actually improve accuracy (70.1% vs 65.4% for JSON) while using fewer tokens, likely due to reduced noise from punctuation.
Q: Should I use TOON for LLM outputs too? A: TOON is designed as an input format. For outputs, it’s better to use JSON since it’s more widely supported by existing tools and libraries.
Q: Is TOON hard to learn? A: If you’re familiar with JSON and YAML, you can start using TOON in minutes. The syntax is intuitive and well-documented across all implementations.
Q: What about security concerns? A: TOON parsers include safety checks. Always validate data from untrusted sources, just like with any format. Use the official reference implementation.
Q: Can I use TOON for data storage? A: Technically yes, but it’s not recommended. TOON is optimized for LLM input, not general storage. Use JSON or databases for persistence.
Conclusion: The Smart Developer’s Competitive Edge
In the AI gold rush of 2025, every edge matters. While your competitors are burning budget on JSON overhead, you can be the developer who ships faster, scales cheaper, and delivers better results—all by making one smart architectural choice.
TOON represents a thoughtful optimization for the LLM era. By recognizing that data formats designed for machine-to-machine communication aren’t always optimal for machine-to-AI communication, TOON provides a practical solution.
The best part? You don’t have to rewrite your entire stack. Keep using JSON for APIs, databases, and client-side code. Just add a quick encode() call before hitting your LLM, and watch your token counts drop.
Start small. Pick one data-heavy LLM endpoint. Implement TOON. Measure the impact. If you’re like most developers who’ve made the switch, you’ll wonder why you didn’t do it sooner.
Ready to cut your LLM costs in half? Install toon_format today and join the growing community of developers building smarter, more efficient AI applications.
pip install toon_format
The future of AI development isn’t just about better models—it’s about better infrastructure. TOON is that infrastructure.
For more information, explore the official TOON specification, try the interactive tokenization playground, and join the community on GitHub.
