TOON vs JSON vs CSV — Het juiste formaat kiezen

Drie formaten lopen een planningsvergadering in. JSON zegt dat het alles aankan. CSV zegt dat het snel en slank is. TOON zegt dat het er is om met de AI te praten. Ze hebben allemaal gelijk — voor verschillende taken. Het frustrerende deel is niet dat deze formaten bestaan, het is dat het kiezen van het verkeerde formaat voor jouw gebruiksscenario je op echte, concrete manieren kost: uitgebreide payloads, mislukte imports, dure LLM-rekeningen, of parse-hoofdpijn. Deze gids geeft je een duidelijk kader voor de keuze.

Een snel portret van elk formaat

JSON (JavaScript Object Notation) is begin jaren 2000 ontstaan uit JavaScript en werd het dominante formaat voor web-API's dankzij zijn eenvoud en expressiviteit. Het verwerkt geneste structuren native, onderscheidt tussen strings, getallen, booleans en nulls zonder extra ceremonie, en is gespecificeerd door RFC 8259. Elke moderne taal heeft een eersteklas JSON-bibliotheek.

CSV (Comma-Separated Values) is ouder dan het web. Het is gedefinieerd door RFC 4180 en is in wezen de lingua franca van platte tabulaire data. Open een CSV in Excel, Google Sheets, of Numbers en het werkt gewoon. Voor puur platte tabellen is het het meest compacte en universeel importeerbare formaat dat bestaat.

TOON is een nieuwer formaat specifiek gebouwd voor LLM-workflows. Het haalt inspiratie uit beide — zoals CSV gebruikt het een header-één-keer-dan-rijen-structuur voor tabulaire data, maar zoals JSON kan het ook geneste objecten en arrays coderen. Het volledige ontwerp is gericht op het minimaliseren van het tokenaantal wanneer data heen en weer wordt doorgegeven aan grote taalmodellen.

Dezelfde data in alle drie de formaten

Om dit concreet te maken, gebruiken we een productcatalogus die een genest specs-object bevat — een real-world vorm die alle drie de formaten zinvol oefent. Hier zijn vier producten van een elektronica-winkel:

JSON — expressief, verwerkt nesting natuurlijk, maar uitgebreid voor repetitieve rijdata:

[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — compact, Excel-vriendelijk, maar het geneste specs-object moet worden afgevlakt. Er is geen standaardmanier om het weer te geven, dus we verliezen ofwel de nesting of vervormen het tot een string:

id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440

TOON — header één keer gedeclareerd, rijen zijn compact, geneste objecten inline gecodeerd:

products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

Waar elk formaat tekortschiet

De faalwijzen begrijpen is even belangrijk als de sterke punten kennen.

• JSON schiet tekort voor tabellen. Elke sleutelnaam op elke rij herhalen is echt verspillend. Een dataset van 1000 rijen waarbij elke rij 8 sleutels heeft, betekent "id", "name", "price" enzovoort elk 1000 keer geschreven. Voor LLM-invoer vertaalt dit zich direct naar tokenkosten; voor menselijke inspectie is het gewoon ruis.
• CSV schiet tekort voor geneste data. Het formaat heeft geen concept van nesting. Je kunt een genest object in een cel omzetten naar een string, maar dan moet de consumer weten om die cel te parsen — je hebt het probleem gewoon verplaatst. CSV heeft ook geen native typesysteem: true is een string, 42 is een string, null is dubbelzinnig. Tools gaan hier inconsistent mee om.
• TOON schiet tekort buiten LLM-contexten. Het is een niche-formaat met een smaller ecosysteem. Je zult geen native TOON-ondersteuning vinden in PostgreSQL, in je REST-framework, of in Excel. Het npm-pakket dekt JavaScript/TypeScript-workflows goed, maar als je TOON gebruikt in een context die niets met AI te maken heeft, overengineer je waarschijnlijk.
• CSV schiet tekort voor waarden die komma's of regeleinden bevatten. De RFC 4180-quoting- regels behandelen dit, maar veel CSV-producenten en -consumers implementeren ze inconsistent. Een productnaam zoals 27" IPS Monitor, Black of een beschrijving met regelbreuken wordt een betrouwbaarheidsrisico.

Beslissingsmatrix

Hier is een praktische gids. Koppel je situatie aan het juiste formaat:

• Je data gaat in een LLM-prompt → TOON. Vooral als het tabulair is. Gebruik JSON naar TOON om te converteren vóór de API-aanroep.
• Je data komt terug van een LLM en moet worden verwerkt → TOON (voor uitvoer), decodeer dan naar JSON of een native object voor downstream gebruik met TOON naar JSON.
• Je data is puur plat tabulair (dezelfde sleutels op elke rij) en gaat naar/van spreadsheets → CSV. Het is de kleinste representatie en universeel importeerbaar.
• Je data is plat tabulair maar wordt getransformeerd door code (niet door spreadsheets) → CSV of JSON. JSON is veiliger als typen er toe doen (je wilt geen "true" in plaats van true).
• Je data heeft geneste objecten of arrays → JSON. Vecht niet tegen de alleen-platte beperking van CSV. Als nesting naar een LLM gaat, codeer naar TOON na het bouwen van de structuur.
• Je data gaat naar een REST API of wordt opgeslagen in een database → JSON. Altijd.
• Je data is een configuratiebestand → JSON of YAML. Noch CSV noch TOON hoort hier thuis.
• Je hebt maximale portabiliteit en een afhankelijkheidsvrije parser nodig → JSON of CSV. Beide hebben native of bijna-native ondersteuning overal.

Alle drie gebruiken in één pijplijn

Een realistische pijplijn kan alle drie gebruiken. Stel je een e-commerce workflow voor die productdata verrijkt met door AI gegenereerde beschrijvingen:

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

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

JSON voor de API-laag, TOON door de LLM-laag, CSV voor de voor mensen leesbare uitvoer. Elk formaat doet precies het werk waarvoor het is ontworpen.

Snelle toolreferentie

Als je tussen deze formaten beweegt, dekken deze tools de gangbare conversies. De TOON Formatter is de snelste manier om TOON-strings te valideren en op te schonen. De JSON naar TOON converter verwerkt de LLM-voorbereidingsstap. In de andere richting nadat een LLM TOON retourneert, kan TOON naar CSV direct een spreadsheet-klare export produceren, en CSV naar JSON is de go-to voor het normaliseren van imports uit Excel of externe dataproviders. Voor TOON-specifieke details staat het officiële pakket op npm.

Samenvatting

JSON, CSV en TOON hebben elk een duidelijk domein. JSON is het universele formaat voor uitwisseling van gestructureerde data — genest of plat, API's, configuratie, opslag. CSV is het universele formaat voor platte tabulaire data die moet reizen tussen systemen en mensen — spreadsheets, imports, exports. TOON is het formaat voor het efficiënt doorgeven van gestructureerde data door AI-systemen, waar elk token telt. De fout die de meeste ontwikkelaars maken is standaard JSON gebruiken voor alles inclusief LLM-prompts, of standaard CSV gebruiken en dan nestingvereisten halverwege een project ontdekken. Ken de vorm van je data, weet waar het naartoe gaat, en het juiste formaat kiest zichzelf meestal.

Voor een diepere duik in de JSON vs TOON-afweging specifiek, bekijk de TOON vs JSON vergelijking. Voor achtergrondinformatie over de CSV-specificatie en zijn eigenaardigheden behandelt het Wikipedia-artikel over CSV de geschiedenis en formaatsvarianten goed.