Getting Started with TOON Format in 2025

Your complete beginner's guide to TOON format. Learn the basics, set up your environment, and start optimizing your LLM applications today.hifza

Welcome to TOON! If you're looking to reduce your LLM API costs and optimize token usage, you're in the right place. This guide will take you from zero to productive with TOON format in under 30 minutes.

What You'll Learn

By the end of this guide, you'll be able to:

• Understand what TOON is and why it matters
• Read and write TOON syntax
• Convert your first JSON file to TOON
• Integrate TOON into your applications
• Measure your token savings

Let's get started!

What is TOON?

TOON (Token-Oriented Object Notation) is a data serialization format designed specifically for Large Language Model applications. Think of it as JSON's leaner, more efficient cousin.

The Problem TOON Solves

When you send data to LLMs like GPT or Claude:

• Every character is converted to tokens
• Tokens cost money
• JSON has lots of unnecessary characters (braces, quotes, commas)

Example:

{"name": "Alice", "age": 3000}  

JSON Tokens: ~12

name: Alice  
  
age: 30  

TOON Tokens: ~6

Savings: 50% fewer tokens = 50% lower costs

Key Benefits

✅ 30-60% token reduction on typical datasets ✅ Direct cost savings on all LLM APIs ✅ Faster processing with fewer tokens ✅ More data fits in context windows ✅ Easy to learn if you know JSON or YAML

TOON Basics

Your First TOON File

Create a file called example.toon:

title: Getting Started with TOON  
  
author: Mobeen  
  
published: true  
  
readTime: 5  

That's it! You've written your first TOON file.

Core Syntax Rules

1. Key-Value Pairs

key: value  

• Key on the left
• Colon in the middle
• Value on the right
• No quotes needed for simple keys or values

2. Nesting with Indentation

person:  
  
  name: John  
  
  age: 30  

• Parent key ends with a colon
• Child properties indented 2 spaces
• No braces needed

3. Arrays

Simple arrays:

colors: [red, green, blue]  
  
numbers: [1, 2, 3, 4, 5]  

Arrays of objects:

users:  
  - name: Alice  
  
    role: admin  
  - name: Bob  
  
    role: user  

4. Data Types

Strings:

name: Alice  
  
title: Hello World  
  
message: "Text with spaces"  

Numbers:

age: 30  
  
price: 29.99  
  
quantity: 1000  

Booleans:

isActive: true  
  
isVerified: false  

Null:

middleName: null  

Complete Example

userId: 12345  
  
profile:  
  
  firstName: John  
  
  lastName: Doe  
  
  email: john@example.com  
  
  age: 30  
  
  verified: true  
  
preferences:  
  
  theme: dark  
  
  notifications:  
  
    email: true  
  
    push: false  
  
    sms: false  
  
tags: [developer, javascript, nodejs]  
  
projects:  
  - id: 1  
  
    name: Website Redesign  
  
    status: active  
  
    priority: high  
  - id: 2  
  
    name: Mobile App  
  
    status: completed  
  
    priority: medium  

Setting Up Your Environment

Option 1: Use Online Converters (Quickest Start)

No installation needed! Just:

1. Visit a TOON converter website
2. Paste your JSON
3. Get TOON output
4. Copy and use

Best for:

• Learning TOON
• Quick conversions
• Testing samples

Option 2: Command Line Tools (For Developers)

Install a TOON CLI tool:

# Example installation (adjust based on actual tools)  
npm install -g toon-cli  
# or  
pip install toon-converter  

Usage:

# Convert JSON to TOON  
toon convert input.json -o output.toon  
  
# Validate TOON file  
toon validate data.toon  
  
# Get token count  
toon count data.toon  

Option 3: Editor Plugins (For Daily Use)

VS Code:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "TOON" or "TOON Format"
4. Install the extension

Features you get:

• Syntax highlighting
• Auto-completion
• Validation
• Format on save

Option 4: Programming Libraries

JavaScript/Node.js:

const toon = require('toon-parser');  
  
// Parse TOON string  
const data = toon.parse(toonString);  
  
// Convert object to TOON  
const toonString = toon.stringify(data);  

Python:

import toon  
  
# Parse TOON file  
with open('data.toon', 'r') as f:  
    data = toon.load(f)  
  
# Convert dict to TOON  
toon_string = toon.dumps(data)  

Your First Conversion

Let's convert a real JSON file step by step.

Step 1: Prepare Your JSON

Create user.json:

{  
  "id": 101,  
  "username": "alice",  
  "email": "alice@example.com",  
  "profile": {  
    "firstName": "Alice",  
    "lastName": "Johnson",  
    "age": 28  
  },  
  "active": true  
}  

Step 2: Manual Conversion

Following TOON rules, convert to user.toon:

id: 101  
  
username: alice  
  
email: alice@example.com  
  
profile:  
  
  firstName: Alice  
  
  lastName: Johnson  
  
  age: 28  
  
active: true  

Step 3: Validate

Check your conversion:

• ✅ No curly braces
• ✅ No quotes on keys
• ✅ Proper indentation (2 spaces)
• ✅ Colon after parent keys
• ✅ Values correctly formatted

Step 4: Measure Savings

JSON tokens: ~45 TOON tokens: ~24 Savings: 47%

Integrating TOON into Your Application

Pattern 1: Convert at the Boundary

Keep your application logic in JSON, convert to TOON only when calling LLMs.

// Your existing code  
const data = {  
  user: "Alice",  
  query: "Analyze this data"  
};  
  
// Convert to TOON before LLM call  
const toonData = convertToTOON(data);  
  
// Send to LLM  
const response = await openai.chat.completions.create({  
  model: "gpt-4",  
  messages: [{  
    role: "user",  
    content: toonData  
  }]  
});  

Benefits:

• Minimal code changes
• Use JSON everywhere else
• Maximum token savings where it matters

Pattern 2: Native TOON Storage

Store configuration and prompts in TOON format.

config.toon:

llm:  
  
  provider: openai  
  
  model: gpt-4  
  
  temperature: 0.7  
  
  maxTokens: 2000  
  
prompts:  
  
  system: You are a helpful assistant  
  
  userTemplate: Analyze: {input}  

Load in your app:

const config = loadTOON('config.toon');  

Benefits:

• Smaller config files
• Better for version control
• Easier to read diffs

Pattern 3: Hybrid Approach

Use JSON for external APIs, TOON for internal processing.

// Receive JSON from client  
app.post('/api/analyze', (req, res) => {  
  const jsonData = req.body;  
    
  // Convert to TOON for LLM  
  const toonData = toTOON(jsonData);  
    
  // Process with LLM  
  const result = await processWithLLM(toonData);  
    
  // Convert back to JSON for response  
  const jsonResult = toJSON(result);  
    
  res.json(jsonResult);  
});  

Common Patterns and Recipes

Pattern 1: User Data

JSON:

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

TOON:

users:  
  - id: 1  
  
    name: Alice  
  
    role: admin  
  - id: 2  
  
    name: Bob  
  
    role: user  

Pattern 2: API Responses

JSON:

{  
  "status": "success",  
  "data": {  
    "items": [1, 2, 3],  
    "total": 3  
  }  
}  

TOON:

status: success  
  
data:  
  
  items: [1, 2, 3]  
  
  total: 3  

Pattern 3: Configuration Files

JSON:

{  
  "database": {  
    "host": "localhost",  
    "port": 5432,  
    "ssl": true  
  }  
}  

TOON:

database:  
  
  host: localhost  
  
  port: 5432  
  
  ssl: true  

Pattern 4: Multi-line Content

TOON:

description: |  
  This is a long description  
  that spans multiple lines  
  and preserves formatting  

Pattern 5: Comments

# Configuration for production  
environment: production  
  
# Database settings  
database:  
  
  host: prod-db.example.com  # Production DB  
  port: 5432  

Measuring Your Success

Track These Metrics

Before TOON:

Average request tokens: 500  
Daily requests: 10,000  
Daily cost: $50  
Monthly cost: $1,500  

After TOON:

Average request tokens: 250 (50% reduction)  
Daily requests: 10,000  
Daily cost: $25  
Monthly cost: $750  
Savings: $750/month  

Token Counting Tools

Use built-in tools to measure:

# Count tokens in file  
toon count myfile.toon  
  
# Compare JSON vs TOON  
toon compare myfile.json myfile.toon  

Expected output:

JSON tokens: 1,245  
TOON tokens: 623  
Reduction: 50%  
Estimated monthly savings: $1,200  

Troubleshooting Common Issues

Issue 1: Indentation Errors

Problem:

user:  
  
 name: John  
  
   age: 30  

Solution: Use consistent 2-space indentation:

user:  
  
  name: John  
  
  age: 30  

Issue 2: Missing Colons

Problem:

user  
  
  name: John  

Solution: Add a colon after parent keys:

user:  
  
  name: John  

Issue 3: Quoted Numbers

Problem:

age: "30"  

Solution: Remove quotes for numbers:

age: 30  

Issue 4: Array Syntax Confusion

Problem:

items:  
  1, 2, 3  

Solution: Use brackets for simple arrays:

items: [1, 2, 3]  

Or dash notation for object arrays:

items:  
  - id: 1  
  - id: 2  

Best Practices

1. Start Small

Begin with:

• Non-critical endpoints
• Internal APIs
• Test environments

2. Validate Everything

Always validate TOON before production:

toon validate myfile.toon  

3. Version Control

Commit both JSON and TOON during transition:

/config  
  ├── settings.json  
  └── settings.toon  

4. Document Your Schema

Add comments to TOON files:

# User configuration schema  
# Version: 2.1  
user:  
  
  id: 12345  # Unique user identifier  
  role: admin  # Options: admin, user, guest  

5. Use Consistent Formatting

Pick a style and stick to it:

• 2 spaces for indentation (recommended)
• Lowercase keys
• Clear commenting conventions

6. Test Token Counts

Before full deployment:

# Test sample files  
toon count sample1.toon  
toon count sample2.toon  
toon count sample3.toon  
  
# Calculate average reduction  

Next Steps

Now that you're up and running with TOON:

Week 1: Learn and Experiment

•  Convert 10 sample JSON files
•  Practice writing TOON manually
•  Set up your editor with TOON support
•  Try different data structures

Week 2: Measure and Validate

•  Measure token savings on real data
•  Calculate projected cost savings
•  Test with your LLM provider
•  Validate conversion accuracy

Week 3: Pilot Deployment

•  Choose one non-critical endpoint
•  Deploy TOON conversion
•  Monitor for issues
•  Track actual savings

Week 4: Scale Up

•  Expand to more endpoints
•  Optimize the conversion process
•  Document best practices for your team
•  Share results with stakeholders

Resources

Learning Materials

• TOON specification documentation
• Video tutorials
• Interactive examples
• Community forums

Tools

• Online converters
• CLI tools
• Editor plugins
• Library integrations

Community

• GitHub discussions
• Discord server
• Stack Overflow tag
• Reddit community

Conclusion

You're now ready to use TOON! Remember:

1. Start simple - Begin with basic conversions
2. Measure first - Know your baseline token usage
3. Deploy gradually - Test before full rollout
4. Monitor constantly - Track savings and issues
5. Optimize continuously - Refine your approach

TOON adoption typically shows:

• 30-60% token reduction
• ROI within 2-4 weeks
• Minimal learning curve
• Easy integration

The best time to start saving on LLM costs was yesterday. The second best time is now.

---

Ready to dive deeper? Check out our advanced guides on TOON optimization and best practices.