TOON-syntaxgids — Van schaalwaarden tot tabelgegevens

De meeste dataformaten zijn ontworpen voor één publiek: mensen of machines. JSON neigt naar mensen. Binaire formaten zoals MessagePack neigen naar machines. TOON is expliciet ontworpen voor een derde publiek dat niet bestond toen die formaten werden uitgevonden: grote taalmodellen. Elke syntaxisbeslissing in TOON geeft prioriteit aan tokenefficiëntie — maximale gestructureerde data in minimale tokens passen zodat je meer context aan een AI kunt doorgeven zonder je budget op te blazen. Deze gids behandelt elke TOON-syntaxisfunctie, van eenvoudige scalars tot de tabulaire notatie die het echt anders maakt.

Wat TOON anders maakt

TOON staat voor Token-Optimised Object Notation. Het kernidee is eenvoudig: dataserialisatieformaten zoals JSON zijn ontworpen lang voordat per-token API-prijzen een ding waren. JSON is prima voor machine-naar-machine communicatie, maar wanneer je payload een dataset van 200 rijen is die in een gpt-4o-prompt gaat, betaal je voor elk aanhalingsteken, elke accolade en elke herhaalde sleutelnaam. TOON elimineert dat afval. Het installeert als een enkel npm-pakket — @toon-format/toon — en bestanden gebruiken de extensie .toon.

Scalairwaarden — Strings, Getallen, Booleans

TOON-scalars lijken erg op hun JSON-tegenhangers, met één belangrijk verschil: stringwaarden vereisen geen aanhalingstekens tenzij ze speciale tekens bevatten zoals komma's, dubbele punten of haken. Dit alleen al snijdt een betekenisvolle hoeveelheid tokens uit tekst-zware datasets.

// Numbers — exactly like JSON
42
3.14
-7

// Booleans — lowercase, same as JSON
true
false

// Strings — no quotes needed for simple values
hello
Alice
Widget Pro

Wanneer een string een komma, dubbele punt of haak bevat, zet hem dan in dubbele aanhalingstekens net als JSON. Dus "New York, NY" heeft aanhalingstekens nodig, maar London niet. Simpele regel, grote besparingen.

Objecten — Sleutel:Waarde-paren zonder de ruis

TOON-objecten gebruiken accolades met een sleutel:waarde-syntaxis. Sleutels worden nooit geciteerd — dat alleen al bespaart twee tekens per sleutel vergeleken met JSON. Paren zijn gescheiden door komma's. Geen afsluitende komma's, geen dubbele punten na het laatste paar.

{name:Alice,age:31,city:London,active:true}

Vergelijk dat met de equivalente JSON:

{"name": "Alice", "age": 31, "city": "London", "active": true}

Dezelfde data, minder tekens, en de tokenbesparingen vermenigvuldigen zich dramatisch wanneer je werkt met arrays van objecten. En dan...

Arrays — Geordende lijsten van waarden

Arrays in TOON gebruiken vierkante haken met door komma's gescheiden waarden — precies zoals JSON, alleen zonder aanhalingstekens bij eenvoudige stringwaarden.

// Array of strings
[Alice,Bob,Carol]

// Array of numbers
[10,20,30,40,50]

// Mixed types (same rules as JSON)
[Widget Pro,29.99,true,101]

// Array of objects
[{id:1,name:Alice},{id:2,name:Bob}]

Arrays van objecten werken, maar dit is waar TOON's killer-feature binnenkomt. Als je meer dan twee of drie rijen gestructureerde data hebt, is de tabulaire notatie dramatisch efficiënter.

Tabulaire notatie — De functie die alles verandert

Tabulaire notatie is TOON's hoofdfunctie. Het is ontworpen voor het scenario dat je constant tegenkomt in echt werk: een lijst van gelijksoortige objecten — producten, gebruikers, transacties, logvermeldingen — waarbij het herhalen van de sleutels op elke rij pure verspilling is. De syntaxis is:

name[count]{col1,col2,col3,...}:
  row1val1,row1val2,row1val3
  row2val1,row2val2,row2val3

Uitgelegd: name is het label van de dataset, [count] is het aantal datarijen (vereist — het vertelt de parser precies hoeveel regels te lezen), {col1,col2,...} is de headerrij, de dubbele punt : beëindigt de header, en elke volgende ingesprongen regel is één rij waarden. Hier is een echt productvoorbeeld:

products[5]{id,name,price,inStock,category}:
  101,Widget Pro,29.99,true,Tools
  102,Gadget Plus,49.99,true,Electronics
  103,Thing Basic,9.99,false,Misc
  104,Super Doohickey,74.99,true,Electronics
  105,Budget Widget,14.99,true,Tools

Stel je nu dezelfde data voor als een array van JSON-objecten. Je zou "id", "name", "price", "inStock" en "category" elk vijf keer schrijven — plus alle omringende accolades, haken en aanhalingstekens. De tabulaire TOON-representatie is ruwweg 60% kleiner in tokenaantal voor deze vorm van data.

Een gebruikersdataset volgt hetzelfde patroon:

users[4]{id,username,email,role,active}:
  1,alice_dev,[email protected],admin,true
  2,bob_writer,[email protected],editor,true
  3,carol_ops,[email protected],viewer,false
  4,dan_qa,[email protected],editor,true

Nesting — Objecten, Arrays en Tabulair samen

TOON ondersteunt nesting op de plaatsen die je zou verwachten. Een object kan een arraywaarde bevatten. Een tabulaire rij kan een object bevatten. Hiermee kun je echte data weergeven die niet perfect past in platte rijen.

Object met een array:

{name:Alice,roles:[admin,editor],active:true}

Tabulaire data met een ingebed object in één kolom (handig voor adresdata, metadata, enz.):

orders[3]{orderId,customer,total,address}:
  1001,alice_dev,89.97,{city:London,country:UK}
  1002,bob_writer,49.99,{city:Berlin,country:DE}
  1003,carol_ops,124.50,{city:Paris,country:FR}

Houd nesting zo ondiep mogelijk. Twee of drie niveaus diep is waar TOON nog steeds wint op tokenaantal. Diep recursieve structuren worden beter bediend door JSON, dat rijkere tooling heeft voor schemavalidatie — zie de MDN JSON-referentie als je dat nodig hebt.

Werken met het npm-pakket

Installeer met npm of een compatibele pakketbeheerder. TOON werkt in Node.js en moderne browsers.

npm install @toon-format/toon

Het pakket exporteert twee functies: encode en decode. Dat is de volledige publieke API — opzettelijk minimaal.

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

// decode: TOON string → JS value
const toonString = `products[3]{id,name,price,inStock}:
  101,Widget Pro,29.99,true
  102,Gadget Plus,49.99,true
  103,Thing Basic,9.99,false`;

const data = decode(toonString);
console.log(data);
// [
//   { id: 101, name: "Widget Pro", price: 29.99, inStock: true },
//   { id: 102, name: "Gadget Plus", price: 49.99, inStock: true },
//   { id: 103, name: "Thing Basic", price: 9.99, inStock: false }
// ]

// encode: JS value → TOON string
const users = [
  { id: 1, username: 'alice_dev', active: true },
  { id: 2, username: 'bob_writer', active: false }
];

const toon = encode(users, { indent: 2 });
console.log(toon);
// users[2]{id,username,active}:
//   1,alice_dev,true
//   2,bob_writer,false

De optie { indent: 2 } bestuurt de inspringing van rijwaarden. Je kunt ook encode gebruiken op gewone objecten en primitieve waarden, niet alleen arrays — het kiest automatisch de meest compacte TOON-representatie. Plak de uitvoer in de TOON Formatter om het te inspecteren en mooi op te maken.

Veelgemaakte fouten

Dit zijn de fouten die nieuwe TOON-ontwikkelaars bijten, gewoonlijk binnen het eerste uur:

• Verkeerd rijenaantal in tabulaire notatie. products[3] schrijven maar dan 4 datarijen opnemen zal een parse-fout veroorzaken of de laatste rij stilzwijgend verwijderen afhankelijk van de parserversie. Tel je rijen en houd het getal bijgewerkt. De TOON Validator pakt dit meteen op.
• Objectsleutels citeren. {"name":Alice} is ongeldige TOON — sleutels worden nooit geciteerd. Verwijder de aanhalingstekens: {name:Alice}.
• De dubbele punt na de header vergeten. products[2]{id,name} gevolgd door een nieuwe regel zal mislukken. Je hebt de afsluitende dubbele punt nodig: products[2]{id,name}:.
• Spaties rond de dubbele punt gebruiken in sleutel:waarde-paren. {name : Alice} is niet geldig. Geen spaties: {name:Alice}.
• Komma's insluiten in niet-geciteerde stringwaarden. Als een productnaam "Bouten, Moeren & Meer" is, moet je het citeren in tabulaire rijen: 101,"Bouten, Moeren & Meer",4.99,true.
• JSON-uitvoer verwachten van decode op scalars. decode("42") retourneert het JavaScript-getal 42, niet een JSON-object. TOON decodeert naar native JS-typen.

Converteren tussen TOON en JSON

TOON en JSON zijn volledig onderling converteerbaar — TOON is een superset van hetzelfde logische datamodel dat JSON serialiseert. Gebruik JSON naar TOON om een bestaande dataset te verkleinen voordat je hem naar een LLM stuurt, en TOON naar JSON om terug te converteren wanneer je het resultaat in een alleen-JSON downstream-systeem moet voeden. De functies encode en decode behandelen dit programmatisch als je de workflow automatiseert in Node.js. De onderliggende datastructuurspecificatie is nauw verwant aan concepten van het JSON-globaal in JavaScript.

Samenvatting

TOON-syntaxis is opzettelijk compact. Geen geciteerde sleutels, geen herhaalde sleutelnamen in tabellen, geen verplichte aanhalingstekens bij eenvoudige stringwaarden. Als je eenmaal een tabulair blok met de hand hebt geschreven zie je meteen waarom — een dataset die 40 regels JSON kost past in 8 regels TOON. Het npm-pakket op npmjs.com/@toon-format/toon houdt het API-oppervlak klein: encode en decode, verder niets te leren. Gebruik de TOON Formatter om mooi op te maken, TOON Validator om syntaxfouten op te sporen, JSON naar TOON om je bestaande data te converteren, en TOON naar JSON wanneer je het resultaat terug in standaardvorm nodig hebt.