TOON Syntax Guide — From Scalars to Tabular Data

De fleste dataformater var designet til ét publikum: mennesker eller maskiner. JSON hælder mod mennesker. Binære formater som MessagePack hælder mod maskiner. TOON er eksplicit designet til et tredje publikum, der ikke eksisterede, da disse formater blev opfundet: store sprogmodeller. Alle syntaks-beslutninger i TOON prioriterer tokeneffektivitet — at pakke maksimalt strukturerede data ind i minimale tokens så du kan sende mere kontekst til en AI uden at sprænge dit budget. Denne guide dækker alle TOON-syntaks-funktioner, fra simple skalarer til den tabelnotation, der gør det genuint anderledes.

Hvad gør TOON anderledes

TOON står for Token-Optimised Object Notation. Kernekonceptet er simpelt: dataserialiseringsformater som JSON blev designet længe før pr.-token API-prisfastsættelse var en ting. JSON er fint til maskine-til-maskine-kommunikation, men når din payload er et datasæt med 200 rækker, der er på vej ind i en gpt-4o-prompt, betaler du for hvert anførselstegn, hvert krøllet parentes og hvert gentaget nøglenavn. TOON eliminerer dette spild. Det installeres som en enkelt npm-pakke — @toon-format/toon — og filer bruger .toon-udvidelsen.

Skalarværdier — strenge, tal, booleaner

TOON-skalarer ligner meget deres JSON-modparter, med én vigtig forskel: strengværdier kræver ikke anførselstegn, medmindre de indeholder specialtegn som kommaer, kolon eller parenteser. Dette alene skærer en meningsfuld mængde tokens fra tekst-tunge datasæt.

// 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 indeholder et komma, kolon eller parentes, omgiv den med dobbelte anførselstegn ligesom JSON. Så "New York, NY" har brug for anførselstegn, men London gør det ikke. Simpel regel, store besparelser.

Objekter — nøgle:værdi-par uden støjen

TOON-objekter bruger krøllede parenteser med en nøgle:værdi-syntaks. Nøgler er aldrig citeret — det alene sparer to tegn pr. nøgle sammenlignet med JSON. Par er kommaseparerede. Ingen efterfølgende kommaer, ingen kolon efter det sidste par.

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

Sammenlign det med den tilsvarende JSON:

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

Samme data, færre tegn, og tokenbesparelserne vokser dramatisk, når du arbejder med arrays af objekter. Derom mere...

Arrays — ordnede lister af værdier

Arrays i TOON bruger firkantede parenteser med kommaseparerede værdier — præcis som JSON, bare uden anførselstegn på bare strengværdier.

// 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 af objekter virker, men det er her TOONs killer-funktion kommer i spil. Hvis du har mere end to eller tre rækker af strukturerede data, er tabelnotationen dramatisk mere effektiv.

Tabelnotation — funktionen der ændrer alt

Tabelnotation er TOONs overskriftsfunktion. Den er designet til det scenarie, du konstant støder på i rigtigt arbejde: en liste over lignende objekter — produkter, brugere, transaktioner, logposter — hvor gentagelse af nøglerne på hver række er rent spild. Syntaksen er:

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

For at bryde det ned: name er datasættets label, [count] er antallet af datarækker (påkrævet — det fortæller parseren præcis, hvor mange linjer der skal læses), {col1,col2,...} er header-rækken, kolonet : afslutter headeren, og hver efterfølgende indrykket linje er én række af værdier. Her er et reelt 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

Forestil dig nu de samme data som et array af JSON-objekter. Du ville skrive "id", "name", "price", "inStock" og "category" fem gange hver — plus alle de omgivende krøllede parenteser, firkantede parenteser og anførselstegn. Den tabelformede TOON-repræsentation er omtrent 60% mindre i tokenantal for denne form for data.

Et brugerdatasæt følger det samme mønster:

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

Indlejring — objekter, arrays og tabeller sammen

TOON understøtter indlejring de steder, du ville forvente. Et objekt kan indeholde en arrayværdi. En tabelrække kan indeholde et objekt. Dette lader dig repræsentere virkelighedsnære data, der ikke passer perfekt ind i flade rækker.

Objekt der indeholder et array:

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

Tabeldata med et indlejret objekt i én kolonne (nyttigt til 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 indlejringen overfladisk, når det er muligt. To eller tre niveauer dybt er, hvor TOON stadig vinder på tokenantal. Dybt rekursive strukturer er bedre tjent med JSON, der har rigere værktøjer til skemavalidering — se MDN JSON reference hvis du har brug for det.

Arbejde med npm-pakken

Installer med npm eller en kompatibel pakkehåndtering. TOON virker i Node.js og moderne browsere.

npm install @toon-format/toon

Pakken eksporterer to funktioner: encode og decode. Det er hele den offentlige API — bevidst minimal.

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

Indstillingen { indent: 2 } styrer indrykning af rækkeværdier. Du kan også bruge encode på almindelige objekter og primitive værdier, ikke kun arrays — den vælger automatisk den mest kompakte TOON-repræsentation. Indsæt outputtet i TOON Formatter for at inspicere og formatere det pænt.

Almindelige fejl

Dette er de fejl, der bider udviklere, der er nye til TOON, normalt inden for den første time:

• Forkert rækketal i tabelnotation. At skrive products[3] men derefter inkludere 4 datarækker vil forårsage en parse-fejl eller stille droppe den sidste række afhængigt af parserversionen. Tæl dine rækker og hold tallet opdateret. TOON Validator opdager dette øjeblikkeligt.
• Citere objektnøgler. {"name":Alice} er ugyldig TOON — nøgler er aldrig citeret. Drop anførselstegnene: {name:Alice}.
• Glemme kolonet efter headeren. products[2]{id,name} efterfulgt af et linjeskift vil fejle. Du har brug for det efterfølgende kolon: products[2]{id,name}:.
• Bruge mellemrum omkring kolonet i nøgle:værdi-par. {name : Alice} er ikke gyldigt. Ingen mellemrum: {name:Alice}.
• Indlejre kommaer i ikke-citerede strengværdier. Hvis et produktnavn er "Bolts, Nuts & More", skal du citere det i tabelrækker: 101,"Bolts, Nuts & More",4.99,true.
• Forvente JSON-output fra decode på skalarer. decode("42") returnerer JavaScript-tallet 42, ikke et JSON-objekt. TOON dekoder til native JS-typer.

Konvertering mellem TOON og JSON

TOON og JSON er fuldt indbyrdes konverterbare — TOON er en overbygning af den samme logiske datamodel, som JSON serialiserer. Brug JSON til TOON til at skrumpe et eksisterende datasæt, før du sender det til en LLM, og TOON til JSON til at konvertere tilbage, når du skal videregive resultatet til et JSON-eksklusivt downstream-system. Funktionerne encode og decode håndterer dette programmatisk, hvis du automatiserer arbejdsgangen i Node.js. Den underliggende datastrukturspecifikation er tæt relateret til koncepter fra JSON-globalen i JavaScript.

Opsummering

TOON-syntaks er bevidst kompakt. Ingen citerede nøgler, ingen gentagne nøglenavne i tabeller, ingen obligatoriske anførselstegn på simple strengværdier. Når du én gang har skrevet en tabelblok i hånden, vil du straks forstå hvorfor — et datasæt, der fylder 40 linjer i JSON, passer ind i 8 linjer i TOON. npm-pakken på npmjs.com/@toon-format/toon holder API-overfladen lille: encode og decode, intet andet at lære. Brug TOON Formatter til at formatere pænt, TOON Validator til at opdage syntaksfejl, JSON til TOON til at konvertere dine eksisterende data, og TOON til JSON, når du har brug for resultatet tilbage i standardform.