JSON Toolkit

Przewodnik po formacie TOON: odchudź JSON przed podaniem go do LLM

Podsumowanie: Gdy przekazujesz jednolitą tablicę do modelu językowego w formacie JSON, powtarzające się nazwy kluczy i nawiasy pożerają tokeny. TOON deklaruje strukturę tylko raz dzięki wciętym obiektom i tabelarycznym tablicom, a dane wylewa wiersz po wierszu. Oficjalne benchmarki pokazują około 40% mniej tokenów przy wyższej dokładności parsowania. Ten przewodnik obejmuje składnię, kiedy oszczędność działa, kiedy konwersja się nie opłaca i jak połączyć encode z decode.

Średniozaawansowany~6 min czytaniaOpublikowano 2026-11-10Zaktualizowano 2026-11-10
Składnia tabelarycznej tablicy TOON: nagłówek pól zadeklarowany raz, wiersze danych wylewane po kolei

Narzut składniowy JSON nie ma znaczenia przy transferze między maszynami, ale na wejściu LLM rozliczanego za tokeny to realne pieniądze: ta sama jednolita tablica powtarza nazwy kluczy dziesiątki razy, a każda klamra z każdym cudzysłowem ugryzie kawałek budżetu. TOON nie wymyśla nowego modelu danych — przepisuje model danych JSON tańszą notacją.

Czym jest TOON: jeszcze jedno kodowanie JSON, nie konkurent

TOON (Token-Oriented Object Notation) to otwarty format, który pojawił się w 2025 roku, a jego oficjalne pozycjonowanie mieści się w jednym zdaniu: kompaktowe, bezstratne i czytelne kodowanie modelu danych JSON. Nie wprowadza nowych typów — obiekty, tablice, stringi, liczby, booleany i null odpowiadają JSON-owi jeden do jednego, a decode(encode(x)) jest ściśle równe danym oryginalnym (typy spoza JSON jak Date czy NaN trzeba najpierw znormalizować). Round-trip jest bezstratny i deterministyczny: to samo wejście zawsze daje to samo wyjście, co jest ważne dla powtarzalnych promptów.

Ponieważ TOON koduje dokładnie model danych JSON, właściwym sposobem użycia jest format graniczny: aplikacja dalej pracuje w JSON wewnątrz, konwertuje do TOON tuż przed włożeniem danych do promptu i konwertuje z powrotem z odpowiedzi modelu. Oficjalna dokumentacja nazywa to „translation layer“. Zwyczajowe rozszerzenie plików to .toon; dla transportu HTTP tymczasowy media type to text/toon, w UTF-8.

Jedno ostrzeżenie dotyczące szumu wyszukiwania: nie myl z Toon Shaderem w grafice 3D. Wspólne jest tylko słowo.

Dlaczego JSON jest szczególnie drogi na wejściu LLM

Weź listę zamówień, wykaz użytkowników albo podsumowanie logów zapisane jako tablica JSON. Tokeny idą w trzy miejsca:

  1. Powtarzające się nazwy kluczy. Pięćdziesiąt rekordów zamówień pisze "id", "amount" i "status" po pięćdziesiąt razy każdy. Podwój dane — podwoisz narzut.
  2. Interpunkcja strukturalna. Klamry i nawiasy kwadratowe, dwukropki i przecinki — wszystko to tokeny, a zagnieżdżanie pakuje je jeszcze gęściej.
  3. Cudzysłowy. Prawie każdy klucz i każda wartość tekstowa są owinięte podwójnymi cudzysłowami.

Razem: koszt API rozliczanego za tokeny rośnie wprost; długie wejścia wcześniej uderzają w sufit okna kontekstu; a przy bardzo długich wejściach model częściej pomija lub przesuwa pola. Benchmark oficjalnej strony: na zestawie testowym o mieszanych strukturach i czterech modelach około 40% mniej tokenów przy dokładności parsowania rosnącej z 70% (JSON) do 74% (TOON). Oszczędność i dokładność to tu nie trade-off, bo bardziej kompaktowa struktura robi granice bardziej widocznymi dla modelu.

Składnia: wcięte obiekty + tabelaryczne tablice

Te same dane prognozy pogody w trzech formach. Wersja JSON, około 117 tokenów:

{
  "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 }
  ]
}

Wersja TOON, około 66 tokenów:

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

Trzy formy pokrywają wszystko, a serializator wybiera je automatycznie według kształtu danych:

Forma Nadaje się do Odpowiednik JSON
Wcięty obiekt Zagnieżdżone obiekty { "location": { ... } }, wcięcie zastępuje klamry
Tablica inline Tablice prymitywów ["frost","wind"], [2] deklaruje długość
Tablica tabelaryczna Tablice jednolitych obiektów Nazwy pól pojawiają się tylko raz w nagłówku {day,temp{min,max},...}; każdy wiersz zawiera tylko wartości rozdzielone przecinkami

Jednolite zagnieżdżone obiekty (temp{min,max}) składają się w nagłówek jako grupa zagnieżdżonych pól, a wiersze danych pozostają płaskie. Zasada cudzysłowów jest minimalna: stringi biorą cudzysłowy tylko jeśli zawierają separatory, znaki specjalne albo grozą odczytania jako liczby — jedna z przyczyn, dla których TOON wygrywa z „kompaktowym JSON“ w liczeniu tokenów. Kluczowa różnica wobec YAML: TOON ma jawne deklaracje długości i nagłówki pól weryfikowalne maszynowo; wobec CSV: zachowuje zagnieżdżenie i typy.

[N] i {fields}: strukturalne poręcze dla modelu

[3] i {day,...} służą nie tylko do oszczędzania tokenów — to też weryfikowalny kontrakt, który przekazujesz modelowi:

  • Długość tablicy pozwala modelowi od razu odpowiedzieć na „ile rekordów zawiera zestaw danych“ i natychmiast zdemaskuje ucięcie, gdy liczba wierszy się nie zgadza.
  • Nagłówek pól deklaruje nazwy raz; model wyrównuje wartości według pozycji zamiast w każdym wierszu od nowa zgadywać dopasowanie kluczy.

To profilaktyka, przeciwieństwo naprawiania po fakcie. Naprawiacz JSON (zobacz przewodnik naprawy) ratuje dane po tym, jak model wypluje zepsuty JSON; deklaracje długości i pól w TOON zmniejszają na wejściu prawdopodobieństwo zepsutych danych. Rób i jedno, i drugie — wskaźnik błędów parsowania w połowie pipeline spada.

Kiedy nie używać TOON

Oficjalna sekcja „When Not to Use TOON“ jest orzeźwiająco bezpośrednia. Cztery scenariusze, zostaw je takimi, jakie są:

Scenariusz Dlaczego unikać Najlepszy wybór
Głęboko zagnieżdżone, niejednolite struktury Kwalifikacja tabelaryczna ≈ 0%; kompaktowy JSON często wygrywa Kompaktowy JSON
Półjednolite tablice Nieregularne pola, oszczędność znika Zostaw pipeline JSON
Czysto tabelaryczne dane TOON kosztuje 5–10% narzutu względem CSV CSV
Wrażliwe na opóźnienia (modele lokalne/kwantyzowane) Mniej tokenów ≠ szybszy inference Najpierw zmierz TTFT

Półjednolitość ocenia się według kwalifikacji tabelarycznej (tabular eligibility): oficjalnie, przy kwalifikacji 40–60% oszczędność jest już marginalna. Migracja formatu ma realny koszt — parsery, walidatory i skrypty w dół strumienia zmieniają się wszystkie — więc jeśli zysk jest poniżej dziesięciu procent, niczego nie ruszaj.

Wdrożenie: encode / decode i CLI

Oficjalna biblioteka TypeScript, w obu kierunkach:

npm install @toon-format/toon
# Konwersja wsadowa też idzie przez 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)  // ściśle równe danym oryginalnym

Istnieją implementacje w Pythonie, Go, Rust i .NET; zanim jakąś wybierzesz, porównaj listę implementacji w oficjalnym repozytorium specyfikacji i upewnij się, że pokrywa składniowe funkcje, których używasz. Przed produkcją zrób asercję round-trip: decode(encode(oryginał)) musi być głęboko równe oryginałowi; jeśli nie — problem leży w implementacji albo w danych.

Jak to się wpisuje w Twój istniejący pipeline JSON

TOON niczego nie zmienia w Twoim pipeline JSON; dodaje konwersję na granicy. Zalecana kolejność:

  1. Najpierw upewnij się, że JSON jest czysty. Zepsuty JSON da zepsuty TOON. Walidację składni i naprawę opisuje Przewodnik naprawy JSON.
  2. Sprawdź kształt danych. Wszystkie obiekty tablicy mają te same pola? Najpierw znormalizuj — albo przyznaj, że konwersja nie jest warta zachodu.
  3. Konwertuj i próbkowo porównuj. Po konwersji porównaj kilka wierszy z oryginalnym JSON, żeby upewnić się, że wyrównanie pól nie zjechało.
  4. Oceń korzyść. Dla jednolitych list wierszowa logika podręcznika JSONL działa też przy konwersji strumieniowej; co do relacji rozmiaru i kosztu prawdziwy związek JSON minify i gzip daje tę samą lekcję: najpierw mierzyć, potem konwertować.

Czy TOON zastąpi JSON?

Nie. TOON koduje model danych JSON; jego miejsce to granica promptu, podczas gdy przechowywanie i wymiana między programami pozostają terytorium JSON. Użyj TOON do segmentu „dać modelowi“ i zostaw resztę łańcucha nietkniętą.

Jaki stosunek ma TOON do YAML i CSV?

Obiekty wyglądają jak YAML (wcięcia zamiast klamer); jednolite tablice wyglądają jak CSV (nagłówek zadeklarowany raz, wiersze w strumieniu). Ale TOON ma jawne deklaracje długości, których YAML nie ma, i zachowuje zagnieżdżenie i typy, których CSV nie ma — stoi między nimi, z poręczami weryfikowalnymi maszynowo.

Czy konwersja TOON na JSON traci dane?

Nie: obiekty, tablice, stringi, liczby, booleany i null odpowiadają jeden do jednego, a decode(encode(x)) jest ściśle równe oryginałowi. Jedyna ostrożność — wcześniej znormalizuj typy spoza JSON jak Date i NaN; inaczej równość obowiązuje dopiero po round-trip.

Jak sprawdzić, czy skonwertowany TOON jest poprawny?

Dwie kontrole: asercja round-trip (encode, potem decode, głęboka równość z oryginałem) i wzrokowa inspekcja nagłówka — liczba [N] musi równać się liczbie wierszy, a pola {fields} muszą wyrównywać się jeden do jednego z wartościami rozdzielonymi przecinkami w każdym wierszu. Po stronie modelu możesz jeszcze przed odpowiedzią poprosić o podanie długości tablicy.