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} должны выравниваться один к одному со значениями через запятую в каждой строке. На стороне модели можно также попросить её сначала сообщить длину массива, прежде чем отвечать.