TOON Syntax Guide — From Scalars to Tabular Data

De flesta dataformat designades för en publik: människor eller maskiner. JSON lutar mot människor. Binära format som MessagePack lutar mot maskiner. TOON är uttryckligen designat för en tredje publik som inte existerade när dessa format uppfanns: stora språkmodeller. Varje syntaxbeslut i TOON prioriterar tokeneffektivitet — att passa maximal strukturerad data i minimala tokens så att du kan skicka mer kontext till en AI utan att spränga din budget. Den här guiden täcker alla TOON-syntaxfunktioner, från enkla skalärer till tabellnotationen som gör det genuint annorlunda.

Vad som gör TOON annorlunda

TOON står för Token-Optimised Object Notation. Grundidén är enkel: dataserialiseringsformat som JSON designades långt innan API-prissättning per token var en grej. JSON är bra för maskin-till-maskin-kommunikation, men när din payload är ett 200-raders dataset på väg in i en gpt-4o-prompt, betalar du för varje citationstecken, varje klammer och varje upprepat nyckelnamn. TOON eliminerar det slöseriet. Det installeras som ett enda npm-paket — @toon-format/toon — och filer använder tillägget .toon.

Skalarvärden — strängar, tal, booleaner

TOON-skalärer ser mycket lika ut som deras JSON-motsvarigheter, med en viktig skillnad: strängvärden kräver inte citationstecken om de inte innehåller specialtecken som kommatecken, kolon eller hakparenteser. Detta ensamt skär bort en meningsfull del av tokens från texttunga dataset.

// 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 sträng innehåller ett kommatecken, kolon eller hakparentes, wrap:a den med dubbla citationstecken precis som JSON. Så "New York, NY" behöver citationstecken, men London gör det inte. Enkel regel, stora besparingar.

Objekt — nyckel:värde-par utan brus

TOON-objekt använder klamrar med nyckel:värde-syntax. Nycklar är aldrig citerade — det ensamt sparar två tecken per nyckel jämfört med JSON. Par är kommaseparerade. Inga efterföljande kommatecken, inga kolon efter det sista paret.

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

Jämför det med motsvarande JSON:

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

Samma data, färre tecken, och tokenbesparingarna förstärks dramatiskt när man arbetar med arrayer av objekt. Om det...

Arrayer — ordnade listor av värden

Arrayer i TOON använder hakparenteser med kommaseparerade värden — precis som JSON, bara utan citationstecken på enkla strängvärden.

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

Arrayer av objekt fungerar, men det är här TOONs mördarfunktion kommer in. Om du har mer än två eller tre rader strukturerad data är tabellnotationen dramatiskt mer effektiv.

Tabellnotation — funktionen som förändrar allt

Tabellnotation är TOONs huvudfunktion. Den designades för scenariot du ständigt stöter på i verkligt arbete: en lista med liknande objekt — produkter, användare, transaktioner, loggposter — där upprepning av nycklar på varje rad är rent slöseri. Syntaxen är:

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

Bryta ner det: name är datasatsets etikett, [count] är antalet datarader (obligatorisk — den talar om för parsern exakt hur många rader att läsa), {col1,col2,...} är rubrikraden, kolon : avslutar rubriken, och varje efterföljande indragen rad är en rad värden. Här är ett verkligt produktexempel:

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

Föreställ dig nu samma data som en array av JSON-objekt. Du skulle skriva "id", "name", "price", "inStock" och "category" fem gånger vardera — plus alla omgivande klamrar, hakparenteser och citationstecken. Den tabellmässiga TOON-representationen är ungefär 60% mindre i tokenantal för den här formen av data.

Ett användardataset följer samma 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

Nesting — objekt, arrayer och tabellformat tillsammans

TOON stöder nesting på de ställen du förväntar dig. Ett objekt kan innehålla ett arrayvärde. En tabellrad kan innehålla ett objekt. Det låter dig representera verklig data som inte passar perfekt in i platta rader.

Objekt som innehåller en array:

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

Tabelldata med ett inbäddat objekt i en kolumn (användbart för adressdata, metadata etc.):

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}

Håll nestingen grund när möjligt. Två eller tre nivåer djupt är där TOON fortfarande vinner på tokenantal. Djupt rekursiva strukturer betjänas bättre av JSON, som har rikare verktyg för schemavalidering — se MDN JSON-referensen om du behöver det.

Arbeta med npm-paketet

Installera med npm eller valfri kompatibel pakethanterare. TOON fungerar i Node.js och moderna webbläsare.

npm install @toon-format/toon

Paketet exporterar två funktioner: encode och decode. Det är hela det publika API:et — avsiktligt 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 } styr indragna radvärden. Du kan också använda encode på vanliga objekt och primitiva värden, inte bara arrayer — den väljer den mest kompakta TOON-representationen automatiskt. Klistra in utdata i TOON Formatter för att inspektera och snygg-skriva ut det.

Vanliga misstag

Det här är felen som biter utvecklare som är nya för TOON, vanligtvis inom den första timmen:

• Fel radantal i tabellnotation. Att skriva products[3] men sedan inkludera 4 datarader kommer att orsaka ett parsningsfel eller tyst ta bort den sista raden beroende på parsern version. Räkna dina rader och håll antalet aktuellt. TOON Validator fångar detta omedelbart.
• Citera objektnycklar. {"name":Alice} är ogiltig TOON — nycklar citeras aldrig. Ta bort citationstecknen: {name:Alice}.
• Glömma kolon efter rubriken. products[2]{id,name} följt av en nyrad kommer att misslyckas. Du behöver det avslutande kolonet: products[2]{id,name}:.
• Använda mellanslag runt kolon i nyckel:värde-par. {name : Alice} är inte giltigt. Inga mellanslag: {name:Alice}.
• Bädda in kommatecken i ociterade strängvärden. Om ett produktnamn är "Bolts, Nuts & More" måste du citera det i tabellrader: 101,"Bolts, Nuts & More",4.99,true.
• Förvänta JSON-utdata från decode på skalärer. decode("42") returnerar JavaScript-numret 42, inte ett JSON-objekt. TOON avkodar till inbyggda JS-typer.

Konvertera mellan TOON och JSON

TOON och JSON är fullt inbördes konverterbara — TOON är en supermängd av samma logiska datamodell som JSON serialiserar. Använd JSON till TOON för att krympa ett befintligt dataset innan du skickar det till ett LLM, och TOON till JSON för att konvertera tillbaka när du behöver mata resultatet in i ett JSON-only nedströmssystem. Funktionerna encode och decode hanterar detta programmatiskt om du automatiserar arbetsflödet i Node.js. Den underliggande datastrukturspecifikationen är nära relaterad till begrepp från JSON-globalen i JavaScript.

Sammanfattning

TOON-syntax är avsiktligt kompakt. Inga citerade nycklar, inga upprepade nyckelnamn i tabeller, inga obligatoriska citationstecken på enkla strängvärden. När du väl har skrivit ett tabellblock för hand ser du omedelbart varför — ett dataset som tar 40 rader JSON passar i 8 rader TOON. npm-paketet på npmjs.com/@toon-format/toon håller API-ytan liten: encode och decode, inget annat att lära sig. Använd TOON Formatter för snygg-utskrift, TOON Validator för att fånga syntaxfel, JSON till TOON för att konvertera din befintliga data, och TOON till JSON när du behöver resultatet tillbaka i standardform.