toon-formatter

TOON v2.0 形式エキスパート

TOON（Token-Oriented Object Notation）は、均一な配列で繰り返されるキーをなくすことで、構造化データのトークン数を30〜60％削減します。

使用するタイミング

次の場合はTOONを自動的に適用します：

• 類似したオブジェクトが5個以上ある配列
• 同じ構造が繰り返されるAPIレスポンス
• データベースクエリの結果
• ログエントリ、イベント、トランザクション
• メトリクス、アナリティクス、ベンチマーク
• あらゆる表形式データ

次の場合はJSONのままにします：

• 小さな配列（5項目未満）
• 均一でない深くネストされたデータ
• 単一のオブジェクト
• 文章や指示

形式仕様

表形式（最も一般的）

均一なオブジェクトの配列の場合：

[count]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

例 - JSON（120トークン）：

[
  {"id": 1, "name": "Alice", "role": "admin", "active": true},
  {"id": 2, "name": "Bob", "role": "user", "active": true},
  {"id": 3, "name": "Carol", "role": "user", "active": false}
]

TOON（70トークン、42％削減）：

[3]{id,name,role,active}:
  1,Alice,admin,true
  2,Bob,user,true
  3,Carol,user,false

インライン形式

プリミティブ配列（10項目以下）の場合：

fieldName[count]: value1,value2,value3

例：

tags[4]: javascript,react,nodejs,api
ids[3]: 101,102,103

展開形式

複雑なネスト値の場合（1行に1つ）：

items[3]|:
  | {"complex": "object1"}
  | {"complex": "object2"}
  | {"complex": "object3"}

区切り文字

データの内容に応じて選択します：

区切り文字	構文	使用する場面
カンマ	[N]	デフォルト。値にカンマが含まれない場合
タブ	[N\t]	値にカンマが含まれる場合
パイプ	[N|]	値にカンマとタブが含まれる場合

タブ区切りの例：

[2\t]{name,description}:
  Product A	A great product, really
  Product B	Another one, even better

キーの折りたたみ（ネストされたオブジェクト）

ネストされた構造を平坦化します：

server.host: localhost
server.port: 8080
server.ssl.enabled: true
database.url: postgres://localhost/db

特殊値

値	TOONでの表現
null	~
空文字列	""
true	true
false	false

変換パターン

APIレスポンス

変換前（JSON）：

{
  "users": [
    {"id": 1, "email": "[email protected]", "plan": "pro"},
    {"id": 2, "email": "[email protected]", "plan": "free"},
    {"id": 3, "email": "[email protected]", "plan": "pro"}
  ],
  "total": 3
}

変換後（TOON）：

users[3]{id,email,plan}:
  1,[email protected],pro
  2,[email protected],free
  3,[email protected],pro
total: 3

ログエントリ

変換前（JSON）：

[
  {"ts": "2024-01-15T10:00:00Z", "level": "INFO", "msg": "Server started"},
  {"ts": "2024-01-15T10:00:01Z", "level": "DEBUG", "msg": "Connection pool ready"},
  {"ts": "2024-01-15T10:00:02Z", "level": "INFO", "msg": "Listening on :8080"}
]

変換後（TOON）：

[3]{ts,level,msg}:
  2024-01-15T10:00:00Z,INFO,Server started
  2024-01-15T10:00:01Z,DEBUG,Connection pool ready
  2024-01-15T10:00:02Z,INFO,Listening on :8080

データベースの結果

変換前（JSON）：

[
  {"product_id": 101, "name": "Widget", "price": 29.99, "stock": 150},
  {"product_id": 102, "name": "Gadget", "price": 49.99, "stock": 75},
  {"product_id": 103, "name": "Gizmo", "price": 19.99, "stock": 200}
]

変換後（TOON）：

[3]{product_id,name,price,stock}:
  101,Widget,29.99,150
  102,Gadget,49.99,75
  103,Gizmo,19.99,200

混合コンテンツ

必要に応じて形式を組み合わせます：

config.name: MyApp
config.version: 1.0.0
config.features[3]: auth,logging,metrics

endpoints[4]{method,path,auth}:
  GET,/api/users,required
  POST,/api/users,required
  GET,/api/health,none
  DELETE,/api/users/:id,admin

tags[5]: api,rest,json,http,web

判断フローチャート

Is it an array?
├─ No → Use standard JSON/key-value
└─ Yes → How many items?
    ├─ <5 → Keep as JSON (overhead not worth it)
    └─ ≥5 → Are objects uniform (≥60% same keys)?
        ├─ No → Use expanded format
        └─ Yes → Are values primitives?
            ├─ Yes, ≤10 items → Inline format
            └─ Otherwise → Tabular format

トークン削減率の目安

データの種類	一般的な削減率
ユーザーリスト	40-50%
ログエントリ	35-45%
APIレスポンス	30-50%
データベースの行	45-55%
イベントストリーム	40-60%
設定配列	25-35%

バイナリエンコーダー

コンパイル済みのZigエンコーダー（JSより20倍高速）を利用できます：

# Encode JSON to TOON
.claude/utils/toon/bin/toon encode data.json

# Decode TOON to JSON  
.claude/utils/toon/bin/toon decode data.toon

# Check if TOON recommended
.claude/utils/toon/bin/toon check data.json

# Analyze token savings
.claude/utils/toon/bin/toon analyze data.json

コマンド

コマンド	説明
/toon-encode <file>	JSONをTOONに変換
/toon-decode <file>	TOONをJSONに変換
/toon-validate <file>	TOON構文を検証
/analyze-tokens <file>	JSONとTOONのサイズを比較
/convert-to-toon <file>	変換ワークフロー全体を実行

ベストプラクティス

推奨：

• RAGパイプラインのデータペイロードにTOONを使用する
• 配列を含むツール呼び出しのレスポンスに適用する
• ベンチマーク結果やメトリクスを変換する
• 値にカンマが含まれる場合はタブ区切りを使用する

非推奨：

• 小さな配列（5項目未満）を変換する
• 均一でないデータを無理に表形式にする
• 深くネストされた構造に使用する
• 人が読むドキュメントに適用する

リソース

• 仕様: https://github.com/toon-format/spec
• ウェブサイト: https://toonformat.dev
• ローカルガイド: .claude/utils/toon/toon-guide.md