JSON Toolkit

Průvodce formátem TOON: odlehčete JSON před tím, než ho dáte LLM

Shrnutí: Když předáváte jazykovému modelu uniformní pole ve formátu JSON, opakující se názvy klíčů a závorky polykají tokeny. TOON deklaruje strukturu jednou pomocí odsazených objektů a tabulkových polí a data vypisuje řádek po řádku. Oficiální benchmarky ukazují přibližně o 40 % méně tokenů s vyšší přesností parsování. Tento průvodce pokrývá syntaxi, kdy úspora funguje, kdy se konverze nevyplatí a jak propojit encode a decode.

Střední~6 min čteníPublikováno 2026-11-10Aktualizováno 2026-11-10
Syntaxe tabulkového pole TOON: hlavička polí deklarovaná jednou, řádky dat vypisovány postupně

Syntaktická režie JSONu nezáleží při přenosu mezi stroji, ale na vstupu LLM účtovaného po tokenech jsou to skutečné peníze: totéž uniformní pole opakuje názvy klíčů desítkrát a každá složená závorka s každou uvozovkou ukousne kus rozpočtu. TOON nevymýšlí nový datový model — přepisuje datový model JSON levnější notací.

Co je TOON: další kódování JSONu, ne konkurent

TOON (Token-Oriented Object Notation) je otevřený formát, který se objevil v roce 2025, a jeho oficiální pozice se vejde do jedné věty: kompaktní, bezztrátové a čitelné kódování datového modelu JSON. Nezavádí nové typy — objekty, pole, řetězce, čísla, booleany a null odpovídají JSONu jeden na jednoho a decode(encode(x)) je striktně rovné původním datům (typy mimo JSON jako Date nebo NaN je třeba předem normalizovat). Round-trip je bezztrátový a deterministický: stejný vstup vždy dává stejný výstup, což je důležité pro reprodukovatelné prompty.

Protože TOON kóduje přesně datový model JSON, správný způsob použití je jako hraniční formát: aplikace dál pracuje interně v JSONu, těsně před vložením dat do promptu konvertuje do TOON a z odpovědi modelu konvertuje zpět. Oficiální dokumentace tomu říká „translation layer“. Běžná přípona souborů je .toon; pro HTTP transport je předběžný media type text/toon, v UTF-8.

Jedno varování ohledně vyhledávacího šumu: nepleťte si to s Toon Shaderem ve 3D grafice. Společný je jen slovo.

Proč je JSON na vstupu LLM obzvlášť drahý

Vezměte seznam objednávek, přehled uživatelů nebo shrnutí logů zapsané jako JSON pole. Tokeny jdou na tři místa:

  1. Opakující se názvy klíčů. Padesát záznamů objednávek píše "id", "amount" a "status" padesátkrát každý. Zdvojnásobte data — zdvojnásobíte režii.
  2. Strukturální interpunkce. Složené a hranaté závorky, dvojtečky a čárky — všechno jsou to tokeny a zanořování je balí ještě hustěji.
  3. Uvozovky. Téměř každý klíč a každá řetězcová hodnota jsou obalené dvojitými uvozovkami.

Dohromady: náklady na API účtované po tokenech rostou přímo; dlouhé vstupy dřív narazí na strop kontextového okna; a na velmi dlouhých vstupech model častěji vynechává nebo posouvá pole. Benchmark oficiální stránky: na testovací sadě se smíšenými strukturami a čtyřmi modelemi přibližně o 40 % méně tokenů s přesností parsování, která stoupá ze 70 % (JSON) na 74 % (TOON). Úspora a přesnost tady nejsou kompromis, protože kompaktnější struktura dělá hranice pro model viditelnějšími.

Syntaxe: odsazené objekty + tabulková pole

Tatáž data předpovědi počasí ve třech tvarech. Verze JSON, přibližně 117 tokenů:

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

Verze TOON, přibližně 66 tokenů:

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

Tři tvary pokrývají vše a serializátor je vybírá automaticky podle tvaru dat:

Tvar Hodí se pro Ekvivalent v JSON
Odsazený objekt Zanořené objekty { "location": { ... } }, odsazení nahrazuje složené závorky
Řádkové pole Pole primitivů ["frost","wind"], [2] deklaruje délku
Tabulkové pole Pole uniformních objektů Názvy polí se objeví jen jednou v hlavičce {day,temp{min,max},...}; každý řádek obsahuje jen hodnoty oddělené čárkami

Uniformní zanořené objekty (temp{min,max}) se složí do hlavičky jako skupina zanořených polí a řádky dat zůstanou ploché. Pravidlo uvozovek je minimální: řetězce berou uvozovky jen pokud obsahují oddělovače, speciální znaky nebo by hrozilo, že budou čteny jako čísla — jeden z důvodů, proč TOON poráží „kompaktní JSON“ v počtu tokenů. Klíčový rozdíl proti YAML: TOON má explicitní deklarace délky a strojově ověřitelné hlavičky polí; proti CSV: zachovává zanoření a typy.

[N] a {fields}: strukturální zábradlí pro model

[3] a {day,...} neslouží jen k úspoře tokenů — jsou to i ověřitelná smlouva, kterou modelu předáváte:

  • Délka pole umožňuje modelu přímo odpovědět na „kolik záznamů dataset obsahuje“ a okamžitě prozradí zkrácení, když počet řádků nesedí.
  • Hlavička polí deklaruje názvy jednou; model zarovnává hodnoty podle pozice místo toho, aby v každém řádku znovu hádal shodu klíčů.

To je prevence, opak dodatečné opravy. Opravář JSONu (viz příručka oprav) zachraňuje data poté, co model vyplivl rozbitý JSON; deklarace délky a polí v TOON snižují na vstupu pravděpodobnost rozbitých dat. Dělejte obojí a míra selhání parsování v polovině pipeline klesá.

Když TOON nepoužívat

Oficiální sekce „When Not to Use TOON“ je osvěžně přímočará. Čtyři scénáře, nechte je tak, jak jsou:

Scénář Proč se vyhnout Nejlepší volba
Hluboko zanořené, neuniformní struktury Tabulková způsobilost ≈ 0 %; kompaktní JSON často vyhrává Kompaktní JSON
Polouniformní pole Nepravidelná pole, úspora se vytratí Nechte JSON pipeline
Ryze tabulková data TOON stojí o 5–10 % režie navíc proti CSV CSV
Citlivé na latenci (lokální/kvantované modely) Méně tokenů ≠ rychlejší inference Nejdřív změřte TTFT

Polouniformnost se posuzuje podle tabulkové způsobilosti (tabular eligibility): oficiálně, při způsobilosti 40–60 % je úspora už okrajová. Migrace formátu má skutečné náklady — parsery, validátory i skripty po proudu se mění všechny — takže pokud zisk je pod deseti procenty, nic neškrtávejte.

Nasazení: encode / decode a CLI

Oficiální TypeScript knihovna, oběma směry:

npm install @toon-format/toon
# Dávková konverze jde také přes CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // striktně rovné původním datům

Existují implementace pro Python, Go, Rust a .NET; před tím, než některou vezmete, porovnejte seznam implementací v oficiálním repozitáři specifikace a ujistěte se, že pokrývá syntaktické vlastnosti, které používáte. Před produkčním nasazením proveďte kontrolu round-trip: decode(encode(původní)) musí být hluboko rovné originálu; pokud ne, problém je v implementaci nebo v datech.

Jak se to vejde do vaší stávající JSON pipeline

TOON ve vaší JSON pipeline nic nemění; přidává konverzi na hranici. Doporučené pořadí:

  1. Nejdřív se ujistěte, že JSON je čistý. Rozbitý JSON dá rozbitý TOON. Syntaktickou validaci a opravy popisuje Průvodce opravou JSON.
  2. Zkontrolujte tvar dat. Všechny objekty pole mají stejná pole? Nejdřív normalizujte — nebo přiznejte, že konverze nestojí za námahu.
  3. Konvertujte a kontrolujte vzorky. Po konverzi porovnejte pár řádků s původním JSON, abyste se přesvědčili, že zarovnání polí neposloužilo.
  4. Oceňte přínos. U uniformních seznamů platí řádková logika příručky JSONL i pro proudovou konverzi; ohledně poměru velikosti a nákladů skutečný poměr JSON minify a gzip dává tutéž lekci: nejdřív měřit, pak konvertovat.

Nahradí TOON JSON?

Ne. TOON kóduje datový model JSON; jeho místo je hranice promptu, zatímco ukládání a výměna mezi programy zůstávají územím JSON. Použijte TOON pro segment „dát modelu“ a zbytek řetězu nechte nedotčený.

Jaký vztah má TOON k YAML a CSV?

Objekty vypadají jako YAML (odsazení místo složených závorek); uniformní pole vypadají jako CSV (hlavička deklarována jednou, řádky v proudu). Ale TOON má explicitní deklarace délky, které YAML nemá, a zachovává zanoření a typy, které CSV nemá — stojí mezi nimi, se strojově ověřitelnými zábradlími.

Ztrácí konverze TOON na JSON data?

Ne: objekty, pole, řetězce, čísla, booleany a null odpovídají jeden na jednoho a decode(encode(x)) je striktně rovné originálu. Jediná obezřetnost — předem normalizujte typy mimo JSON jako Date a NaN; jinak rovnost platí jen po round-trip.

Jak ověřím, že konvertovaný TOON je správný?

Dvě kontroly: kontrola round-trip (encode, pak decode, hluboká rovnost s originálem) a vizuální kontrola hlavičky — číslo [N] se musí rovnat počtu řádků a pole {fields} se musí zarovnat jeden na jednoho s hodnotami oddělenými čárkami v každém řádku. Na straně modelu můžete ještě před odpovědí požádat o hlášení délky pole.