YAML i TOON są opisywane jako "bardziej czytelne niż JSON" — i to opisanie jest technicznie prawdziwe dla obu, co czyni je bezużytecznym. Prawdziwe pytanie brzmi: czytelny dla kogo i w jakim celu? YAML jest zoptymalizowany do ludzkiej edycji: komentarze, anchory, wieloliniowe ciągi, wcięcia odzwierciedlające sposób, w jaki programiści myślą o konfiguracji. TOON jest zoptymalizowany do przetwarzania maszynowego: minimalne tokeny, brak niejednoznaczności, brak składni istniejącej wyłącznie dla wygody człowieka. To są różne zadania. Mylenie ich prowadzi do YAML w promptach LLM — co jest gorsze niż JSON — i TOON w manifestach Kubernetes, których nikt nie chce ręcznie edytować. Ten artykuł wyraźnie wyznacza granicę.
YAML w dwóch zdaniach
YAML to przyjazny dla człowieka format serializacji danych zaprojektowany dla plików konfiguracyjnych, pipeline'ów CI/CD i dowolnych dokumentów strukturalnych, które programista będzie czytał, pisał i utrzymywał ręcznie. Jego definiujące cechy — komentarze inline, mechanika DRY anchor/alias, literały ciągów wieloliniowych i struktura oparta na wcięciach — wszystkie istnieją, aby format był przyjemny dla ludzi, nie efektywny dla maszyn.
Kanoniczne przypadki użycia to workflow'y GitHub Actions, manifesty Kubernetes, pliki Docker Compose i konfiguracja aplikacji dostarczana wraz z kodem. Jeśli oczekuje się, że człowiek otworzy plik i go edytuje, YAML jest mocnym wyborem. Specyfikacja YAML 1.2 sformalizowała wiele przypadków brzegowych, które trapiły YAML 1.1 — najbardziej infamously Problem Norwegii, gdzie kod kraju NO był parsowany jako boolean false w parserach YAML 1.1. Nowoczesne parsery celujące w YAML 1.2 obsługują to poprawnie, ale jest to użyteczne przypomnienie, że pozorna prostota YAML ukrywa prawdziwą złożoność parsera.
- Komentarze.
# to jest komentarz— YAML obsługuje komentarze inline i pełne linie. To samo sprawia, że jest właściwym wyborem dla każdej konfiguracji, którą człowiek będzie utrzymywać. - Anchory i aliasy. Zdefiniuj blok raz za pomocą
&anchor, używaj go ponownie gdziekolwiek za pomocą*alias. Niezbędne dla konfiguracji DRY Kubernetes i wielośrodowiskowych pipeline'ów CI. - Wieloliniowe ciągi. Literałowe (
|) i złożone (>) skalary blokowe pozwalają osadzać skrypty shell, zapytania SQL lub dane certyfikatów czysto wewnątrz pliku YAML. - Czytelne wcięcia. Struktura jest definiowana przez białe znaki, co naturalnie mapuje na sposób, w jaki programiści myślą o zagnieżdżonych hierarchiach konfiguracji.
- Słabości. Wrażliwość na wcięcia oznacza, że błędnie umieszczona spacja jest błędem parsowania. Znaki tabulacji są zabronione. Konwersja boolean YAML 1.1 (Problem Norwegii,
yes/no,on/off) spowodowała prawdziwe błędy produkcyjne. Dane tabelaryczne wyrażone jako tablica obiektów są bardziej gadatliwe niż nawet JSON.
TOON w dwóch zdaniach
TOON to kompaktowy format serializacji zaprojektowany do przekazywania danych strukturalnych do i od dużych modeli językowych, gdzie każdy token kosztuje pieniądze, a przestrzeń okna kontekstowego jest skończona. Jego kluczową innowacją jest notacja tabelaryczna: dla zestawów danych, gdzie każdy rekord dzieli te same pola, klucze są deklarowane raz w nagłówku i pominięte w każdym kolejnym wierszu — co jest przeciwieństwem tego, co robią JSON i YAML.
TOON nie jest formatem konfiguracji i nigdy nie miał nim być. Nie ma składni komentarzy. Nie ma anchorów. Nie chciałbyś ręcznie edytować zbioru danych TOON z 500 wierszami bardziej niż chciałbyś ręcznie edytować plik binarny. To co TOON daje Ci to format, który koduje te same informacje co JSON w znacznie mniejszej liczbie tokenów — a mniej tokenów oznacza niższe koszty API, większe efektywne zestawy danych na prompt i mniejszą presję na limity okna kontekstowego. Tokenizer OpenAI to najszybszy sposób, aby zobaczyć to w praktyce: wklej ten sam zestaw danych w obu formatach i porównaj.
- Notacja tabelaryczna.
name[count]{col1,col2,...}:po którym następuje jeden wiersz wartości na linię. Klucze pojawiają się dokładnie raz niezależnie od liczby wierszy. - Notacja obiektowa.
{key:value,key2:value2}— bez cudzysłowów na kluczach, bez dodatkowych białych znaków. - Jednoznaczne parsowanie. Brak konwersji boolean, brak wrażliwości na wcięcia, brak rozbieżności wersji specyfikacji.
- Brak składni komentarzy. TOON nie ma mechanizmu dla komentarzy inline — z założenia. Jest to format danych, nie format dokumentu.
- Słabości. Niszowe narzędzia, brak historii edycji przez człowieka, nieodpowiedni dla żadnego pliku, który programista będzie bezpośrednio otwierał i edytował.
Porównanie obok siebie: te same dane w środowisku każdego formatu
Najbardziej uczciwe porównanie pokazuje każdy format robiący to, w czym jest naprawdę dobry — nie wymuszając konfrontację, gdzie jeden jest wyraźnie złym narzędziem.
Po pierwsze, manifest Kubernetes Deployment. To jest terytorium domowe YAML: plik konfiguracyjny utrzymywany przez człowieka z komentarzami, anchorami dla wartości współdzielonych i głębokim zagnieżdżaniem mapującym na logiczną hierarchię obiektu Kubernetes:
# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
name: payments-service
namespace: production
labels:
app: payments-service
version: "2.4.1"
spec:
replicas: 3
selector:
matchLabels:
app: payments-service
template:
metadata:
labels:
app: payments-service
spec:
containers:
- name: payments-service
image: registry.example.com/payments-service:2.4.1
ports:
- containerPort: 8080
env:
- name: DB_HOST
valueFrom:
secretKeyRef:
name: payments-db-secret
key: host
- name: LOG_LEVEL
value: "info"
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "500m"
memory: "512Mi"Pisanie tego w TOON byłoby bezcelowe — nie są to dane tabelaryczne, będą edytowane przez ludzi i korzysta z komentarzy wyjaśniających nieoczywiste wartości. YAML jest tutaj właściwym narzędziem i nie ma żadnej kontrowersji.
Teraz te same dane na terytorium domowym TOON: zbiór danych użytkowników przekazywany do LLM do analizy. Tutaj notacja tabelaryczna TOON wykonuje pracę:
users[12]{id,email,plan,mrr,country,signupDate,churned}:
1001,[email protected],pro,99.00,US,2024-01-15,false
1002,[email protected],starter,19.00,GB,2024-02-03,false
1003,[email protected],enterprise,499.00,DE,2023-11-20,false
1004,[email protected],pro,99.00,CA,2024-03-10,true
1005,[email protected],starter,19.00,AU,2024-01-28,false
1006,[email protected],pro,99.00,US,2023-12-05,false
1007,[email protected],enterprise,499.00,FR,2024-02-14,false
1008,[email protected],starter,19.00,IN,2024-03-22,true
1009,[email protected],pro,99.00,US,2024-01-09,false
1010,[email protected],enterprise,499.00,JP,2023-10-31,false
1011,[email protected],starter,19.00,BR,2024-04-01,false
1012,[email protected],pro,99.00,US,2024-02-19,truePisanie tego jako YAML — tablica 12 obiektów, każdy z 7 kluczami — powtarzałoby wszystkie 7 nazw kluczy 12 razy. To 84 deklaracje kluczy dla 84 wartości. TOON deklaruje każdy klucz raz.
Gdzie YAML bije TOON za każdym razem
Każdy plik, który człowiek będzie otwierał, czytał i edytował, należy do YAML (lub JSON dla prostszych przypadków). Decydujące zalety to komentarze i anchory — dwie cechy, których TOON po prostu nie ma.
- Pipeline'y CI/CD. GitHub Actions, GitLab CI, CircleCI — wszystkie natywne dla YAML. Możliwość zakomentowania kroku podczas debugowania jest naprawdę użyteczna.
- Kubernetes i Helm. Każdy manifest, każdy plik values, każdy szablon chart. System anchorów YAML jest aktywnie używany w złożonych chartach Helm, aby uniknąć powtarzania konfiguracji środowisk.
- Docker Compose. Definicje wielu usług z komentarzami wyjaśniającymi nieoczywiste powiązania portów, montowania woluminów i konfiguracje sieci.
- Pliki konfiguracyjne aplikacji. Konfiguracje w stylu
pyproject.toml, ustawienia aplikacji, flagi funkcji z komentarzami wyjaśniającymi inline. - Każdy plik w kontroli wersji, który ludzie przeglądają w PR. Komentarze w konfiguracji YAML są częścią dokumentacji. TOON w ogóle nie może uczestniczyć w tym przepływie pracy.
&anchor) i aliasy (*alias) są niedostatecznie używane, ale potężne. Konfiguracja Kubernetes, która współdzieli te same zmienne środowiskowe między wieloma kontenerami, może zdefiniować je raz za pomocą &common-env i odwołać się do bloku za pomocą *common-env — utrzymując plik DRY bez żadnego silnika szablonów. TOON nie ma równoważnego mechanizmu.Gdzie TOON bije YAML za każdym razem
Wszelkie dane, które są generowane programatycznie i przekazywane do LLM, należą do TOON. YAML jest faktycznie gorszy niż JSON dla tego przypadku użycia — jego składnia ciężka od wcięć i powtarzające się nazwy kluczy dodają tokeny bez dodawania żadnych informacji potrzebnych modelowi.
- Payloady promptów LLM. Podawanie zestawu danych do GPT-4o, Claude lub Gemini do analizy, klasyfikacji lub wzbogacania. Notacja tabelaryczna TOON redukuje liczbę tokenów o 40–60% w porównaniu z JSON, a w porównaniu z YAML różnica jest jeszcze większa.
- Instrukcje wyjścia LLM. Instruowanie modelu do odpowiadania w TOON produkuje krótsze, tańsze wyjście. Wyjście YAML z LLM jest gadatliwe i wrażliwe na wcięcia — jedna błędnie wyrównana spacja i parsowanie się psuje.
- Zestawy danych generowane programatycznie. Jeśli Twój kod buduje dane, powinien budować TOON. Nie ma ludzkiego edytora korzystającego z komentarzy lub czytelnych wcięć.
- Pipeline'y przetwarzania wsadowego o wysokim wolumenie. Przetwarzasz 10 000 rekordów przez LLM dziennie? 50% redukcja tokenów to 50% redukcja tej linii w rachunku API.
- Presja okna kontekstowego. Gdy musisz zmieścić więcej danych w limicie kontekstu modelu, TOON pozwala spakować więcej wierszy przy tym samym koszcie tokenów.
Rzeczywistość liczby tokenów
Oto ten sam zbiór danych 10 wierszy w trzech formatach. Liczby są przybliżone, ale spójne z tym, co zgłasza tokenizer OpenAI dla tokenizacji GPT-4o.
Tablica obiektów YAML:
- id: 1
username: alice_chen
plan: pro
mrr: 99.00
country: US
- id: 2
username: bob_martin
plan: starter
mrr: 19.00
country: GB
- id: 3
username: carol_white
plan: enterprise
mrr: 499.00
country: DE
- id: 4
username: dan_patel
plan: pro
mrr: 99.00
country: CA
- id: 5
username: eve_torres
plan: starter
mrr: 19.00
country: AU
- id: 6
username: frank_liu
plan: pro
mrr: 99.00
country: US
- id: 7
username: grace_kim
plan: enterprise
mrr: 499.00
country: FR
- id: 8
username: henry_obi
plan: starter
mrr: 19.00
country: IN
- id: 9
username: iris_novak
plan: pro
mrr: 99.00
country: US
- id: 10
username: james_sato
plan: enterprise
mrr: 499.00
country: JPNotacja tabelaryczna TOON, te same dane:
users[10]{id,username,plan,mrr,country}:
1,alice_chen,pro,99.00,US
2,bob_martin,starter,19.00,GB
3,carol_white,enterprise,499.00,DE
4,dan_patel,pro,99.00,CA
5,eve_torres,starter,19.00,AU
6,frank_liu,pro,99.00,US
7,grace_kim,enterprise,499.00,FR
8,henry_obi,starter,19.00,IN
9,iris_novak,pro,99.00,US
10,james_sato,enterprise,499.00,JPPowód, dla którego YAML wypada gorzej niż JSON na danych tabelarycznych, jest strukturalny: YAML używa jednej linii na parę klucz-wartość z wcięciem, więc 5-polowy obiekt kosztuje 5 linii plus marker listy. JSON przynajmniej opakowuje cały obiekt w jeden zestaw nawiasów klamrowych. TOON całkowicie eliminuje powtarzanie kluczy — klucze pojawiają się raz, wartości są pakowane do wierszy. Oszczędności rosną z liczbą wierszy i liczbą pól.
Używanie TOON w Twoim kodzie
Pakiet @toon-format/toon obsługuje kodowanie i dekodowanie:
npm install @toon-format/toonimport { encode, decode } from '@toon-format/toon';
// Your dataset — could come from a database query, API response, anywhere
const users = [
{ id: 1001, email: '[email protected]', plan: 'pro', mrr: 99.00, country: 'US' },
{ id: 1002, email: '[email protected]', plan: 'starter', mrr: 19.00, country: 'GB' },
{ id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
// ...more rows
];
// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
// 1001,[email protected],pro,99.00,US
// 1002,[email protected],starter,19.00,GB
// 1003,[email protected],enterprise,499.00,DE
const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.
Dataset:
${toonPayload}`;
// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }Przewodnik decyzyjny
Wybór między YAML a TOON jest w praktyce prawie nigdy niejednoznaczny:
- Używaj YAML jeśli człowiek będzie czytał lub edytował plik — pipeline'y CI/CD, manifesty Kubernetes, Docker Compose, konfiguracja aplikacji, playbooki Ansible.
- Używaj YAML jeśli potrzebujesz komentarzy inline do wyjaśnienia nieoczywistych wartości.
- Używaj YAML jeśli potrzebujesz anchorów i aliasów, aby utrzymać złożoną konfigurację DRY.
- Używaj YAML jeśli pracujesz z narzędziem, które konwencjonalnie oczekuje YAML (Helm, GitHub Actions, k8s
kubectl apply). - Używaj TOON jeśli dane trafiają do promptu LLM — szczególnie dane tabelaryczne z wieloma wierszami.
- Używaj TOON jeśli prosisz LLM o zwracanie danych strukturalnych i chcesz krótszego, tańszego wyjścia.
- Używaj TOON jeśli liczba tokenów ma znaczenie — pipeline'y o wysokim wolumenie, długie zestawy danych, presja okna kontekstowego.
- Używaj TOON jeśli dane są generowane programatycznie i żaden człowiek nie będzie ich bezpośrednio edytował.
- Używaj JSON (nie YAML ani TOON) jeśli budujesz API REST, przechowujesz dane w bazie danych lub integrujesz z narzędziami zewnętrznymi oczekującymi JSON.
Podsumowanie
YAML i TOON zajmują zupełnie różne pozycje w Twoim stosie. YAML należy do Twojego repozytorium obok Twojego kodu — pliki konfiguracyjne, definicje pipeline'ów, manifesty infrastruktury. TOON należy na granicy między Twoją aplikacją a API LLM, gdzie konwertuje Twoje dane strukturalne do najbardziej efektywnej tokenowo reprezentacji przed wysłaniem i konwertuje odpowiedź modelu z powrotem na wyjściu. Nie ma znaczącego nakładania się tych zadań, dlatego pytanie nie brzmi "które jest lepsze", ale "które należy tutaj".
Jeśli pracujesz z TOON, Formatter TOON i Walidator TOON to najszybszy sposób na inspekcję i weryfikację ciągów TOON. Konwerter JSON do TOON konwertuje istniejące payloady JSON do TOON do użytku LLM, a konwerter TOON do JSON obsługuje podróż powrotną, gdy model odpowiada w TOON, a Twój downstream system oczekuje JSON. Zobacz też artykuł Wikipedii o YAML dla zwięzłej historii formatu i podsumowania jego znanych przypadków brzegowych.