Getting Started with TOON Format in 2025

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-4 or Claude:

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

Example:

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

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 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

# User Profile
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:

Visit a TOON converter website
Paste your JSON
Get TOON output
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:

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "TOON" or "TOON Format"
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 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 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:

Start simple - Begin with basic conversions
Measure first - Know your baseline token usage
Deploy gradually - Test before full rollout
Monitor constantly - Track savings and issues
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.