TOON Syntax Guide — From Scalars to Tabular Data

De fleste dataformater ble designet for ett publikum: mennesker eller maskiner. JSON lener seg mot mennesker. Binære formater som MessagePack lener seg mot maskiner. TOON er eksplisitt designet for et tredje publikum som ikke eksisterte da disse formatene ble oppfunnet: store språkmodeller. Alle syntaks-beslutninger i TOON prioriterer tokeneffektivitet — å pakke maksimalt strukturerte data inn i minimale tokens slik at du kan sende mer kontekst til en AI uten å sprenge budsjettet ditt. Denne veiledningen dekker alle TOON-syntaks-funksjoner, fra enkle skalarer til tabellnotasjonen som gjør det genuint annerledes.

Hva gjør TOON annerledes

TOON står for Token-Optimised Object Notation. Kjernekonceptet er enkelt: dataserialiseringsformater som JSON ble designet lenge før per-token API-prissetting var en ting. JSON er fint for maskin-til-maskin-kommunikasjon, men når payloaden din er et datasett med 200 rader på vei inn i en gpt-4o-prompt, betaler du for hvert anførselstegn, hvert krøllet parentes og hvert gjentatt nøkkelnavn. TOON eliminerer dette sløseriet. Det installeres som en enkelt npm-pakke — @toon-format/toon — og filer bruker .toon-utvidelsen.

Skalarverdier — strenger, tall, boolske verdier

TOON-skalarer ligner veldig på sine JSON-motparter, med én viktig forskjell: strengverdier krever ikke anførselstegn med mindre de inneholder spesialtegn som kommaer, kolon eller parenteser. Dette alene kutter en meningsfull mengde tokens fra teksttunge datasett.

// 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

Når en streng inneholder et komma, kolon eller parentes, omgir du den med doble anførselstegn akkurat som JSON. Så "New York, NY" trenger anførselstegn, men London gjør det ikke. Enkel regel, store besparelser.

Objekter — nøkkel:verdi-par uten støyen

TOON-objekter bruker krøllede parenteser med en nøkkel:verdi-syntaks. Nøkler er aldri sitert — det alene sparer to tegn per nøkkel sammenlignet med JSON. Par er kommaseparerte. Ingen etterfølgende kommaer, ingen kolon etter det siste paret.

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

Sammenlign det med tilsvarende JSON:

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

Samme data, færre tegn, og tokenbesparelsene vokser dramatisk når du jobber med arrays av objekter. I den forbindelsen...

Arrays — ordnede lister av verdier

Arrays i TOON bruker firkantede parenteser med kommaseparerte verdier — akkurat som JSON, bare uten anførselstegn på bare strengverdier.

// 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 av objekter fungerer, men det er her TOONs killer-funksjon kommer inn. Hvis du har mer enn to eller tre rader med strukturerte data, er tabellnotasjonen dramatisk mer effektiv.

Tabellnotasjon — funksjonen som endrer alt

Tabellnotasjon er TOONs overskriftsfunksjon. Den er designet for scenariet du støter på konstant i virkelig arbeid: en liste over lignende objekter — produkter, brukere, transaksjoner, loggoppføringer — der gjentakelse av nøklene på hver rad er rent sløseri. Syntaksen er:

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

For å bryte det ned: name er datasettets etikett, [count] er antallet datarader (påkrevd — det forteller parseren nøyaktig hvor mange linjer som skal leses), {col1,col2,...} er overskriftsraden, kolonet : avslutter overskriften, og hver påfølgende innrykket linje er én rad med verdier. Her er et virkelig produkteksempel:

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

Forestill deg nå de samme dataene som et array av JSON-objekter. Du ville skrevet "id", "name", "price", "inStock" og "category" fem ganger hver — pluss alle de omkringliggende krøllede parentesene, firkantede parentesene og anførselstegnene. Den tabellformede TOON-representasjonen er omtrent 60% mindre i tokenantall for denne formen for data.

Et brukerdatasett følger det samme mønsteret:

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 — objekter, arrays og tabeller sammen

TOON støtter nesting på stedene du ville forvente det. Et objekt kan inneholde en array-verdi. En tabellrad kan inneholde et objekt. Dette lar deg representere virkelighetsnære data som ikke passer perfekt inn i flate rader.

Objekt som inneholder et array:

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

Tabelldata med et innebygd objekt i én kolonne (nyttig for adressedata, metadata osv.):

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}

Hold nestingen grunn når det er mulig. To eller tre nivåer dypt er der TOON fortsatt vinner på tokenantall. Dypt rekursive strukturer er bedre tjent med JSON, som har rikere verktøy for skjemavalidering — se MDN JSON-referansen hvis du trenger det.

Jobbe med npm-pakken

Installer med npm eller en kompatibel pakkebehandler. TOON fungerer i Node.js og moderne nettlesere.

npm install @toon-format/toon

Pakken eksporterer to funksjoner: encode og decode. Det er hele det offentlige API-et — bevisst minimalt.

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

Alternativet { indent: 2 } styrer innrykkingen av radverdier. Du kan også bruke encode på vanlige objekter og primitive verdier, ikke bare arrays — den velger automatisk den mest kompakte TOON-representasjonen. Lim utdataene inn i TOON Formatter for å inspisere og pent skrive ut.

Vanlige feil

Dette er feilene som biter utviklere som er nye til TOON, vanligvis innen den første timen:

• Feil radtall i tabellnotasjon. Å skrive products[3] men deretter inkludere 4 datarader vil forårsake en parse-feil eller stille droppe den siste raden avhengig av parserversjonen. Tell radene dine og hold tallet oppdatert. TOON Validator oppdager dette umiddelbart.
• Sitere objektnøkler. {"name":Alice} er ugyldig TOON — nøkler er aldri sitert. Dropp anførselstegnene: {name:Alice}.
• Glemme kolonet etter overskriften. products[2]{id,name} etterfulgt av et linjeskift vil feile. Du trenger det etterfølgende kolonet: products[2]{id,name}:.
• Bruke mellomrom rundt kolonet i nøkkel:verdi-par. {name : Alice} er ikke gyldig. Ingen mellomrom: {name:Alice}.
• Bygge inn kommaer i usiterte strengverdier. Hvis et produktnavn er "Bolts, Nuts & More", må du sitere det i tabelrader: 101,"Bolts, Nuts & More",4.99,true.
• Forvente JSON-utdata fra decode på skalarer. decode("42") returnerer JavaScript-tallet 42, ikke et JSON-objekt. TOON dekoder til native JS-typer.

Konvertering mellom TOON og JSON

TOON og JSON er fullt inkonvertible — TOON er et supersett av den samme logiske datamodellen som JSON serialiserer. Bruk JSON til TOON for å krympe et eksisterende datasett før du sender det til en LLM, og TOON til JSON for å konvertere tilbake når du trenger å mate resultatet inn i et JSON-ekslusivt nedstrøms-system. Funksjonene encode og decode håndterer dette programmatisk hvis du automatiserer arbeidsflyten i Node.js. Den underliggende datastrukturspesifikasjonen er nært beslektet med konsepter fra JSON-globalen i JavaScript.

Oppsummering

TOON-syntaks er bevisst kompakt. Ingen siterte nøkler, ingen gjentatte nøkkelnavn i tabeller, ingen obligatoriske anførselstegn på enkle strengverdier. Når du én gang har skrevet en tabellblokk for hånd, vil du umiddelbart forstå hvorfor — et datasett som tar 40 linjer i JSON passer i 8 linjer TOON. npm-pakken på npmjs.com/@toon-format/toon holder API-overflaten liten: encode og decode, ingenting annet å lære. Bruk TOON Formatter for pent utskrift, TOON Validator for å fange syntaksfeil, JSON til TOON for å konvertere eksisterende data, og TOON til JSON når du trenger resultatet tilbake i standardform.