Trzy formaty wchodzą na spotkanie planowania. JSON mówi, że poradzi sobie ze wszystkim. CSV mówi, że jest szybki i lekki. TOON mówi, że jest tu, aby rozmawiać z AI. Wszyscy mają rację — do różnych zadań. Frustrującą częścią nie jest to, że te formaty istnieją, ale to, że wybranie złego do Twojego przypadku użycia kosztuje Cię w realny, konkretny sposób: gadatliwe payloady, uszkodzone importy, drogie rachunki LLM lub bóle głowy z parsowaniem. Ten przewodnik daje Ci jasne ramy do wyboru.

Krótki portret każdego formatu

JSON (JavaScript Object Notation) wyłonił się z JavaScript na początku lat 2000 i stał się dominującym formatem dla API webowych dzięki swojej prostocie i ekspresywności. Natywnie obsługuje zagnieżdżone struktury, rozróżnia między ciągami, liczbami, wartościami logicznymi i nullami bez żadnych dodatkowych ceremonii, i jest określony przez RFC 8259. Każdy nowoczesny język ma bibliotekę JSON pierwszej klasy.

CSV (Comma-Separated Values) jest starszy od sieci. Jest zdefiniowany przez RFC 4180 i jest zasadniczo lingua franca płaskich danych tabelarycznych. Otwórz dowolny CSV w Excel, Google Sheets lub Numbers, a po prostu działa. Dla czystych płaskich tabel jest to najbardziej kompaktowy i powszechnie importowalny format, jaki istnieje.

TOON to nowszy format zbudowany specjalnie dla przepływów pracy LLM. Czerpie inspirację z obu — jak CSV używa struktury nagłówek-raz-potem-wiersze dla danych tabelarycznych, ale jak JSON może również kodować zagnieżdżone obiekty i tablice. Cały jego projekt jest ukierunkowany na minimalizowanie liczby tokenów podczas przekazywania danych do i z dużych modeli językowych.

Te same dane w trzech formatach

Aby uczynić to konkretnym, użyjmy katalogu produktów zawierającego zagnieżdżony obiekt specs — rzeczywisty kształt, który sensownie testuje wszystkie trzy formaty. Oto cztery produkty ze sklepu z elektroniką:

JSON — ekspresyjny, naturalnie obsługuje zagnieżdżanie, ale gadatliwy dla powtarzających się danych wierszy:

json
[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — kompaktowy, przyjazny dla Excela, ale zagnieżdżony obiekt specs musi zostać spłaszczony. Nie ma standardowego sposobu jego reprezentacji, więc albo tracimy zagnieżdżanie, albo deformujemy je do ciągu:

text
id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440
Zauważ rzadkie kolumny w CSV. Ponieważ każdy produkt ma różne klucze specyfikacji, musieliśmy utworzyć kolumnę dla każdego możliwego pola specyfikacji — i większość wierszy jest w większości pusta. To jest fundamentalny problem z używaniem CSV dla niejednorodnych danych zagnieżdżonych.

TOON — nagłówek zadeklarowany raz, wiersze są kompaktowe, zagnieżdżone obiekty zakodowane inline:

text
products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

Gdzie każdy format zawodzi

Zrozumienie trybów awaryjnych jest równie ważne jak znajomość mocnych stron.

  • JSON zawodzi dla tabel. Powtarzanie każdej nazwy klucza w każdym wierszu jest naprawdę marnotrawne. Zbiór danych 1000 wierszy, gdzie każdy wiersz ma 8 kluczy, oznacza, że "id", "name", "price" i tak dalej jest zapisywanych 1000 razy każdy. W przypadku wejścia LLM przekłada się to bezpośrednio na koszt tokenów; dla inspekcji ludzkiej jest to po prostu szum.
  • CSV zawodzi dla danych zagnieżdżonych. Format nie ma koncepcji zagnieżdżania. Możesz zastringować zagnieżdżony obiekt do komórki, ale wtedy konsument musi wiedzieć, aby parsować tę komórkę — po prostu przeniosłeś problem. CSV również nie ma natywnego systemu typów: true to ciąg, 42 to ciąg, null jest niejednoznaczny. Narzędzia obsługują to niespójnie.
  • TOON zawodzi poza kontekstami LLM. To niszowy format z węższym ekosystemem. Nie znajdziesz natywnej obsługi TOON w PostgreSQL, w Twoim frameworku REST ani w Excelu. Pakiet npm dobrze obsługuje przepływy pracy JavaScript/TypeScript, ale jeśli sięgasz po TOON w kontekście, który nie ma nic wspólnego z AI, prawdopodobnie nadmiernie projektujesz.
  • CSV zawodzi dla wartości zawierających przecinki lub nowe linie. Reguły cytowania RFC 4180 to obsługują, ale wiele producentów i konsumentów CSV implementuje je niespójnie. Nazwa produktu jak 27" IPS Monitor, Black lub opis z podziałami wierszy staje się zagrożeniem niezawodności.

Macierz decyzyjna

Oto praktyczny przewodnik. Dopasuj swoją sytuację do odpowiedniego formatu:

  • Twoje dane trafiają do promptu LLM → TOON. Szczególnie jeśli są tabelaryczne. Użyj JSON do TOON do konwersji przed wywołaniem API.
  • Twoje dane wracają z LLM i muszą być przetworzone → TOON (dla wyjścia), następnie dekoduj do JSON lub natywnego obiektu do użytku downstream z TOON do JSON.
  • Twoje dane są czysto płaskie tabelaryczne (te same klucze w każdym wierszu) i trafiają do/z arkuszy kalkulacyjnych → CSV. Jest to najmniejsza reprezentacja i powszechnie importowalna.
  • Twoje dane są płaskie tabelaryczne, ale będą transformowane przez kod (nie arkusze kalkulacyjne) → CSV lub JSON. JSON jest bezpieczniejszy jeśli typy mają znaczenie (nie chcesz "true" zamiast true).
  • Twoje dane mają zagnieżdżone obiekty lub tablice → JSON. Nie walcz z ograniczeniem CSV tylko dla płaskich danych. Jeśli zagnieżdżanie trafia do LLM, zakoduj do TOON po zbudowaniu struktury.
  • Twoje dane trafiają do API REST lub są przechowywane w bazie danych → JSON. Zawsze.
  • Twoje dane to plik konfiguracyjny → JSON lub YAML. Ani CSV, ani TOON tu nie należą.
  • Potrzebujesz maksymalnej przenośności i parsera bez zależności → JSON lub CSV. Oba mają natywną lub prawie natywną obsługę wszędzie.

Używanie wszystkich trzech w jednym pipielinie

Realistyczny pipeline może używać wszystkich trzech. Wyobraź sobie przepływ pracy e-commerce, który wzbogaca dane produktów opisami generowanymi przez AI:

ts
import { encode, decode } from '@toon-format/toon';

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

JSON dla warstwy API, TOON przez warstwę LLM, CSV dla czytelnego przez człowieka wyjścia. Każdy format wykonuje dokładnie zadanie, do którego był zaprojektowany.

Szybka referencja narzędzi

Jeśli przechodzisz między tymi formatami, te narzędzia pokryją typowe konwersje. Formatter TOON to najszybszy sposób na walidację i czyszczenie ciągów TOON. Konwerter JSON do TOON obsługuje etap przygotowania LLM. Idąc w drugą stronę po zwróceniu TOON przez LLM, TOON do CSV może bezpośrednio wyprodukować eksport gotowy do arkusza kalkulacyjnego, a CSV do JSON to narzędzie do normalizacji importów z Excela lub zewnętrznych dostawców danych. Dla szczegółów specyficznych dla TOON, oficjalny pakiet jest na npm.

Podsumowanie

JSON, CSV i TOON mają każdy wyraźną domenę. JSON to uniwersalny format wymiany danych strukturalnych — zagnieżdżonych lub płaskich, API, konfiguracja, przechowywanie. CSV to uniwersalny format dla płaskich danych tabelarycznych, które muszą podróżować między systemami i ludźmi — arkusze kalkulacyjne, importy, eksporty. TOON to format do efektywnego przekazywania danych strukturalnych przez systemy AI, gdzie każdy token ma znaczenie. Błąd, który popełnia większość programistów, to domyślne używanie JSON do wszystkiego, w tym promptów LLM, lub domyślne używanie CSV, a następnie odkrywanie wymagań zagnieżdżania w połowie projektu. Znaj kształt swoich danych, wiedz dokąd idą, a właściwy format zwykle wybiera się sam.

Aby głębiej zanurzyć się w kompromis JSON vs TOON, sprawdź porównanie TOON vs JSON. Dla informacji o specyfikacji CSV i jej dziwactwach, artykuł Wikipedii o CSV dobrze omawia historię i warianty formatu.

← All TOON articles Browse all categories →