JSON Toolkit

Гід з формату TOON: полегшіть JSON перед передачею LLM

Головне: Коли ви передаєте однорідний масив мовній моделі у форматі JSON, повторювані назви ключів і дужки з'їдають токени. TOON оголошує структуру лише один раз через індексовані об'єкти та табличні масиви, а дані вивантажує рядок за рядком. Офіційні бенчмарки показують близько 40% менше токенів із вищою точністю парсингу. Цей гід охоплює синтаксис, коли економія працює, коли конвертувати не варто та як з'єднати encode і decode.

Середній~6 хв читанняОпубліковано 2026-11-10Оновлено 2026-11-10
Синтаксис табличного масиву TOON: заголовок полів оголошено один раз, рядки даних вивантажуються послідовно

Синтаксичний надлишок JSON не має значення при передачі між машинами, але на вході LLM, який тарифікується за токенами, це реальні гроші: той самий однорідний масив повторює назви ключів десятки разів, і кожна фігурна дужка з кожними лапками відкушує шматок бюджету. TOON не вигадує нову модель даних — він переписує модель даних JSON дешевшою нотацією.

Що таке TOON: ще одне кодування JSON, а не конкурент

TOON (Token-Oriented Object Notation) — відкритий формат, що з'явився 2025 року, і його офіційне позиціонування вкладається в одне речення: компактне, без втрат і читабельне кодування моделі даних JSON. Він не вводить нових типів — об'єкти, масиви, рядки, числа, булеві значення та null відповідають JSON один до одного, а decode(encode(x)) строго дорівнює вихідним даним (типи поза JSON, як-от Date чи NaN, треба нормалізувати заздалегідь). Round-trip є втратоменого та детермінованим: той самий вхід завжди дає той самий вихід, що важливо для відтворюваних промптів.

Оскільки TOON кодує точно модель даних JSON, правильний спосіб його застосування — це формат кордону: застосунок продовжує працювати в JSON усередині, конвертує в TOON безпосередньо перед передачею даних у промпт і конвертує назад із відповіді моделі. Офіційна документація називає це «translation layer». Умовне розширення файлів — .toon; для HTTP-транспорту попередній media type — text/toon, у UTF-8.

Одне застереження щодо пошукового шуму: не плутайте з Toon Shader у 3D-графіці. Спільне лише слово.

Чому JSON особливо дорогий на вході LLM

Візьміть список замовлень, перелік користувачів чи зведення логів, записані як JSON-масив. Токени витрачаються у трьох місцях:

  1. Повторювані назви ключів. П'ятдесят записів замовлень пишуть "id", "amount" і "status" по п'ятдесят разів кожне. Подвойте дані — подвойте надлишок.
  2. Структурна пунктуація. Фігурні та квадратні дужки, двокрапки й коми — усе це токени, а вкладеність пакує їх ще щільніше.
  3. Лапки. Майже кожен ключ і кожне рядкове значення загорнуті у подвійні лапки.

Разом: вартість API, що тарифікується за токенами, зростає напряму; довгі входи раніше упираються в стелю контекстного вікна; а на дуже довгих входах модель частіше пропускає чи зміщує поля. Бенчмарк офіційної сторінки: на тестовому наборі зі змішаними структурами та чотирма моделями близько 40% менше токенів, а точність парсингу зростає з 70% (JSON) до 74% (TOON). Економія й точність тут не є трейд-оффом, бо компактніша структура робить межі помітнішими для моделі.

Синтаксис: індексовані об'єкти + табличні масиви

Ті самі дані прогнозу погоди у трьох формах. Версія JSON, приблизно 117 токенів:

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

Версія TOON, приблизно 66 токенів:

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

Три форми покривають усе, і серіалізатор обирає їх автоматично за формою даних:

Форма Підходить для Еквівалент у JSON
Індексований об'єкт Вкладені об'єкти { "location": { ... } }, індентація замінює фігурні дужки
Вбудований масив Масиви примітивів ["frost","wind"], [2] оголошує довжину
Табличний масив Масиви однорідних об'єктів Назви полів з'являються лише раз у заголовку {day,temp{min,max},...}; кожен рядок містить лише значення через кому

Однорідні вкладені об'єкти (temp{min,max}) згортаються в заголовок як група вкладених полів, а рядки даних залишаються плоскими. Правило лапок — мінімальне: рядки беруть лапки лише якщо містять роздільники, спеціальні символи або ризикують бути прочитаними як числа — одна з причин, чому TOON перемагає «компактний JSON» у підрахунку токенів. Ключова різниця з YAML: TOON має явні оголошення довжини та заголовки полів, які можна перевірити машиною; з CSV — зберігає вкладеність і типи.

[N] і {fields}: структурні поручні для моделі

[3] і {day,...} потрібні не лише для економії токенів — це ще й перевірюваний контракт, який ви передаєте моделі:

  • Довжина масиву дозволяє моделі одразу відповісти на «скільки записів у наборі даних» і миттєво викриває обрізання, коли кількість рядків не збігається.
  • Заголовок полів оголошує назви один раз; модель вирівнює значення за позицією замість того, щоб щоразу вгадувати відповідність ключів у кожному рядку.

Це профілактика, протилежність постфактум-відновленню. JSON-репаратор (див. гід із відновлення) відновлює дані після того, як модель видала зламаний JSON; оголошення довжини та полів у TOON знижують на вході ймовірність зіпсованих даних. Робіть і те, й те — частота збоїв парсингу посеред конвеєра падає.

Коли не варто використовувати TOON

Офіційний розділ «When Not to Use TOON» вражаюче прямолінійний. Чотири сценарії, варто тримати їх такими, як є:

Сценарій Чому варто уникати Кращий вибір
Глибоко вкладені, неоднорідні структури Таблична придатність ≈ 0%; компактний JSON часто виграє Компактний JSON
Напіводнорідні масиви Нерегулярні поля, економія зникає Тримайте JSON-конвеєр
Суто табличні дані TOON коштує 5–10% надлишку проти CSV CSV
Чутливі до затримки (локальні/квантизовані моделі) Менше токенів ≠ швидший інференс Спершу виміряйте TTFT

Напіводнорідність оцінюють за табличною придатністю (tabular eligibility): офіційно, із придатністю 40–60% економія вже маргінальна. Міграція формату має реальну ціну — парсери, валідатори та скрипти нижче за течією змінюються всі — тож якщо виграш менший за десять відсотків, не чіпайте нічого.

Впровадження: encode / decode та CLI

Офіційна TypeScript-бібліотека, в обидва боки:

npm install @toon-format/toon
# Пакетна конвертація також іде через 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)  // строго дорівнює вихідним даним

Існують реалізації Python, Go, Rust та .NET; перед тим як брати одну з них, звірте зі списком реалізацій в офіційному репозиторії специфікації та переконайтеся, що вона покриває синтаксичні можливості, якими ви користуєтесь. Перед продакшеном зробіть перевірку round-trip: decode(encode(оригінал)) має бути глибоко рівним оригіналу; якщо ні — проблема в реалізації або в даних.

Як це вписується у ваш наявний JSON-конвеєр

TOON нічого не змінює у вашому JSON-конвеєрі; він додає конвертацію на кордоні. Рекомендований порядок:

  1. Спершу переконайтеся, що JSON чистий. Зламаний JSON дає зламаний TOON. Синтаксичну перевірку й відновлення описано у Гіді з відновлення JSON.
  2. Перевірте форму даних. Усі об'єкти масиву мають однакові поля? Нормалізуйте спершу — або визнайте, що конвертація не варта зусиль.
  3. Конвертуйте й перевірте вибірково. Після конвертації звірте кілька рядків із оригінальним JSON, щоб пересвідчитися, що вирівнювання полів не зсунулося.
  4. Оцініть вигоду. Для однорідних списків рядкова логіка довідника JSONL застосовна до потокової конвертації; щодо співвідношення розміру й вартості — справжній зв'язок між JSON minify і gzip дає той самий урок: спершу міряти, потім конвертувати.

Чи замінить TOON JSON?

Ні. TOON кодує модель даних JSON; його місце — кордон промпту, тоді як зберігання й обмін між програмами лишаються територією JSON. Використовуйте TOON для сегмента «передати моделі» й залишайте решту ланцюга недоторканою.

Які стосунки в TOON із YAML та CSV?

Об'єкти схожі на YAML (індентація замість фігурних дужок); однорідні масиви схожі на CSV (заголовок оголошено раз, рядки потоково). Але TOON має явні оголошення довжини, яких немає в YAML, і зберігає вкладеність і типи, яких немає в CSV — він стоїть між ними, з перевірюваними машиною поручнями.

Чи втрачає дані конвертація TOON у JSON?

Ні: об'єкти, масиви, рядки, числа, булеві значення та null відповідають один до одного, а decode(encode(x)) строго дорівнює оригіналу. Єдине застереження — нормалізувати заздалегідь типи поза JSON, як-от Date і NaN; інакше рівність справедлива лише після round-trip.

Як перевірити, що конвертований TOON правильний?

Дві перевірки: перевірка round-trip (encode, потім decode, глибока рівність з оригіналом) і візуальний контроль заголовка — число [N] має дорівнювати кількості рядків, а поля {fields} мають вирівнюватися один до одного зі значеннями через кому в кожному рядку. На боці моделі можна також попросити її спершу повідомити довжину масиву, перш ніж відповідати.