TOON は JSON を LLM 入力用に再エンコードする：4つの形式とタビュラ適格率で判断する

JSON の構造そのものがトークンを食う、という問題設定

LLM のプロンプトに JSON をそのまま埋め込むと、中括弧、引用符、キー名の繰り返しにトークンが割かれる。同じキーが10件の配列で10回現れるのは、データとしては冗長でしかない。TOON はこの冗長性を削るために、JSON データモデル（オブジェクト、配列、プリミティブ）をそのまま保った別のテキスト表現を用意する。README はこれを「翻訳レイヤー」と表現していて、プログラム側では JSON を使い、LLM への入力時に TOON へエンコードする、という使い方を想定している。対象読者は、LLM に構造化データを渡すパイプラインを持ち、トークン課金かコンテキスト長のどちらかに悩んでいるエンジニアだ。逆に、LLM を経由しないデータ交換の用途は想定されていない。

4つの形式をデータの形から自動選択する

TOON の実体は、値の形に応じて選ばれる4つの描画形式だと README は説明する。第一がインライン形式で、alerts[2]: frost,wind のようにプリミティブ配列をヘッダ行に並べる。第二がタビュラ形式で、forecast[3]{day,temp{min,max},condition,rainChance}: とフィールド一覧を一度だけ宣言し、以降は1行1要素で流す。ヘッダ内の temp{min,max} は入れ子フィールドグループと呼ばれ、均一な入れ子オブジェクトを行を平坦に保ったままヘッダへ畳み込む。第三がキー付きタビュラで、environments[2:]{region,replicas,debug}: のように長さの後のコロンで印を付け、各行が自分のキー（production: など）を運ぶ。config マップやフィーチャーフラグ、ID 別レコードがこの形に落ちる。第四がリスト形式で、上記のどれにも当てはまらない混在型や非均一オブジェクトは - 項目1つずつ、空オブジェクトは裸の - で表される。この4形式のどれに落ちるかが、後述する削減率をほぼ決める。

入れ子の深さと均一性が損益分岐点になる

README の「When Not to Use TOON」は率直で、向かない条件を4つ挙げている。第一に、構造が深く入れ子であるか非均一で、タビュラ適格率がほぼ 0% の場合、コンパクトな JSON の方が小さくなる。第二に、配列が半均一（適格率およそ 40〜60%）の場合、削減幅が縮むので、すでに JSON で動いているパイプラインなら JSON に留まるべきだとしている。第三に、データが純粋に表形式なら CSV の方が小さい。TOON が持つ 5〜10% 程度のオーバーヘッドは、宣言された長さ、フィールド一覧、区切り文字のスコープを買うためのもので、サイズではなく信頼性のトレードだと README 自身が書いている。第四に、レイテンシが支配的な場合で、特にローカルや量子化モデルでは、トークン数が多いコンパクト JSON の方が速く処理されることがあるとし、TTFT と総時間は自分の環境で測るよう求めている。この最後の点は README が数値を出していない領域なので、採用前に自前で計測するしかない。

インストールと --stats による事前見積もり

npm パッケージは @toon-format/toon、CLI は @toon-format/cli として公開されている。README が最初に示すのはインストール不要の試し方で、cat data.json | npx @toon-format/cli --stats を実行すると TOON 本体と変換の削減量が並んで出力される。天気予報の例では「Token estimates: ~117 (JSON) → ~66 (TOON)」「Saved ~51 tokens (-43.6%)」という表示になる、と README は記載している。トークン数の見積もりは推定値であり、実際のトークナイザ次第でずれる点は押さえておきたい。判断の順序としては、まず自分の代表的なデータでこのコマンドを走らせ、削減率と、出力がタビュラ形式になっているかを目視するのが最短になる。なお、この記事の執筆時点で当方が実際にコマンドを実行して出力を確認したわけではなく、上記は README の記載に基づく。

[N] と {fields} はトークン削減より検証のための仕掛け

タビュラ形式のヘッダにある [N] は行数、{fields} は列幅を宣言する。README はこれを LLM 向けのガードレールと呼び、切り詰められたり壊れたりしたモデル出力がそのまま通ってしまうのを防ぐと説明している。ここは TOON の性格を理解する上で重要で、単なる圧縮形式ではなく、モデルが生成した構造化データを検証可能にする方向に設計が寄っている。CSV との比較でもこの点が効く。CSV は同じデータをより小さく表現できるが、行数も列名も宣言しないため、途中で切れた出力と正常な出力を区別する手がかりが乏しい。TOON が CSV より 5〜10% 大きいのは、この宣言と区切り文字のスコープを確保するためだと README は位置づけている。圧縮率だけを見て CSV を選ぶと、この検証可能性を手放すことになる。

ベンチマークは2トラックに分かれ、CSV は片方にしか出ない

README のベンチマークは2つのトラックで構成される。Mixed-Structure Track は入れ子や半均一なデータセットを対象に TOON、JSON、YAML、XML を比較し、CSV は除外される。これらの構造を損失なく表現できないためだ。Flat-Only Track は平坦で完全にタビュラ適格なデータセットを対象にし、ここで初めて CSV が公平な比較相手として登場する。つまり CSV が TOON より有利なのは平坦なデータの場面だけで、それ以外の比較には CSV は参加していない。README はキー機能の箇所で「JSON の検索精度に匹敵しつつ 42.6% 少ないトークン」と述べているが、この数値がどのトラックのどのデータセットに対応するかは、提供された本文からは特定できない。導入判断に使うなら、抽象的な平均値ではなく自分のデータでの --stats の結果を根拠にすべきだ。

仕様と実装が分離していることの意味

リポジトリ構成で目を引くのは、仕様が toon-format/spec という別リポジトリに切り出されている点だ。README のバッジは「SPEC v4.1」を示し、本体は v4.1.1 を最新リリースとしている。公式実装に加えて多数のコミュニティポートが同一仕様と同じ適合テストスイートを対象にしていると README は説明する。TypeScript SDK と CLI だけを使う分にはこの分離は意識しなくてよいが、他言語から TOON を生成・解読する場合、実装ごとの仕様追従度が問題になる。README 自身も「形式は安定しているが、進行中のアイデアでもある」と述べており、仕様リポジトリへのコントリビューションを呼びかけている。プロダクションで使うなら、依存する仕様バージョンを固定し、適合テストが自分の用途をカバーしているかを確認する作業が要る。

ライセンスと、採用前に確認すべきこと

ライセンスは MIT で、リポジトリの LICENSE ファイルに置かれている。MIT は商用利用や改変、再配布を許容する寛容なライセンスだが、無保証である点は他の MIT プロジェクトと同じで、生成された TOON の正しさを保証するものではない。法的な判断はここでは扱わない。確認すべきは技術的な点で、第一に自分のデータでの削減率、第二に出力がタビュラ形式に落ちているか、第三にタビュラ適格率が 40〜60% の帯に入っていないか、第四に使用モデルでのレイテンシが許容範囲か、だ。特に第四は README が数値を示していない唯一の領域で、TTFT と総時間を自分の環境で測る以外に方法がない。逆に、均一なオブジェクト配列を大量に LLM へ流しているパイプラインなら、変換段を1つ挟むだけでトークン課金が下がる可能性がある。判断は README の平均値ではなく、手元の data.json で --stats を1回走らせた結果で下すのが妥当だ。

編集部の結論

均一なオブジェクト配列を LLM に読ませる用途、たとえば設定マップや ID 別レコードの一括投入なら、TOON は JSON のトークンを削りつつ [N] と {fields} で行数と列幅を明示できるので検討に値する。逆に、入れ子が深いデータやタビュラ適格率が 40〜60% 程度の中途半端な配列、純粋に表形式で CSV が使えるデータ、レイテンシが支配的なローカル・量子化モデルの推論では採用しない方がよい。導入前に必ず自分のデータで npx @toon-format/cli --stats を実行し、削減率と、生成された TOON がタビュラ形式に落ちているかを確認する。削減率が数%に留まるなら、パイプラインに変換段を1つ増やす価値はない。

公式情報源

1. License: MIT
2. Project website
3. README
4. Releases
5. toon-format/toon on GitHub