JSON ↔ TOON Converter - Token-Optimized Format for LLMs

What is TOON (Token-Oriented Object Notation)?

TOON (Token-Oriented Object Notation) is a compact, human-readable data serialization format specifically designed for Large Language Model (LLM) applications. Created to address the growing concern of token consumption costs when working with AI models like ChatGPT, Claude, Gemini, and other LLMs, TOON provides a schema-aware alternative to JSON that can reduce token usage by 30-50% or more. Unlike traditional JSON which repeats property names for every object in an array, TOON uses a tabular format where headers are defined once and data rows follow in a compact comma-separated format. This approach is particularly effective for structured data with repeated schemas, such as API responses, database records, or any collection of objects with consistent properties. The format maintains human readability while significantly reducing the number of tokens required to represent the same data, making it ideal for cost-sensitive LLM applications and scenarios where context window limits are a concern.

Why Should I Use TOON Instead of JSON for LLM Prompts?

There are several compelling reasons to use TOON over JSON when working with Large Language Models. First and foremost is cost reduction - LLM APIs like OpenAI's GPT-4, Anthropic's Claude, and Google's Gemini charge based on token usage, and TOON can reduce your token consumption by 30-50% for structured data, directly lowering your API costs. Second, TOON helps you fit more data within context window limits. Every LLM has a maximum context length, and by using a more compact format, you can include more relevant data in your prompts without hitting these limits. Third, TOON improves response quality by allowing you to provide more context and examples within the same token budget. Fourth, the format is self-documenting - the header row clearly defines the schema, making it easier for both humans and LLMs to understand the data structure. Fifth, TOON is particularly effective for batch operations where you need to process multiple records, as the token savings compound with each additional row. Finally, TOON maintains full data fidelity - you can convert back to JSON without any loss of information, making it a lossless optimization technique.

How Does TOON Format Work?

TOON works by transforming repetitive JSON structures into a more efficient tabular representation. The key insight is that when you have an array of objects with the same properties, JSON repeats all property names for every single object. TOON eliminates this redundancy by declaring the schema once in a header line, then representing each object as a simple comma-separated row of values. The format uses a specific syntax: the header line contains the array name, count, and field names in curly braces, followed by a colon. Each subsequent line contains the values for one object, separated by commas. For nested objects and arrays, TOON uses indentation and recursive application of the same principles. Special values like null, true, false, and strings with special characters are handled according to the TOON specification. The format also supports mixed-type arrays, nested structures, and optional fields, making it flexible enough to represent any JSON data while maintaining its compact nature.

// JSON (89 characters)
[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]

// TOON (42 characters, 53% smaller)
[2](id,name):
  1,Alice
  2,Bob

What Are the Key Differences Between TOON and JSON?

While both TOON and JSON are data serialization formats, they have fundamental differences in their approach and use cases. JSON uses a verbose key-value pair syntax where every object explicitly names all its properties, making it highly redundant for arrays of similar objects. TOON uses a schema-first approach where property names are declared once in a header, and subsequent rows contain only values. JSON is universally supported across all programming languages and platforms with built-in parsers. TOON is newer and requires specific libraries for encoding and decoding, though implementations exist for TypeScript, Python, Go, Rust, and many other languages. JSON is ideal for configuration files, single objects, and scenarios where human editing is frequent. TOON excels at representing collections of structured data, API responses, and any scenario where the same schema is repeated multiple times. JSON uses curly braces and square brackets extensively, consuming more tokens. TOON uses minimal syntax with colons, commas, and indentation, resulting in significant token savings. Both formats can represent the same data with complete fidelity - you can convert between them without losing any information.

How Much Token Savings Can I Expect with TOON?

The token savings from using TOON vary depending on your data structure, but typical savings range from 30% to 60% for structured data with repeated schemas. The savings are most dramatic when you have arrays with many objects that share the same properties. For example, a JSON array of 100 user objects with properties like id, name, email, and role would repeat these four property names 100 times. In TOON, these names appear only once in the header, immediately saving 396 repetitions of property names. Real-world benchmarks show impressive results: a GitHub repositories dataset (100 items) shows 47% token reduction; a user profiles dataset shows 52% reduction; API response data typically shows 35-55% reduction. The savings compound as your data grows - the more objects in your array, the greater the percentage savings. For single objects or highly nested data without repeated schemas, the savings are more modest (10-20%), but still meaningful when you're paying per token. It's worth noting that the savings apply not just to your input tokens but also when LLMs need to output or reference this data in their responses.

What is the Basic Syntax of TOON Format?

TOON syntax is designed to be minimal yet expressive. The basic building blocks are: 1) Simple key-value pairs written as 'key: value' on separate lines, similar to YAML. 2) Arrays of objects use a header notation: 'arrayName[count](field1,field2,field3):' followed by data rows where each row contains comma-separated values corresponding to the header fields. 3) Nested objects are represented with indentation, where child properties are indented under their parent. 4) String values containing commas, newlines, or special characters are quoted. 5) Null values are represented as empty (just a comma with no value). 6) Boolean values are written as 'true' or 'false' without quotes. 7) Numbers are written directly without quotes. 8) Arrays of primitives use square bracket notation. The format supports both tab and comma delimiters, with tabs providing even better token efficiency in some tokenizers. Comments are not part of the official spec but some implementations support them.

// Array with schema header
products[3](id,name,price):
  1,Widget,9.99
  2,Gadget,19.99
  3,Gizmo,29.99

// Nested object
user:
  name: John Doe
  age: 30
  address:{city: New York, zip: 10001}

What Data Types Does TOON Support?

TOON supports all the same data types as JSON, ensuring complete data fidelity during conversion. Strings are represented as text, with quotes required only when the string contains special characters like commas, newlines, or leading/trailing whitespace. Numbers include both integers and floating-point values, represented in their standard decimal notation. Boolean values are written as the literals 'true' or 'false' without quotes. Null values are represented as empty in the tabular format (an empty position between commas) or as the literal 'null' in key-value contexts. Objects can be nested to any depth, with child properties indented under their parent. Arrays can contain any type including mixed types, primitives, or nested objects. TOON also handles special numeric values and maintains precision for large numbers. The format preserves the original JSON types during round-trip conversion, meaning you can convert JSON to TOON and back to JSON without any data loss or type changes.

How Do I Use TOON Format with ChatGPT, Claude, and Other LLMs?

Using TOON with LLMs is straightforward and follows a 'show, don't tell' approach. The most effective method is to wrap your TOON data in code blocks using the 'toon' language identifier. This helps the LLM recognize the format and parse it correctly. When asking the LLM to output data in TOON format, provide an example of the expected structure in your prompt. LLMs are pattern-matching systems and will naturally follow the format you demonstrate. For best results: 1) Include a brief header explaining that the data is in TOON format for token efficiency. 2) Use code blocks to clearly delineate the TOON content. 3) When expecting TOON output, show the header template you want the LLM to use. 4) For complex nested structures, consider providing a small example first. 5) You can ask the LLM to validate TOON syntax or convert between formats. Most modern LLMs including GPT-4, Claude 3, and Gemini can understand and generate TOON format after seeing examples, even without explicit training on the format.

// LLM Prompt Example:
Here is user data in TOON format:

users[3](id,name,email):
  1,Alice,[email protected]
  2,Bob,[email protected]
  3,Charlie,[email protected]

Please analyze this data and respond in the same TOON format.

What Programming Languages Support TOON?

TOON has growing support across many programming languages, with both official and community implementations available. The official TypeScript/JavaScript implementation (toon-format/toon on npm) is the reference implementation, providing encode, decode, and streaming APIs. Python developers can use the toon_format package available on PyPI. Rust has the toon_format crate for high-performance applications. Go developers have toon-go for backend services. Java has JToon for enterprise applications. Swift has toon-swift for iOS/macOS development. .NET developers can use toon_format for C# applications. Community implementations extend support to many more languages including PHP, Ruby, Kotlin, Scala, Elixir, Clojure, Crystal, OCaml, Perl, R, and even Apex for Salesforce development. Most implementations follow the official TOON specification to ensure compatibility. Editor support includes VS Code extensions for syntax highlighting and validation, Tree-sitter grammars for Neovim and other editors, and online playgrounds for experimentation.

When Should I Use TOON vs When Should I Stick with JSON?

TOON is ideal for specific scenarios while JSON remains better for others. Use TOON when: 1) You're sending structured data to LLMs and want to reduce token costs. 2) You have arrays of objects with consistent schemas (database records, API responses, log entries). 3) You're approaching context window limits and need to fit more data. 4) You're doing batch processing with LLMs where token savings compound. 5) You're building AI applications where API costs are a significant concern. 6) You need to include large datasets in prompts while maintaining readability. Stick with JSON when: 1) You're working with configuration files that humans frequently edit. 2) You have single objects or highly irregular nested structures. 3) You need maximum compatibility with existing tools and systems. 4) You're not working with LLMs or token costs aren't a concern. 5) Your data has few repeated schemas where TOON's benefits are minimal. 6) You need to use JSON Schema validation or other JSON-specific tooling. The good news is that conversion between formats is lossless, so you can use JSON internally and convert to TOON only when sending to LLMs.

What Are the Limitations of TOON Format?

While TOON offers significant benefits, it's important to understand its limitations. First, TOON is optimized for arrays of objects with consistent schemas - for single objects or highly irregular structures, the token savings are minimal. Second, TOON requires encoding and decoding steps, adding slight processing overhead compared to native JSON parsing. Third, the format is newer and less widely supported than JSON, meaning you'll need specific libraries and may face compatibility challenges with some tools. Fourth, debugging can be slightly harder since most developer tools expect JSON format. Fifth, the format doesn't support comments in the official specification, though some implementations add this feature. Sixth, for very small datasets (fewer than 3-4 objects), the header overhead might actually result in more tokens than JSON. Seventh, streaming large TOON files requires special handling to maintain the schema context. Eighth, not all LLMs are equally proficient at parsing TOON, though major models like GPT-4 and Claude handle it well. Despite these limitations, TOON remains an excellent choice for its intended use case: reducing token consumption when sending structured data to LLMs.

What Are Best Practices for Using TOON with LLMs?

To maximize the benefits of TOON when working with LLMs, follow these best practices: 1) Always validate your JSON before converting to TOON to avoid encoding errors. 2) Use code blocks with the 'toon' language identifier to help LLMs recognize the format. 3) For complex schemas, provide a small example in your system prompt to prime the model. 4) When expecting TOON output, include the header template you want the LLM to follow. 5) Consider using tab delimiters instead of commas for even better token efficiency with some tokenizers. 6) Test your prompts with both JSON and TOON to measure actual token savings for your specific use case. 7) Keep the TOON specification handy for edge cases like special characters and nested structures. 8) Use the streaming APIs for large datasets to manage memory efficiently. 9) Cache converted TOON data when possible to avoid repeated encoding. 10) Monitor your token usage before and after adopting TOON to quantify savings. 11) Consider hybrid approaches where you use TOON for data-heavy sections and JSON for smaller, more complex structures. 12) Stay updated with the TOON specification as the format continues to evolve with community feedback.