Was ist das TOON-Format? Eine Einführung für Entwickler

Die meisten Entwickler haben eine kurze gedankliche Liste von Datenformaten: JSON für APIs, CSV für Tabellenkalkulationen, YAML für Konfigurationsdateien, vielleicht XML für Legacy-Systeme. Aber es gibt ein neueres Format, das sich still und leise in den KI-Tooling-Bereich vorarbeitet und es wert ist, es zu kennen — TOON, oder Token-Oriented Object Notation. Es wurde von Grund auf für ein spezifisches Problem entwickelt: strukturierte Daten an große Sprachmodelle zu übergeben, ohne das Token-Budget zu erschöpfen.

Was ist TOON?

TOON steht für Token-Oriented Object Notation. Es ist ein kompaktes Datenserialisierungsformat, das speziell dafür entwickelt wurde, die Anzahl der verbrauchten Token zu minimieren, wenn strukturierte Daten in LLM-Prompts oder -Antworten eingebettet werden. Stellen Sie es sich als JSON vor, aus dem alle Ausführlichkeit entfernt wurde — keine wiederholten Schlüsselnamen in Arrays, keine redundanten Anführungszeichen, keine überflüssigen Leerzeichen — nur das Signal mit so wenig syntaktischem Rauschen wie möglich.

Das npm-Paket ist @toon-format/toon, und es bietet eine unkomplizierte encode / decode API, die in jedem Node.js-Projekt oder modernen Bundler funktioniert. TOON-Dateien verwenden die Erweiterung .toon.

Warum nicht einfach JSON verwenden?

JSON ist hervorragend für die Maschine-zu-Maschine-Kommunikation, bei der Bandbreite günstig ist und das Parsen vom Laufzeitsystem übernommen wird. Aber wenn Sie Daten als Teil eines Prompts an die OpenAI API oder die Anthropic API senden, zählt buchstäblich jedes Zeichen. Beide APIs rechnen nach Token ab, und Token entsprechen ungefähr 4 Zeichen englischem Text.

Betrachten Sie eine Tabelle mit 100 Benutzerdatensätzen. In JSON würden Sie die Schlüssel — "id", "name", "role", "email" — einmal pro Datensatz wiederholen. Das sind 100 Kopien derselben Strukturinformation. Die tabellarische Syntax von TOON definiert diese Schlüssel einmal und listet dann Zeile für Zeile Werte auf, genau wie CSV, aber mit erhaltener Objektstruktur. Die Token-Einsparungen bei realen Datensätzen können im Vergleich zu kompaktem JSON 40–70% betragen.

TOON-Syntax auf einen Blick

TOON unterstützt vier grundlegende Datenformen: Skalare (Strings, Zahlen, Booleans), Arrays, Objekte und tabellarische Daten. Die Skalar- und Kollektionssyntax wird Ihnen vertraut vorkommen, wenn Sie mit JSON gearbeitet haben — das tabellarische Format ist der Bereich, in dem sich TOON wirklich unterscheidet.

Ein einfaches Objekt verzichtet auf den Leerraum der äußeren Klammern, lässt unnötige Anführungszeichen weg und trennt Schlüssel-Wert-Paare mit Kommas:

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

Ein einfaches Array von Skalaren sieht genau so aus, wie man es erwarten würde:

[1,2,3]

Hier wird es interessant — tabellarische Daten. Diese Syntax macht TOON für LLM-Anwendungsfälle attraktiv. Anstatt Schlüssel für jedes Objekt in einem Array zu wiederholen, deklarieren Sie das Schema einmal im Header und listen dann Werte Zeile für Zeile auf:

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

Dieser Block repräsentiert ein Array von 3 Benutzerobjekten — äquivalent zum JSON unten — aber in einem Bruchteil der Token. Der Header users[3]{id,name,role} sagt dem Parser: "Das ist eine Variable namens users, sie hat 3 Zeilen, und jede Zeile entspricht den Feldern id, name und role". Die Zeilen sind reine Werte ohne Schlüsselwiederholung.

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

Das @toon-format/toon-Paket installieren und verwenden

Das offizielle npm-Paket verwaltet sowohl die Kodierung von JavaScript-Werten in TOON-Strings als auch die Dekodierung von TOON-Strings zurück in JavaScript-Objekte und Arrays. Installieren Sie es aus der npm-Registry:

npm install @toon-format/toon

Das Paket exportiert zwei Funktionen — encode und 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}

Die Option indent in encode() steuert, ob die Ausgabe hübsch formatiert wird. Bei LLM-Prompts werden Sie normalerweise kompakte Ausgabe (ohne Einrückung) verwenden wollen, um Token zu sparen. Für das Debugging oder menschenlesbare .toon-Dateien liefert { indent: 2 } gut formatierte Ausgabe.

Ein reales Anwendungsbeispiel: Datensätze an einen LLM senden

Stellen Sie sich vor, Sie entwickeln ein Produkt-Analytics-Feature, das Benutzeraktivitäten zusammenfassen soll. Sie rufen aktuelle Sitzungsdatensätze aus Ihrer Datenbank ab und möchten sie zur natürlichsprachlichen Zusammenfassung an einen LLM senden. So sieht das mit TOON aus:

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}`;

Die TOON-Darstellung dieser 5 Sitzungsdatensätze ist deutlich kürzer als das äquivalente JSON, das "userId", "action", "duration" und "page" je fünfmal wiederholen würde. Bei Hunderten von Datensätzen sind die Einsparungen erheblich und führen direkt zu niedrigeren API-Kosten und schnelleren Antwortzeiten (weniger Token im Aufmerksamkeitsfenster zu verarbeiten).

Wichtige Datentypen in TOON

TOON bildet sauber auf die Primitive ab, die Sie bereits in JavaScript und den meisten anderen Sprachen verwenden:

• Strings — Ohne Anführungszeichen, wenn sie keine Sonderzeichen enthalten. Mit doppelten Anführungszeichen, wenn sie Kommas, Doppelpunkte oder Leerzeichen enthalten.
• Zahlen — Ganzzahlen und Fließkommazahlen so geschrieben wie sie sind: 42, 3.14, -7.
• Booleans — true und false, genau wie JSON.
• Null — Als null für fehlende oder undefinierte Werte.
• Arrays — Inline-Klammersyntax [val1,val2,val3] für kurze Listen; tabellarische Header-Syntax für Arrays von Objekten.
• Objekte — Geschweifter-Klammer-Syntax {key:value,key2:value2} für einzelne Objekte.
• Tabellarische Daten — Der Star: Header name[n]{col1,col2,...}: gefolgt von kommaseparierten Zeilen — ideal für jede Sammlung von Datensätzen gleicher Form.

Wann TOON vs andere Formate verwenden

TOON versucht nicht, JSON als allgemeines Austauschformat zu ersetzen. Es füllt eine spezifische Nische. Hier ist ein schneller Entscheidungsleitfaden:

• JSON verwenden, wenn Sie REST-APIs entwickeln, Dokumente in einer Datenbank speichern oder Daten zwischen Diensten übergeben. JSON wird universell unterstützt, ist gut mit Tools ausgestattet und menschenlesbar.
• TOON verwenden, wenn strukturierte Daten Teil eines Prompts oder LLM-Kontextfensters sind und die Token-Anzahl wichtig ist. Das tabellarische Format glänzt, wenn Sie mit Zeilen von Datensätzen arbeiten — Benutzerlisten, Log-Einträge, Produktkataloge, Analytics-Events.
• CSV verwenden, wenn Sie nur flache tabellarische Daten benötigen und der Verbraucher CSV erwartet (Tabellenkalkulationen, BI-Tools). CSV hat keine Objektverschachtelung, daher ist TOON ausdrucksstärker.
• YAML verwenden für von Menschen bearbeitete Konfigurationsdateien, bei denen Lesbarkeit und Kommentare wichtiger sind als Kompaktheit.
• TOON auch für LLM-Tool-Ausgaben verwenden: Wenn ein LLM Ihr Tool aufruft und strukturierte Ergebnisse zurückgibt, spart die Kodierung dieser Ergebnisse in TOON Token auf beiden Seiten des API-Aufrufs.

Zusammenfassung

TOON — Token-Oriented Object Notation — ist ein kompaktes Serialisierungsformat, das für das LLM-Zeitalter entwickelt wurde. Es behält die vertraute Struktur von JSON (Objekte, Arrays, Skalare) bei und führt dabei eine tabellarische Syntax ein, die redundante Schlüsselwiederholungen über Datensätze hinweg eliminiert. Das Ergebnis ist ein Format, das 40–70% kleiner als äquivalentes JSON sein kann, was sich direkt in niedrigeren Token-Kosten niederschlägt, wenn Sie mit der OpenAI API, Anthropic API oder einem anderen Token-abrechnenden LLM-Dienst arbeiten.

Wenn Sie TOON praktisch erkunden möchten, haben wir hier eine vollständige Suite von Tools: Verwenden Sie den TOON Formatter zum hübschen Formatieren und Untersuchen von TOON-Dokumenten, den TOON Validator zum Erkennen von Syntaxfehlern, den JSON-zu-TOON-Konverter zum Migrieren bestehender Payloads und den TOON-zu-JSON-Konverter, wenn Sie in die andere Richtung müssen. Das npm-Paket @toon-format/toon bietet encode und decode, um TOON direkt in Ihren Node.js- oder Browser-seitigen Code in Minuten zu integrieren.