TOON-Syntaxleitfaden — Von Skalaren bis zu tabellarischen Daten

Die meisten Datenformate wurden für ein Publikum entwickelt: Menschen oder Maschinen. JSON neigt zum Menschen. Binärformate wie MessagePack neigen zur Maschine. TOON ist explizit für ein drittes Publikum konzipiert, das als diese Formate erfunden wurden noch nicht existierte: große Sprachmodelle. Jede Syntax-Entscheidung in TOON priorisiert Token-Effizienz — maximale strukturierte Daten in minimale Tokens zu packen, damit man dem KI mehr Kontext geben kann, ohne sein Budget zu sprengen. Dieser Leitfaden deckt jede TOON-Syntaxfunktion ab, von einfachen Skalaren bis zur tabellarischen Notation, die ihn wirklich anders macht.

Was TOON anders macht

TOON steht für Token-Optimised Object Notation. Die Kernidee ist einfach: Datenserialisierungsformate wie JSON wurden lange vor token-basierter API-Preisgestaltung entwickelt. JSON ist in Ordnung für Maschine-zu-Maschine-Kommunikation, aber wenn der Payload ein 200-Zeilen-Datensatz ist, der in einen gpt-4o-Prompt geht, zahlt man für jedes Anführungszeichen, jede geschweifte Klammer und jeden wiederholten Schlüsselnamen. TOON eliminiert diesen Overhead. Es wird als einzelnes npm-Paket installiert — @toon-format/toon — und Dateien verwenden die Erweiterung .toon.

Skalare Werte — Strings, Zahlen, Booleans

TOON-Skalare sehen JSON-Gegenstücken sehr ähnlich, mit einem wichtigen Unterschied: String-Werte erfordern keine Anführungszeichen, es sei denn, sie enthalten Sonderzeichen wie Kommas, Doppelpunkte oder Klammern. Dies allein schneidet einen bedeutenden Anteil von Tokens aus textlastigen Datensätzen.

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

Wenn ein String ein Komma, einen Doppelpunkt oder eine Klammer enthält, in doppelte Anführungszeichen setzen, genau wie bei JSON. Also braucht "New York, NY" Anführungszeichen, aber London nicht. Einfache Regel, große Einsparungen.

Objekte — Schlüssel:Wert-Paare ohne Rauschen

TOON-Objekte verwenden geschweifte Klammern mit einer Schlüssel:Wert-Syntax. Schlüssel werden niemals in Anführungszeichen gesetzt — das spart allein zwei Zeichen pro Schlüssel im Vergleich zu JSON. Paare werden durch Kommas getrennt. Keine abschließenden Kommas, kein Doppelpunkt nach dem letzten Paar.

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

Vergleiche das mit dem entsprechenden JSON:

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

Gleiche Daten, weniger Zeichen, und die Token-Einsparungen summieren sich dramatisch, wenn man mit Arrays von Objekten arbeitet. Apropos...

Arrays — Geordnete Listen von Werten

Arrays in TOON verwenden eckige Klammern mit durch Kommas getrennten Werten — genau wie JSON, nur ohne Anführungszeichen bei einfachen String-Werten.

// 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 von Objekten funktionieren, aber hier kommt TOONs Killer-Feature ins Spiel. Wenn man mehr als zwei oder drei Zeilen strukturierter Daten hat, ist die tabellarische Notation dramatisch effizienter.

Tabellarische Notation — Das Feature, das alles ändert

Tabellarische Notation ist TOONs Hauptfeature. Es ist für das Szenario konzipiert, das in der realen Arbeit ständig vorkommt: eine Liste ähnlicher Objekte — Produkte, Benutzer, Transaktionen, Log-Einträge — bei denen das Wiederholen der Schlüssel in jeder Zeile reiner Overhead ist. Die Syntax lautet:

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

Aufgeschlüsselt: name ist das Label des Datensatzes, [count] ist die Anzahl der Datenzeilen (erforderlich — er teilt dem Parser genau mit, wie viele Zeilen gelesen werden sollen), {col1,col2,...} ist die Headerzeile, der Doppelpunkt : beendet den Header, und jede nachfolgende eingerückte Zeile ist eine Zeile mit Werten. Hier ist ein echtes Produktbeispiel:

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

Stell dir nun dieselben Daten als Array von JSON-Objekten vor. Man würde "id", "name", "price", "inStock" und "category" jeweils fünf Mal schreiben — plus all die umgebenden Klammern und Anführungszeichen. Die tabellarische TOON-Darstellung ist in der Token-Anzahl für diese Datenform ungefähr 60% kleiner.

Ein Benutzerdatensatz folgt demselben Muster:

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

Verschachtelung — Objekte, Arrays und Tabellen zusammen

TOON unterstützt Verschachtelung an den erwarteten Stellen. Ein Objekt kann einen Array-Wert enthalten. Eine tabellarische Zeile kann ein Objekt enthalten. Dies ermöglicht die Darstellung realer Daten, die nicht perfekt in flache Zeilen passen.

Objekt, das ein Array enthält:

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

Tabellarische Daten mit einem eingebetteten Objekt in einer Spalte (nützlich für Adressdaten, Metadaten usw.):

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}

Verschachtelung wenn möglich flach halten. Zwei oder drei Ebenen tief ist, wo TOON noch bei der Token-Anzahl gewinnt. Tief rekursive Strukturen werden besser durch JSON bedient, das reichere Werkzeuge für die Schema-Validierung hat — sieh dir die MDN JSON-Referenz an, wenn du das brauchst.

Mit dem npm-Paket arbeiten

Mit npm oder einem kompatiblen Paketmanager installieren. TOON funktioniert in Node.js und modernen Browsern.

npm install @toon-format/toon

Das Paket exportiert zwei Funktionen: encode und decode. Das ist die gesamte öffentliche API — absichtlich 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

Die Option { indent: 2 } steuert die Einrückung von Zeilenwerten. Man kann encode auch auf einfache Objekte und primitive Werte anwenden, nicht nur auf Arrays — es wählt automatisch die kompakteste TOON-Darstellung. Füge die Ausgabe in den TOON Formatter ein, um sie zu inspizieren und schön zu drucken.

Häufige Fehler

Das sind die Fehler, die Entwickler zu Beginn mit TOON treffen, normalerweise innerhalb der ersten Stunde:

• Falsche Zeilenanzahl in der tabellarischen Notation. products[3] schreiben, aber dann 4 Datenzeilen einfügen, verursacht einen Parse-Fehler oder lässt die letzte Zeile abhängig von der Parser-Version stillschweigend fallen. Zeilen zählen und die Zahl aktuell halten. Der TOON Validator erkennt dies sofort.
• Objekt-Schlüssel in Anführungszeichen setzen. {"name":Alice} ist ungültiges TOON — Schlüssel werden niemals in Anführungszeichen gesetzt. Die Anführungszeichen weglassen: {name:Alice}.
• Den Doppelpunkt nach dem Header vergessen. products[2]{id,name} gefolgt von einem Zeilenumbruch schlägt fehl. Der abschließende Doppelpunkt ist erforderlich: products[2]{id,name}:.
• Leerzeichen um den Doppelpunkt in Schlüssel:Wert-Paaren verwenden. {name : Alice} ist ungültig. Keine Leerzeichen: {name:Alice}.
• Kommas in unquoted String-Werten einbetten. Wenn ein Produktname "Bolts, Nuts & More" ist, muss er in tabellarischen Zeilen in Anführungszeichen gesetzt werden: 101,"Bolts, Nuts & More",4.99,true.
• JSON-Ausgabe von decode bei Skalaren erwarten. decode("42") gibt die JavaScript-Zahl 42 zurück, kein JSON-Objekt. TOON dekodiert zu nativen JS-Typen.

Zwischen TOON und JSON konvertieren

TOON und JSON sind vollständig ineinander konvertierbar — TOON ist eine Obermenge desselben logischen Datenmodells, das JSON serialisiert. Verwende JSON zu TOON, um einen bestehenden Datensatz zu verkleinern, bevor er an ein LLM gesendet wird, und TOON zu JSON, um zurück zu konvertieren, wenn das Ergebnis in ein JSON-only-Downstream-System eingespeist werden soll. Die Funktionen encode und decode erledigen dies programmatisch, wenn man den Workflow in Node.js automatisiert. Die zugrundeliegende Datenstrukturspezifikation ist eng mit Konzepten aus dem JSON-Global in JavaScript verwandt.

Zusammenfassung

TOON-Syntax ist absichtlich kompakt. Keine Schlüssel in Anführungszeichen, keine wiederholten Schlüsselnamen in Tabellen, keine obligatorischen Anführungszeichen bei einfachen String-Werten. Sobald man einmal manuell einen tabellarischen Block geschrieben hat, sieht man sofort warum — ein Datensatz, der 40 Zeilen JSON benötigt, passt in 8 Zeilen TOON. Das npm-Paket bei npmjs.com/@toon-format/toon hält die API-Oberfläche winzig: encode und decode, nichts anderes zu lernen. Verwende den TOON Formatter zum Formatieren, TOON Validator zum Erkennen von Syntaxfehlern, JSON zu TOON zum Konvertieren bestehender Daten, und TOON zu JSON, wenn das Ergebnis zurück in Standardform benötigt wird.