Większość programistów ma krótką mentalną listę formatów danych: JSON do API, CSV do arkuszy kalkulacyjnych, YAML do plików konfiguracyjnych, może XML jeśli pracujesz z systemami legacy. Ale jest nowszy format, który po cichu toruje sobie drogę w przestrzeni narzędzi AI i warto go poznać — TOON, czyli Token-Oriented Object Notation. Został zaprojektowany od podstaw do rozwiązania konkretnego problemu: przekazywania danych strukturalnych do dużych modeli językowych bez przepalania budżetu tokenowego.

Czym jest TOON?

TOON to skrót od Token-Oriented Object Notation. Jest to kompaktowy format serializacji danych stworzony specjalnie w celu minimalizowania liczby tokenów zużywanych podczas osadzania danych strukturalnych w promptach lub odpowiedziach LLM. Można o nim myśleć jak o JSON z usuniętą nadmiarowością — bez powtarzających się nazw kluczy w tablicach, bez zbędnych cudzysłowów, bez końcowych białych znaków — tylko sygnał z jak najmniejszą ilością składniowego szumu.

Pakiet npm to @toon-format/toon, który udostępnia proste API encode / decode działające w każdym projekcie Node.js lub nowoczesnym bundlerze. Pliki TOON używają rozszerzenia .toon.

Dlaczego nie wystarczy JSON?

JSON świetnie sprawdza się w komunikacji między maszynami, gdzie przepustowość jest tania, a parsowanie obsługuje środowisko uruchomieniowe. Ale gdy wysyłasz dane jako część promptu do OpenAI API lub Anthropic API, każdy znak ma znaczenie — dosłownie. Oba API pobierają opłaty za token, a tokeny odpowiadają mniej więcej 4 znakom angielskiego tekstu.

Rozważ tabelę 100 rekordów użytkowników. W JSON powtarzałbyś klucze — "id", "name", "role", "email" — raz na rekord. To 100 kopii tych samych informacji strukturalnych. Składnia tabelaryczna TOON definiuje te klucze raz, a następnie wyświetla wartości wiersz po wierszu, tak jak robi to CSV, ale z zachowaną strukturą obiektową. Oszczędności tokenów na rzeczywistych zbiorach danych mogą wynosić 40–70% w porównaniu do zwięzłego JSON.

Zasada kciuka: Jeśli osadzasz w prompcie więcej niż kilka rekordów, TOON niemal zawsze będzie tańszy niż JSON. Użyj naszego konwertera JSON do TOON, aby zobaczyć dokładnie, o ile mniejszy staje się Twój payload.

Składnia TOON w pigułce

TOON obsługuje cztery podstawowe kształty danych: skalary (ciągi, liczby, wartości logiczne), tablice, obiekty i dane tabelaryczne. Składnia skalarów i kolekcji będzie znajoma jeśli pracowałeś z JSON — format tabelaryczny jest tym, czym TOON naprawdę się wyróżnia.

Prosty obiekt usuwa białe znaki wokół zewnętrznych nawiasów klamrowych, pomija zbędne cudzysłowy i rozdziela pary klucz–wartość przecinkami:

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

Prosta tablica skalarów wygląda dokładnie tak, jak można się spodziewać:

text
[1,2,3]

A teraz to, co jest naprawdę interesujące — dane tabelaryczne. To składnia, która sprawia, że TOON jest atrakcyjny w zastosowaniach LLM. Zamiast powtarzać klucze dla każdego obiektu w tablicy, deklarujesz schemat raz w nagłówku i wyświetlasz wartości wiersz po wierszu:

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

Ten blok reprezentuje tablicę 3 obiektów użytkowników — ekwiwalent poniższego JSON — ale przy użyciu ułamka tokenów. Nagłówek users[3]{id,name,role} mówi parserowi: "to jest zmienna o nazwie users, ma 3 wiersze, a każdy wiersz mapuje się na pola id, name i role". Wiersze to czyste wartości, bez powtarzania kluczy.

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

Instalacja i używanie pakietu @toon-format/toon

Oficjalny pakiet npm obsługuje zarówno kodowanie wartości JavaScript do ciągów TOON, jak i dekodowanie ciągów TOON z powrotem do obiektów i tablic JavaScript. Zainstaluj go z rejestru npm:

bash
npm install @toon-format/toon

Pakiet eksportuje dwie funkcje — encode i decode:

ts
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}

Opcja indent w encode() kontroluje, czy wyjście jest ładnie sformatowane. W przypadku promptów LLM zazwyczaj będziesz chciał zwięzłego wyjścia (bez wcięć), aby zaoszczędzić tokeny. Do debugowania lub czytelnych dla człowieka plików .toon, { indent: 2 } daje ładnie sformatowane wyjście.

Rzeczywisty przypadek użycia: wysyłanie rekordów do LLM

Wyobraź sobie, że budujesz funkcję analityki produktu, która musi podsumować aktywność użytkowników. Pobierasz ostatnie rekordy sesji z bazy danych i chcesz wysłać je do LLM w celu podsumowania w języku naturalnym. Oto jak to wygląda z TOON:

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

Reprezentacja TOON tych 5 rekordów sesji jest znacznie krótsza niż odpowiedni JSON, który powtarzałby "userId", "action", "duration" i "page" pięć razy każdy. Przy setkach rekordów oszczędności są znaczne i przekładają się bezpośrednio na niższe koszty API i szybsze czasy odpowiedzi (mniej tokenów do przetworzenia w oknie kontekstowym).

Kluczowe typy danych w TOON

TOON mapuje się czysto na prymitywy, których już używasz w JavaScript i większości innych języków:

  • Ciągi znaków — Bez cudzysłowów, gdy nie zawierają znaków specjalnych. W cudzysłowach podwójnych, gdy zawierają przecinki, dwukropki lub białe znaki.
  • Liczby — Całkowite i zmiennoprzecinkowe zapisane tak jak są: 42, 3.14, -7.
  • Wartości logiczne — true i false, tak samo jak w JSON.
  • Null — Zapisywany jako null dla wartości nieobecnych lub niezdefiniowanych.
  • Tablice — Wbudowana składnia nawiasów kwadratowych [val1,val2,val3] dla krótkich list; składnia nagłówka tabelarycznego dla tablic obiektów.
  • Obiekty — Składnia nawiasów klamrowych {key:value,key2:value2} dla pojedynczych obiektów.
  • Dane tabelaryczne — Gwiazda pokazu: nagłówek name[n]{col1,col2,...}: po którym następują wiersze oddzielone przecinkami — idealny dla dowolnej kolekcji rekordów o tym samym kształcie.

Kiedy sięgać po TOON, a kiedy po inne formaty

TOON nie stara się zastąpić JSON jako ogólnego formatu wymiany. Wypełnia konkretną niszę. Oto szybki przewodnik decyzyjny:

  • Używaj JSON gdy budujesz API REST, przechowujesz dokumenty w bazie danych lub przekazujesz dane między usługami. JSON jest powszechnie obsługiwany, dobrze narzędziowany i czytelny dla człowieka.
  • Używaj TOON gdy dane strukturalne są częścią promptu lub okna kontekstowego LLM, a liczba tokenów ma znaczenie. Format tabelaryczny świeci, gdy pracujesz z wierszami rekordów — listami użytkowników, wpisami logów, katalogami produktów, zdarzeniami analitycznymi.
  • Używaj CSV gdy potrzebujesz tylko płaskich danych tabelarycznych i konsument oczekuje CSV (arkusze kalkulacyjne, narzędzia BI). CSV nie ma zagnieżdżania obiektów, więc TOON jest bardziej ekspresyjny.
  • Używaj YAML do plików konfiguracyjnych edytowanych przez człowieka, gdzie czytelność i komentarze są ważniejsze niż zwięzłość.
  • Używaj TOON również dla wyjść narzędzi LLM: jeśli LLM wywołuje Twoje narzędzie i zwraca ustrukturyzowane wyniki, kodowanie tych wyników w TOON oszczędza tokeny zarówno po stronie wejściowej, jak i wyjściowej wywołania API.
Nie wiesz, jak TOON wypada w porównaniu z Twoim aktualnym payloadem JSON? Wklej swój JSON do konwertera JSON do TOON, a narzędzie pokaże Ci obie reprezentacje obok siebie, wraz z szacowanym porównaniem liczby tokenów.

Podsumowanie

TOON — Token-Oriented Object Notation — to kompaktowy format serializacji zbudowany dla ery LLM. Zachowuje znajomą strukturę JSON (obiekty, tablice, skalary), wprowadzając jednocześnie składnię tabelaryczną, która eliminuje zbędne powtarzanie kluczy w rekordach. Rezultatem jest format, który może być o 40–70% mniejszy niż odpowiedni JSON, co przekłada się bezpośrednio na niższe koszty tokenów podczas pracy z OpenAI API, Anthropic API lub dowolną inną usługą LLM rozliczaną tokenami.

Jeśli chcesz eksplorować TOON praktycznie, mamy pełen zestaw narzędzi tutaj: użyj Formattera TOON do ładnego wydruku i inspekcji dokumentów TOON, Walidatora TOON do wykrywania błędów składniowych, konwertera JSON do TOON do migracji istniejących payloadów, i konwertera TOON do JSON jeśli potrzebujesz iść w drugą stronę. Pakiet npm @toon-format/toon daje Ci encode i decode do integracji TOON bezpośrednio w Twoim kodzie Node.js lub po stronie przeglądarki w kilka minut.

← All TOON articles Browse all categories →