What is TOON Format? A Developer's Introduction

De fleste utviklere har en kort mental liste over dataformater: JSON til API-er, CSV til regneark, YAML til konfigurasjonsfiler, kanskje XML hvis du jobber med legacy-systemer. Men det finnes et nyere format som stille og rolig baner seg vei inn i AI-verktøyrommet og er verdt å kjenne til — TOON, eller Token-Oriented Object Notation. Det ble designet fra bunnen til et spesifikt problem: å sende strukturerte data til store språkmodeller uten å brenne av tokenbudsjettet ditt.

Hva er TOON?

TOON står for Token-Oriented Object Notation. Det er et kompakt dataserialiseringsformat bygget for å minimere antallet tokens som brukes når strukturerte data er innebygd i LLM-prompter eller svar. Tenk på det som JSON med all redundans fjernet — ingen gjentatte nøkkelnavn i arrays, ingen unødvendige anførselstegn, ingen etterfølgende whitespace — bare signalet med så lite syntaktisk støy som mulig.

npm-pakken er @toon-format/toon, og den gir deg et enkelt encode / decode API som fungerer i ethvert Node.js-prosjekt eller moderne bundler. TOON-filer bruker filendelsen .toon.

Hvorfor ikke bare bruke JSON?

JSON er utmerket for maskin-til-maskin-kommunikasjon, der båndbredde er billig og parsing håndteres av runtime-en. Men når du sender data som en del av en prompt til OpenAI API eller Anthropic API, teller hvert tegn — bokstavelig talt. Begge API-ene fakturerer per token, og tokens tilsvarer omtrent 4 tegn engelsk tekst.

Tenk på en tabell med 100 brukerposter. I JSON ville du gjenta nøklene — "id", "name", "role", "email" — én gang per post. Det er 100 kopier av den samme strukturelle informasjonen. TOONs tabellformat definerer disse nøklene én gang og viser deretter verdier rad for rad, på samme måte som CSV gjør, men med objektstrukturen bevart. Tokenbesparelsene på virkelige datasett kan være 40–70% sammenlignet med kompakt JSON.

TOON-syntaks i korte trekk

TOON støtter fire kjerne-dataformer: skalarer (strenger, tall, boolske verdier), arrays, objekter og tabelldata. Skalar- og samlingssyntaksen vil se kjent ut hvis du har jobbet med JSON — tabellformatet er der TOON virkelig skiller seg ut.

Et enkelt objekt fjerner den ytre klammens whitespace, utelater unødvendige anførselstegn og skiller nøkkel–verdi-par med kommaer:

{name:Alice,age:30,role:admin}

Et enkelt array av skalarer ser akkurat ut som man ville forvente:

[1,2,3]

Nå er det her det blir interessant — tabelldata. Det er syntaksen som gjør TOON overbevisende til LLM-brukstilfeller. I stedet for å gjenta nøkler for hvert objekt i et array, erklærer du skjemaet én gang i overskriften og viser verdier rad for rad:

users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Den blokken representerer et array av 3 brukerobjekter — tilsvarende JSON nedenfor — men på en brøkdel av tokens. Overskriften users[3]{id,name,role} forteller en parser: "dette er en variabel med navnet users, den har 3 rader, og hver rad kartlegges til feltene id, name og role". Radene er rene verdier, ingen nøkkelgjentakelse.

[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

Installasjon og bruk av @toon-format/toon-pakken

Den offisielle npm-pakken håndterer både koding av JavaScript-verdier til TOON-strenger og dekoding av TOON- strenger tilbake til JavaScript-objekter og arrays. Installer den fra npm-registeret:

npm install @toon-format/toon

Pakken eksporterer to funksjoner — encode og decode:

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

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

indent-alternativet i encode() styrer om utdataene er pent formatert. Til LLM-prompter vil du normalt ønske kompakt utdata (ingen innrykk) for å spare tokens. Til feilsøking eller menneskelesbare .toon-filer gir { indent: 2 } deg pent formatert utdata.

Et virkelighetsnært brukstilfelle: Sende poster til en LLM

Forestill deg at du bygger en produktanalysefunksjon som skal oppsummere brukeraktivitet. Du henter nylige sesjoner fra databasen og vil sende dem til en LLM for naturlig-språklig oppsummering. Slik ser det ut med TOON:

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

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

TOON-representasjonen av disse 5 sesjonspostene er betydelig kortere enn tilsvarende JSON, som ville gjenta "userId", "action", "duration" og "page" fem ganger hver. Over hundrevis av poster er besparelsene vesentlige og oversettes direkte til lavere API-kostnader og raskere responstider (færre tokens å behandle i oppmerksomhetsvinduer).

Viktige datatyper i TOON

TOON kartlegges rent til primitivene du allerede bruker i JavaScript og de fleste andre språk:

• Strenger — Uten anførselstegn når de ikke inneholder spesialtegn. Sitert med doble anførselstegn når de inneholder kommaer, kolon eller whitespace.
• Tall — Heltall og desimaltall skrevet som de er: 42, 3.14, -7.
• Boolske verdier — true og false, samme som JSON.
• Null — Skrevet som null for fraværende eller udefinerte verdier.
• Arrays — Inline-parentes-syntaks [val1,val2,val3] for korte lister; tabellhodesyntaks for arrays av objekter.
• Objekter — Klammesyntaks {key:value,key2:value2} for enkle objekter.
• Tabelldata — Stjernen i showet: name[n]{col1,col2,...}:-overskrift etterfulgt av kommaseparerte rader — ideell for enhver samling av poster med samme form.

Når skal man velge TOON versus andre formater

TOON forsøker ikke å erstatte JSON som et generelt utvekslingsformat. Det fyller en spesifikk nisje. Her er en rask beslutningsveiledning:

• Bruk JSON når du bygger REST API-er, lagrer dokumenter i en database eller sender data mellom tjenester. JSON er universelt støttet, har gode verktøy og er lesbar for mennesker.
• Bruk TOON når strukturerte data er en del av en prompt eller et LLM-kontekstvindu, og tokenantall er viktig. Tabellformatet skinner når du jobber med rader av poster — brukerlister, loggoppføringer, produktkataloger, analysebegivenheter.
• Bruk CSV når du bare trenger flate tabelldata, og forbrukeren forventer CSV (regneark, BI-verktøy). CSV har ingen objektinnbygging, så TOON er mer uttrykksfull.
• Bruk YAML til menneskeredigerte konfigurasjonsfiler der lesbarhet og kommentarer er viktigere enn kompakthet.
• Bruk TOON til LLM-verktøyutdata også: hvis en LLM kaller verktøyet ditt og returnerer strukturerte resultater, sparer koding av disse resultatene i TOON tokens på både inndata- og utdatasiden av API-kallet.

Oppsummering

TOON — Token-Oriented Object Notation — er et kompakt serialiseringsformat bygget for LLM-æraen. Det bevarer den kjente strukturen fra JSON (objekter, arrays, skalarer), mens det introduserer en tabellsyntaks som eliminerer redundant nøkkelgjentakelse på tvers av poster. Resultatet er et format som kan være 40–70% mindre enn tilsvarende JSON, noe som direkte oversettes til lavere tokenkostnader når man jobber med OpenAI API, Anthropic API, eller en annen token-fakturert LLM-tjeneste.

Hvis du vil utforske TOON praktisk, har vi en komplett suite av verktøy her: bruk TOON Formatter til å pent skrive ut og inspisere TOON-dokumenter, TOON Validator til å fange syntaksfeil, JSON til TOON-konvertereren til å migrere eksisterende payloads, og TOON til JSON-konvertereren hvis du trenger å gå den andre veien. npm-pakken @toon-format/toon gir deg encode og decode for å integrere TOON direkte i din Node.js- eller nettlesersidekode på få minutter.