TOON (Token-Oriented Object Notation): A Smarter, Lighter JSON for LLMs

In the era of AI and Large Language Models (LLMs), the efficiency of data formats is no longer just a matter of "optimization"; it has become a direct driver of cost and performance. JSON (JavaScript Object Notation), the standard data carrier of the web for years, struck a perfect balance between human readability and machine parsability. But once the "token" economy of LLMs came into play, JSON's curly braces, quotation marks and repeated keys started to become an expensive burden.

This is where TOON (Token-Oriented Object Notation) enters the stage. A more compact, "token-friendly" alternative to the JSON data model designed specifically for LLMs, TOON is on its way to becoming a new standard in data representation. In this post, I will take an in-depth look at what TOON is, how it works, how it differs from JSON and how you can use it in your projects.

JSON's "Token" Problem and the Birth of TOON

When you send data to an LLM (for example GPT-4 or Claude 3.5) or ask it for structured data, every character and symbol takes up part of your token quota. JSON is by nature a "verbose" format.

For example, when we represent a list of users in JSON, we write keys like id, name and email over and over for each user object. We also use double quotes for every string and curly braces {} for every object. In data with thousands of rows, these repetitions make up a significant share of the total token count.

TOON was developed to solve this problem. Its core promise is quite ambitious: 30% to 60% token savings compared to the standard JSON structure. And it does this without breaking the meaning or structure of the data; it supports exactly the same data types as JSON (object, array, string, number, boolean, null) but expresses them with a much smarter syntax.

TOON Syntax: How Does It Work?

TOON's syntax will feel quite familiar to developers who know Python or YAML. But TOON's real power lies in how it handles arrays.

1. Indentation-Based Structure

TOON uses indentation instead of curly braces to denote nested objects. This is a feature we know from YAML, and it significantly reduces visual noise.

2. Farewell to Quotation Marks

You do not need quotation marks for keys or simple text values. Quotes may only be needed for text that contains special characters.

3. Table-Like Arrays (The Killer Feature!)

TOON's most revolutionary feature is how it compresses uniform object arrays. While JSON repeats the key names on every row, TOON treats this like a CSV table: it defines the headers first and then writes the data row by row.

Let's see this difference with a concrete example.

Example: A User List

Below, we see the JSON and TOON versions of a simple user database side by side.

Standard JSON:

{
  "metadata": {
    "total_users": 2,
    "source": "database"
  },
  "users": [
    {
      "id": 1,
      "username": "aliyildiz",
      "role": "admin",
      "active": true
    },
    {
      "id": 2,
      "username": "aysekara",
      "role": "editor",
      "active": false
    }
  ]
}

This JSON format is readable but contains a lot of repetition. Now let's look at the same data in TOON format:

TOON Format:

metadata:
  total_users: 2
  source: database
users[2]{id,username,role,active}:
  1,aliyildiz,admin,true
  2,aysekara,editor,false

Do You See the Difference?

1. There are no curly braces for the metadata object, only indentation. 2. When the users array is defined, the expression users[2] declares the length of the array (2 items) up front. This helps the LLM "plan" (look ahead) how much data it will write when generating output. 3. The {id,username,role,active} part defines the schema of the objects in this array once. 4. In the rows below, id, username and so on are not repeated; only the values are written, separated by commas.

This structure achieves an incredible compression ratio as the dataset grows. In a list of 1,000 users, you would have to write "username": 1,000 times in JSON, while in TOON you write it only once.

Why Is It Better for LLMs?

TOON does not just mean "fewer characters"; it is better suited to how LLMs work (probabilistic token prediction).

1. Deterministic and Predictable

Explicit length declarations like users[2] help the model better understand when to stop or when to move on to the next block. In JSON, waiting for the closing bracket ] can sometimes cause models to hallucinate or break the structure too early.

2. Context Window Efficiency

LLMs have a "memory" limit (the context window). Even if you have a 128k-token window, you would rather fill that space with more business logic or richer data than with unnecessary JSON syntax. TOON lets you fit 50% more data into the same context window.

3. Lower API Costs

When using the OpenAI, Anthropic or Google Gemini APIs, you pay for both the tokens you send (input) and the tokens you receive (output). Converting your data format to TOON can directly cut your bill by 30-40% in high-volume applications.

Library Support and Integration

If you are asking "So how do I use this?", the good news is that TOON has ready-made libraries for most modern languages.

There are currently official or community-supported parser and serializer libraries for TypeScript/JavaScript, Python, Go, Rust and .NET.

Example Usage with Python

If you use Python, you can add the toon library to your project (the package name is a hypothetical example; check the available libraries):

import toon
import json


data = {
    "users": [
        {"id": 1, "name": "Ali"},
        {"id": 2, "name": "Veli"}
    ]
}

# As JSON
json_output = json.dumps(data)
print(len(json_output)) # e.g. 65 characters

# As TOON
toon_output = toon.dumps(data)
print(toon_output)
# Output:
# users[2]{id,name}:
#   1,Ali
#   2,Veli

This simple switch makes a big difference, especially in RAG (Retrieval-Augmented Generation) systems when passing thousands of records pulled from a database to an LLM as context.

Use Cases: Where Does TOON Shine?

Will TOON replace JSON in every scenario? Probably not. Web browsers and REST APIs will keep using JSON for a long time. But TOON is unbeatable in these areas:

1. AI Agent Communication: Reducing token traffic in systems where multiple AI agents send data to each other. 2. Big Data Analysis (with LLMs): When having an LLM analyze a CSV or Excel file, giving it the structured but compressed TOON format instead of raw CSV helps the model better understand the columns and data types. 3. Configuration Files: Thanks to its readability, it is a strong alternative to YAML for complex config files. 4. Log Compression: It saves space when storing system logs or sending them for analysis.

Advantages and Disadvantages

To sum up from an objective point of view:

Advantages:

* ✅ High token efficiency (30-60% savings). * ✅ Much cleaner and more readable for the human eye. * ✅ Easier for LLMs to grasp the structure. * ✅ Data types fully compatible with JSON.

Disadvantages:

* ❌ Not yet a universal standard like JSON. * ❌ Library support in every language may not be as mature as JSON's. * ❌ No built-in support on the browser side like JSON.parse(); it requires an external library.

Conclusion

As AI technologies evolve, the quality and format of the "fuel" (data) we give them evolve too. TOON is a logical step in this evolution. If your application uses LLMs heavily, processes database output or token costs are straining your budget, now is a great time to give TOON a chance.

I would say the day is not far off when models prefer the TOON format by default and we see "TOON mode" options instead of "JSON mode" in API documentation.

If you also want to increase data efficiency in your projects, you can review the specifications at toonformat.dev (example link) and start experimenting.