De meeste ontwikkelaars hebben een korte mentale lijst van dataformaten: JSON voor API's, CSV voor spreadsheets, YAML voor configuratiebestanden, misschien XML als je met legacy-systemen werkt. Maar er is een nieuwer formaat dat stilletjes zijn weg baant in de AI-toolingwereld en het waard is om te kennen — TOON, of Token-Oriented Object Notation. Het is van de grond af ontworpen voor een specifiek probleem: gestructureerde data doorgeven aan grote taalmodellen zonder je tokenbudget op te branden.

Wat is TOON?

TOON staat voor Token-Oriented Object Notation. Het is een compact dataserialisatieformaat speciaal gebouwd om het aantal tokens te minimaliseren dat wordt verbruikt wanneer gestructureerde data wordt ingesloten in LLM-prompts of -antwoorden. Zie het als JSON met alle breedsprakigheid eruit gehaald — geen herhaalde sleutelnamen in arrays, geen overbodige aanhalingstekens, geen afsluitende spaties — alleen het signaal met zo min mogelijk syntactische ruis.

Het npm-pakket is @toon-format/toon, en het biedt een eenvoudige encode / decode API die werkt in elk Node.js-project of moderne bundler. TOON-bestanden gebruiken de extensie .toon.

Waarom niet gewoon JSON gebruiken?

JSON is uitstekend voor machine-naar-machine communicatie waarbij bandbreedte goedkoop is en parsing door de runtime wordt afgehandeld. Maar wanneer je data verzendt als onderdeel van een prompt naar de OpenAI API of de Anthropic API, telt elk teken — letterlijk. Beide API's rekenen per token, en tokens komen overeen met ongeveer 4 tekens Engelse tekst.

Stel je een tabel met 100 gebruikersrecords voor. In JSON zou je de sleutels herhalen — "id", "name", "role", "email" — één keer per record. Dat zijn 100 kopieën van dezelfde structurele informatie. De tabulaire syntaxis van TOON definieert die sleutels één keer en somt waarden rij voor rij op, op dezelfde manier als een CSV, maar met de objectstructuur behouden. De tokenbesparing op real-world datasets kan 40–70% zijn vergeleken met compacte JSON.

Vuistregel: Als je meer dan een handvol records in een prompt insluit, zal TOON bijna altijd goedkoper zijn dan JSON. Gebruik onze JSON naar TOON converter om te zien hoeveel kleiner je payload wordt.

TOON-syntaxis in één oogopslag

TOON ondersteunt vier kerngegevensvormen: scalars (strings, getallen, booleans), arrays, objecten en tabulaire data. De scalar- en collectiesyntaxis zal bekend aanvoelen als je met JSON hebt gewerkt — het tabulaire formaat is waar TOON zich echt onderscheidt.

Een eenvoudig object verwijdert de witruimte van de buitenste accolades, laat onnodige aanhalingstekens weg, en scheidt sleutel-waardeparen met komma's:

text
{name:Alice,age:30,role:admin}

Een eenvoudige array van scalars ziet er precies uit zoals je zou verwachten:

text
[1,2,3]

Nu wordt het interessant — tabulaire data. Dit is de syntaxis die TOON overtuigend maakt voor LLM-gebruiksscenario's. In plaats van sleutels te herhalen voor elk object in een array, declareer je het schema één keer in de header en geef je waarden rij voor rij op:

text
users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Dat blok vertegenwoordigt een array van 3 gebruikersobjecten — equivalent aan de onderstaande JSON — maar in een fractie van de tokens. De header users[3]{id,name,role} vertelt een parser: "dit is een variabele genaamd users, het heeft 3 rijen, en elke rij komt overeen met de velden id, name en role". De rijen zijn pure waarden, geen sleutelherhalingen.

json
[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

Het @toon-format/toon-pakket installeren en gebruiken

Het officiële npm-pakket behandelt zowel het coderen van JavaScript-waarden naar TOON-strings als het decoderen van TOON-strings terug naar JavaScript-objecten en -arrays. Installeer het vanuit het npm-register:

bash
npm install @toon-format/toon

Het pakket exporteert twee functies — encode en decode:

ts
import { encode, decode } from '@toon-format/toon';

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

De indent-optie in encode() bepaalt of de uitvoer mooi wordt opgemaakt. Voor LLM-prompts wil je meestal compacte uitvoer (geen inspringing) om tokens te besparen. Voor foutopsporing of voor mensen leesbare .toon-bestanden geeft { indent: 2 } je netjes opgemaakte uitvoer.

Een praktisch gebruik: Records naar een LLM sturen

Stel je voor dat je een productanalysefunctie bouwt die gebruikersactiviteit moet samenvatten. Je haalt recente sessierecords op uit je database en wilt ze naar een LLM sturen voor samenvatting in natuurlijke taal. Zo ziet dat eruit met TOON:

ts
import { encode } from '@toon-format/toon';

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

De TOON-representatie van die 5 sessierecords is aanzienlijk korter dan de equivalente JSON, die "userId", "action", "duration" en "page" vijf keer zou herhalen. Over honderden records zijn de besparingen substantieel en vertalen ze zich direct naar lagere API-kosten en snellere responstijden (minder tokens om te verwerken in het aandachtsvenster).

Belangrijkste gegevenstypen in TOON

TOON mapt netjes op de primitieven die je al gebruikt in JavaScript en de meeste andere talen:

  • Strings — Zonder aanhalingstekens wanneer ze geen speciale tekens bevatten. Tussen dubbele aanhalingstekens wanneer ze komma's, dubbele punten of witruimte bevatten.
  • Getallen — Gehele getallen en floats zoals ze zijn: 42, 3.14, -7.
  • Booleans — true en false, hetzelfde als JSON.
  • Null — Geschreven als null voor afwezige of ongedefinieerde waarden.
  • Arrays — Inline haaklensyntaxis [val1,val2,val3] voor korte lijsten; tabulaire headersyntaxis voor arrays van objecten.
  • Objecten — Accoladensyntaxis {key:value,key2:value2} voor enkele objecten.
  • Tabulaire data — De ster van de show: name[n]{col1,col2,...}: header gevolgd door door komma's gescheiden rijen — ideaal voor elke verzameling records met dezelfde vorm.

Wanneer TOON gebruiken versus andere formaten

TOON probeert JSON niet te vervangen als algemeen uitwisselingsformaat. Het vult een specifieke niche. Hier is een snelle beslissingsgids:

  • Gebruik JSON wanneer je REST API's bouwt, documenten opslaat in een database of data doorgeeft tussen services. JSON wordt universeel ondersteund, heeft goede tools en is leesbaar voor mensen.
  • Gebruik TOON wanneer gestructureerde data deel uitmaakt van een prompt of LLM-contextvenster en het aantal tokens ertoe doet. Het tabulaire formaat schittert wanneer je werkt met rijen records — gebruikerslijsten, logvermeldingen, productcatalogi, analysegebeurtenissen.
  • Gebruik CSV wanneer je alleen platte tabulaire data nodig hebt en de consumer CSV verwacht (spreadsheets, BI-tools). CSV heeft geen objectnesting, dus TOON is expressiever.
  • Gebruik YAML voor door mensen bewerkte configuratiebestanden waar leesbaarheid en commentaar belangrijker zijn dan compactheid.
  • Gebruik TOON ook voor LLM-tool-uitvoer: als een LLM je tool aanroept en gestructureerde resultaten retourneert, bespaart het coderen van die resultaten in TOON tokens aan zowel de invoer- als uitvoerkant van de API-aanroep.
Weet je niet hoe TOON zich verhoudt tot je huidige JSON-payload? Gooi je JSON in de JSON naar TOON converter en de tool toont je beide representaties naast elkaar, samen met een geschatte vergelijking van het aantal tokens.

Samenvatting

TOON — Token-Oriented Object Notation — is een compact serialisatieformaat gebouwd voor het LLM-tijdperk. Het behoudt de vertrouwde structuur van JSON (objecten, arrays, scalars) en introduceert een tabulaire syntaxis die redundante sleutelherhalingen over records elimineert. Het resultaat is een formaat dat 40–70% kleiner kan zijn dan equivalente JSON, wat zich direct vertaalt naar lagere tokenkosten bij het werken met de OpenAI API, Anthropic API, of elke andere op tokens gefactureerde LLM-service.

Als je TOON hands-on wil verkennen, hebben we hier een complete suite tools: gebruik de TOON Formatter om TOON-documenten mooi op te maken en te inspecteren, de TOON Validator om syntaxfouten op te sporen, de JSON naar TOON converter om bestaande payloads te migreren, en de TOON naar JSON converter als je de andere kant op moet. Het npm-pakket @toon-format/toon geeft je encode en decode om TOON direct te integreren in je Node.js- of browser-zijdige code in minuten.

← All TOON articles Browse all categories →