Learn how to convert JSON to TOON format with practical examples, best practices, and step-by-step instructions to reduce your LLM token usage.
Converting your JSON data to TOON format is the fastest way to start saving on LLM API costs. This comprehensive guide will walk you through everything you need to know about JSON to TOON conversion, from basic syntax to advanced patterns.
Why Convert JSON to TOON?
Before we dive into the how, let's quickly recap the why:
- Reduce token consumption by 30-60%
- Lower API costs across all LLM providers
- Fit more data in context windows
- Faster processing with fewer tokens
Understanding the Fundamental Differences
JSON Structure
{
"key": "value",
"nested": {
"property": "data"
},
"array": [1, 2, 3]
}
TOON Structure
key: value
nested:
property: data
array: [1, 2, 3]
Token savings: TOON eliminates redundant curly braces, quotation marks around keys, and excessive punctuation.
Basic Conversion Rules
1. Simple Key-Value Pairs
JSON:
{
"name": "Alice",
"age": 28,
"city": "New York"
}
TOON:
name: Alice
age: 28
city: New York
Rule: Remove curly braces and quotes around keys. Keep one key-value pair per line.
2. Nested Objects
JSON:
{
"user": {
"name": "Bob",
"email": "bob@example.com",
"address": {
"street": "123 Main St",
"city": "Boston"
}
}
}
TOON:
user:
name: Bob
email: bob@example.com
address:
street: 123 Main St
city: Boston
Rule: Use indentation (2 spaces) to represent nesting instead of curly braces.
3. Arrays
JSON:
{
"colors": ["red", "green", "blue"],
"numbers": [1, 2, 3, 4, 5]
}
TOON:
colors: [red, green, blue]
numbers: [1, 2, 3, 4, 5]
Rule: Keep arrays in bracket notation. Quotes around string values in arrays can be omitted if there are no spaces.
4. Arrays of Objects
JSON:
{
"users": [
{
"id": 1,
"name": "John"
},
{
"id": 2,
"name": "Jane"
}
]
}
TOON:
users:
- id: 1
name: John
- id: 2
name: Jane
Rule: Use dash (-) for array items, followed by indented properties.
Advanced Conversion Patterns
Complex Nested Structures
JSON:
{
"company": {
"name": "TechCorp",
"departments": [
{
"name": "Engineering",
"employees": [
{
"name": "Alice",
"role": "Senior Developer"
}
]
}
]
}
}
TOON:
company:
name: TechCorp
departments:
- name: Engineering
employees:
- name: Alice
role: Senior Developer
Handling Special Characters
JSON:
{
"message": "Hello, \"World\"!",
"description": "Line 1\nLine 2"
}
TOON:
message: Hello, "World"!
description: |
Line 1
Line 2
Rule: Use pipe (|) for multi-line strings. Escape sequences are handled naturally.
Boolean and Null Values
JSON:
{
"isActive": true,
"isVerified": false,
"middleName": null
}
TOON:
isActive: true
isVerified: false
middleName: null
Rule: Boolean and null values remain the same.
Numbers and Scientific Notation
JSON:
{
"integer": 42,
"float": 3.14159,
"scientific": 1.5e10
}
TOON:
integer: 42
float: 3.14159
scientific: 1.5e10
Rule: Numeric values are preserved as-is.
Step-by-Step Conversion Process
Step 1: Analyze Your JSON Structure
Identify:
- Depth of nesting
- Number of arrays
- Special characters or multi-line strings
- Data types present
Step 2: Start with the Root Level
Remove the opening curly brace and convert top-level keys.
Step 3: Handle Nesting
Replace curly braces with proper indentation (2 spaces per level).
Step 4: Convert Arrays
Keep simple arrays in brackets. Use dash notation for arrays of objects.
Step 5: Validate the Result
Ensure:
- Consistent indentation
- Proper syntax for each data type
- No missing or extra characters
Real-World Conversion Example
Let's convert a realistic API response:
JSON (Original):
{
"status": "success",
"data": {
"user": {
"id": 12345,
"username": "johndoe",
"email": "john@example.com",
"profile": {
"firstName": "John",
"lastName": "Doe",
"age": 30
},
"preferences": {
"theme": "dark",
"notifications": true
}
},
"posts": [
{
"id": 1,
"title": "My First Post",
"likes": 42
},
{
"id": 2,
"title": "Another Post",
"likes": 73
}
]
}
}
TOON (Converted):
status: success
data:
user:
id: 12345
username: johndoe
email: john@example.com
profile:
firstName: John
lastName: Doe
age: 30
preferences:
theme: dark
notifications: true
posts:
- id: 1
title: My First Post
likes: 42
- id: 2
title: Another Post
likes: 73
Token Reduction: Approximately 45% fewer tokens!
Common Conversion Mistakes to Avoid
1. Inconsistent Indentation
❌ Wrong:
user:
name: John
age: 30
✅ Correct:
user:
name: John
age: 30
2. Missing Colons
❌ Wrong:
name John
✅ Correct:
name: John
3. Incorrect Array Syntax
❌ Wrong:
items:
[1, 2, 3]
✅ Correct:
items: [1, 2, 3]
4. Not Handling Multi-line Strings
❌ Wrong:
description: This is a very long description that spans multiple lines
✅ Correct:
description: |
This is a very long description
that spans multiple lines
Automated Conversion Tools
While manual conversion is educational, automated tools save time:
Benefits of Using a Converter Tool:
- Instant conversion of large JSON files
- Error-free syntax
- Token count comparison before and after
- Batch processing for multiple files
- Validation to ensure proper TOON format
When to Use Manual vs Automated:
- Manual: Learning TOON, small files, custom formatting needs
- Automated: Production environments, large datasets, time-sensitive projects
Testing Your Converted TOON
After conversion, verify:
- Data integrity: All values preserved correctly
- Structure: Nesting levels match original JSON
- Token count: Measure actual savings
- LLM compatibility: Test with your target LLM API
Best Practices for Conversion
1. Keep Consistent Formatting
Use the same indentation throughout (2 spaces recommended).
2. Comment Your TOON
Add comments where needed:
user:
name: John # Primary user
role: admin
3. Validate Before Production
Always validate converted TOON before using in production environments.
4. Version Control
Keep both JSON and TOON versions during transition period.
5. Document Your Schema
Maintain documentation of your TOON data structures for team reference.
Migration Strategy
Phase 1: Test
Convert sample JSON files and test with your LLM applications.
Phase 2: Measure
Track token usage and cost savings over a test period.
Phase 3: Gradual Rollout
Migrate one API endpoint at a time to minimize risk.
Phase 4: Full Production
Once validated, convert all JSON to TOON for maximum savings.
Conclusion
Converting JSON to TOON is straightforward once you understand the basic rules:
- Remove unnecessary syntax overhead
- Use indentation for nesting
- Keep arrays concise
- Maintain data type integrity
Whether you convert manually or use automated tools, the token savings make TOON adoption a smart choice for any LLM-powered application.
Ready to start converting? Try our free JSON to TOON converter and see your savings instantly!
Next Steps: Check out our guide on calculating your exact API savings with TOON format.