TOON File Format Examples

TOON (Token-Optimized Object Notation) is a data serialization format specifically designed for Large Language Model applications. Unlike JSON which repeats keys for every object in an array, TOON declares keys once as headers and represents data in delimited rows, similar to CSV but optimized for nested structures.

Why TOON Format Matters for AI Applications

Language models like GPT-4, Claude, and Gemini charge based on token consumption. Standard JSON wastes tokens on redundant syntax: curly braces, quotes around keys, colons, and commas. For an array of 100 user objects with 10 fields each, JSON repeats those 10 keys 100 times. TOON declares them once.

• Token Reduction: Achieve 30-60% fewer tokens compared to equivalent JSON data structures.
• Cost Savings: Direct reduction in GPT-4 API costs at $0.03 per 1K tokens means significant monthly savings.
• Human Readable: Unlike binary formats, TOON maintains readability for debugging and manual inspection.
• LLM Compatible: Language models process TOON format naturally in prompt contexts without special handling.

The format excels with homogeneous arrays of objects (user lists, product catalogs, log entries) where repetitive structure creates maximum redundancy in JSON. TOON transforms these into table-like representations with headers declared once.

TOON files work best when feeding structured data to Large Language Models. The format reduces token overhead while maintaining human readability for debugging. Below are practical examples for common programming languages.

Using TOON in Python LLM Applications

Read TOON files and include them in prompts sent to OpenAI, Anthropic, or other LLM providers. The reduced token count directly lowers API costs.

import openai

# Read TOON formatted data
with open("sample-users-toon.toon", "r", encoding="utf-8") as f:
    toon_data = f.read()

# Include in LLM prompt with minimal token overhead
prompt = f"""
Context Data:
{toon_data}

Task: Summarize the user distribution by country.
"""

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": prompt}]
)

print(response.choices[0].message.content)

Loading TOON in JavaScript/Node.js

Use TOON format in frontend applications or Node.js backends to optimize token consumption when interacting with language model APIs.

const fs = require('fs');
const { Configuration, OpenAIApi } = require('openai');

// Read TOON file
const toonData = fs.readFileSync('sample-products-toon.toon', 'utf-8');

// Prepare optimized prompt
const prompt = `Product Catalog:\n${toonData}\n\nGenerate SEO descriptions for top 3 products.`;

const configuration = new Configuration({
  apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(configuration);

const completion = await openai.createChatCompletion({
  model: "gpt-4",
  messages: [{ role: "user", content: prompt }],
});

console.log(completion.data.choices[0].message.content);

Converting JSON to TOON Programmatically

Integrate TOON conversion into your data pipeline for automatic optimization before sending to LLMs. This Python example shows basic array-to-table conversion.

import json
import csv
from io import StringIO

def json_to_toon(json_data, delimiter=','):
    """Convert JSON array to TOON format"""
    if isinstance(json_data, list) and json_data and isinstance(json_data[0], dict):
        # Extract all unique keys
        keys = list(json_data[0].keys())
        
        # Create header and rows
        output = StringIO()
        writer = csv.writer(output, delimiter=delimiter)
        writer.writerow(keys)
        
        for item in json_data:
            row = [item.get(key, '') for key in keys]
            writer.writerow(row)
            
        return output.getvalue().strip()
    return json.dumps(json_data)

# Example usage
with open('products.json', 'r') as f:
    data = json.load(f)

toon_output = json_to_toon(data['products'])

# Save to file
with open('products.toon', 'w') as f:
    f.write(f"products:\n{toon_output}")

print(f"Token reduction: ~{len(toon_output) / len(json.dumps(data)) * 100:.0f}% of original")

Bash/Shell Script for Batch Conversion

Automate TOON conversion in CI/CD pipelines or batch processing workflows using command-line tools.

#!/bin/bash
# convert_to_toon.sh - Convert all JSON files in directory to TOON

for jsonfile in *.json; do
  echo "Converting $jsonfile..."
  
  # Extract filename without extension
  basename="${jsonfile%.json}"
  
  # Convert using jq and custom formatting
  jq -r '.[] | [.id, .name, .email, .role] | @csv' "$jsonfile" > "${basename}.toon"
  
  # Add header
  echo "id,name,email,role" | cat - "${basename}.toon" > temp && mv temp "${basename}.toon"
  
  echo "Created ${basename}.toon"
done

echo "Conversion complete. TOON files ready for LLM integration."

Real-world examples demonstrating token reduction and cost savings across different data structures. Calculations based on GPT-4 pricing at $0.03 per 1,000 input tokens.

• Use for Homogeneous Arrays: TOON excels with arrays of objects sharing the same structure (users, products, logs). Heterogeneous data benefits less.
• Choose Appropriate Delimiters: Use comma for standard data, tab for better visual alignment, pipe when data contains commas.
• Maintain Readability: TOON should remain debuggable. Avoid excessive compression that makes manual inspection difficult.
• Document the Format: When sharing TOON files with team members, include format documentation explaining the structure.
• Version Control Friendly: TOON text format works well with git and other VCS systems, showing clear line-by-line diffs.
• Test with Actual Tokenizers: Validate savings using actual LLM provider tokenizers rather than assumptions about compression ratios.