TOON フォーマットガイド:LLM に渡す前に JSON を軽くする
要点:同型配列を LLM に JSON で渡すと、繰り返されるキー名と括弧がトークンを消費します。TOON はインデントのオブジェクトと表形式配列で構造を一度だけ宣言し、データを行単位で並べます。公式ベンチマークでは約 40% 少ないトークンでより高い解析精度を達成。構文の読み方、節約が効く条件、変換すべきでないケース、encode と decode の組み込み方を解説します。

JSON の構文オーバーヘッドは機械間転送では無視できるものですが、トークン課金される LLM の入力側では実際の費用になります。同じ同型配列でもキー名が何十回も繰り返され、括弧や引用符が一つひとつトークンを消費します。TOON の発想は新しいデータモデルの発明ではなく、JSON データモデルをより安い記法で書き直すことです。
TOON とは:JSON の別エンコーディングであり、競合ではない
TOON(Token-Oriented Object Notation)は 2025 年に登場したオープンフォーマットで、公式の位置づけは一言でいえば JSON データモデルのコンパクトで可逆・人間可読なエンコーディングです。新しい型は一切導入しません。オブジェクト、配列、文字列、数値、真偽値、null はすべて JSON と一対一に対応し、decode(encode(x)) は元データと厳密に一致します(Date や NaN など JSON 外の型は事前に正規化が必要)。ラウンドトリップは可逆かつ決定的で、同じ入力は常に同じ出力を生みます。この決定性は、再現可能なプロンプト構築に重要です。
エンコード対象が JSON データモデルそのものなので、TOON の正しい使い方は境界フォーマットとしてです。アプリ内部では従来どおり JSON でビジネスロジックを回し、プロンプトにデータを入れる直前に一度だけ TOON へ変換し、モデルの応答を受け取ったら JSON に戻して処理します。公式ドキュメントはこれを "translation layer"(翻訳層)と呼びます。拡張子の慣例は .toon、HTTP 転送の暫定メディアタイプは text/toon(UTF-8)です。
検索時の注意:コンピュータグラフィックスの Toon Shader(トゥーンレンダリング)とは無関係です。単語が同じだけの別物です。
なぜ LLM の入力側で JSON は高くつくのか
注文リスト、ユーザー一覧、ログ要約を JSON 配列で表現すると、トークンは三つの部分に消えます。
- 繰り返されるキー名。50 件の注文レコードは
"id"、"amount"、"status"をそれぞれ 50 回書きます。データが倍になればキー名のオーバーヘッドも倍です。 - 構造上の句読点。波括弧、角括弧、コロン、カンマはすべてトークンを消費し、ネストが深いほど密度が上がります。
- 引用符。ほぼすべてのキーと文字列値が二重引用符で囲まれます。
この三つが重なると、トークン単価の API 費用が直接増え、長い入力はコンテキスト窓の上限に早く達し、超長入力ではモデルがフィールドを取りこぼしたり誤対応させたりする確率も上がります。TOON 公式トップページのベンチマークでは、混合構造のテストセットで 4 モデル平均 トークン約 40% 減、解析精度は JSON の 70% から 74% へ上昇。つまりこの領域では省トークンと精度はトレードオフではなく、締まった構造のほうが境界を見誤りにくいのです。
構文解説:インデントオブジェクト+表形式配列
同じ天気予報データの三つの表現を見ます。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})はヘッダーへ折りたたまれ、データ行はフラットのまま保たれます。引用符の規則は最小引用:文字列が区切り文字や特殊文字を含む、または数値と誤読される場合にのみ引用符を付けます。これが「圧縮 JSON」よりトークンを削れる理由の一つです。YAML との決定的な違いは TOON に明示的な長さ宣言とフィールドヘッダーがあり機械検証できること、CSV との違いはネストと型を保持することです。
[N] と {fields}:モデルに渡す構造のガードレール
[3] と {day,...} は単なるトークン削減手段ではなく、モデルに渡す検証可能な契約でもあります。
- 配列長により、モデルは「データセットは何件か」に直接答えられ、行数の不一致から切り詰め(truncate)を即座に検出できます。
- フィールドヘッダーは名前を一度だけ宣言し、モデルは位置で値を整列します。各行でキー対応を推測し直すことによる誤り面が減ります。
これは事後の救済とは正反対の発想です。JSON 修復ツール(修復パイプラインの記事参照)はモデルが壊れた JSON を出力した後で救い出しますが、TOON の長さとフィールド宣言は入力側で壊れたデータが生まれる確率を下げます。両方をやれば、途中の解析失敗率が下がります。
TOON を使うべきでないとき
公式の「When Not to Use TOON」は率直で、四つのケースをそのまま覚えて問題ありません。
| ケース | 変換しない理由 | より良い選択 |
|---|---|---|
| 深いネスト・不均一な構造 | 表形式適合率≈0%。コンパクト JSON のほうが省ける | コンパクト JSON |
| 半同型の配列 | フィールドが揃わず削減幅がほぼ消える | JSON パイプライン維持 |
| 純粋なフラット表 | TOON は CSV より 5–10% の構造オーバーヘッド | 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 の実装も存在します。採用前に公式 spec リポジトリの実装リストを確認し、使う構文機能がカバーされているかを確かめてください。本番投入前にはラウンドトリップ検証を行います。decode(encode(元データ)) が深い一致でなければ、実装かデータのどちらかに問題があります。
既存の JSON ツールチェーンとの連携
TOON は既存の JSON 処理を一切変えず、境界変換を一つ追加するだけです。推奨の順序は次のとおりです。
- まず JSON 自体をきれいにする。壊れた JSON からは壊れた TOON しか生まれません。構文検証と修復は JSON 修復ガイド の解析チェーンに任せます。
- データ形状を確認する。配列内のオブジェクトはフィールドが揃っていますか。揃っていなければ先に正規化するか、変換する価値がないと判断します。
- 変換してスポットチェックする。変換後、データ行を一つ取り出して元の JSON と比較し、フィールド整列がずれていないか確認します。
- 利益を見積もる。同型リストなら JSONL ファイルハンドブック の行単位の考え方をストリーミング変換に応用できます。サイズとコストの関係は JSON Minify と Gzip の実際の関係 と同じ教訓です。測ってから変える、が安上がりです。
TOON は JSON を置き換えるのか?
いいえ。TOON がエンコードするのは JSON データモデルそのものであり、役割はプロンプト境界の表現層です。プログラム間の保存と交換は引き続き JSON の領域です。「モデルに渡す」区間だけ TOON を使い、残りのチェーンはそのままにします。
TOON と YAML・CSV の関係は?
オブジェクト部分は YAML に似ており(波括弧の代わりにインデント)、同型配列は CSV に似ています(ヘッダーを一度宣言し行を流す)。ただし TOON には YAML にない明示的な長さ宣言があり、CSV にないネストと型の保持もあります。両者の中間に立ち、機械検証可能な構造ガードレールを加えたものです。
TOON から JSON への変換でデータは失われるか?
失われません。オブジェクト、配列、文字列、数値、真偽値、null はすべて一対一に対応し、decode(encode(x)) は厳密に一致します。唯一の注意点は Date や NaN など JSON 外の型を先に正規化することです。そうしないと一致はラウンドトリップ後になります。
変換結果の TOON が正しいか検証するには?
二つの方法があります。一つはラウンドトリップ検証、encode してから decode した結果が元データと深い一致すること。もう一つはヘッダーの目視確認です。[N] の数字はデータ行数と等しく、{fields} の各フィールドは各行のカンマ区切り値と一対一に対応していなければなりません。モデル側では、答える前にまず配列長を報告させるようプロンプトで要求するのも有効です。