YAMLとTOONはどちらも「JSONよりも読みやすい」と説明されています — そしてその説明は 技術的には両方に当てはまりますが、それ自体は意味をなしません。本当の問いかけは：誰にとっての読みやすさか、そして何の目的のためか、です。YAMLは人間による編集に最適化されています：コメント、アンカー、複数行の文字列、開発者が設定について考える方法を反映したインデント。TOONは機械処理に最適化されています：最小限のトークン、曖昧さなし、人間の快適さだけのために存在する構文なし。これらは異なる用途です。それらを混同すると、LLMプロンプトでYAMLを使用することになり — JSONより悪い — そして誰も手で編集したくないKubernetesマニフェストにTOONを使うことになります。この記事は境界線を明確に引きます。

YAMLを2文で

YAMLは設定ファイル、CI/CDパイプライン、そして開発者が手で読み書き保守する構造化ドキュメントのために 設計された、人に優しいデータシリアライゼーション形式です。その定義的な特徴 — インラインコメント、アンカー/エイリアスのDRYメカニクス、複数行の文字列リテラル、インデントベースの構造 — はすべて、機械ではなく人間にとって快適な形式にするために存在します。

標準的なユースケースはGitHub Actionsワークフロー、Kubernetesマニフェスト、Docker Composeファイル、そしてコードと一緒に配布されるアプリケーション設定です。人間がファイルを開いて編集することが期待される場合、YAMLは強力な選択肢です。YAML 1.2仕様はYAML 1.1を悩ませた多くのエッジケースを正式化しました — 最も悪名高いのはノルウェー問題で、国コードNOがYAML 1.1パーサーでブール値のfalseとして解析されていました。YAML 1.2を対象とする最新のパーサーはこれを正しく処理しますが、YAMLの見た目の単純さが実際のパーサーの複雑さを隠していることを思い出させる有用なリマインダーです。

  • コメント。 # これはコメントです — YAMLはインラインコメントとフルラインコメントをサポートしています。これだけで、人間が保守する設定には正しい選択です。
  • アンカーとエイリアス。 &anchorでブロックを一度定義し、*aliasでどこでも再利用します。DRYなKubernetes設定やマルチ環境CIパイプラインに必須です。
  • 複数行の文字列。 リテラル(|)とフォールデッド(>)のブロックスカラーを使用して、シェルスクリプト、SQLクエリ、または証明書データをYAMLファイル内にきれいに埋め込むことができます。
  • 読みやすいインデント。 構造は空白で定義され、開発者がネストした設定階層について考える方法に自然にマッピングされます。
  • 弱点。 インデント感度は、ずれたスペースが解析エラーになることを意味します。タブ文字は禁止されています。YAML 1.1のブール強制変換（ノルウェー問題、yes/no、on/off）は実際の本番バグを引き起こしました。オブジェクトの配列として表現された表形式データは、JSONよりもさらに冗長です。

TOONを2文で

TOONは、すべてのトークンがコストを伴いコンテキストウィンドウスペースが有限である大規模言語モデルとの間で構造化データを受け渡すために設計されたコンパクトなシリアライゼーション形式です。その主要なイノベーションは表形式記法です：すべてのレコードが同じフィールドを共有するデータセットの場合、キーはヘッダーで一度だけ宣言され、後続のすべての行から省略されます — これはJSONとYAMLが行うことと正反対です。

TOONは設定形式ではなく、そのために設計されたものでもありません。コメント構文はありません。アンカーもありません。バイナリファイルを手で編集したくないのと同様に、500行のTOONデータセットを手で編集したいとは思わないでしょう。TOONが提供するのは、JSONと同じ情報を大幅に少ないトークンでエンコードする形式です — そして少ないトークンはAPI コストの低下、プロンプトごとのより大きな実効データセット、コンテキストウィンドウ制限への圧力の軽減を意味します。OpenAIトークナイザーは実際にこれを確認する最速の方法です：同じデータセットを両方の形式で貼り付けて比較してください。

  • 表形式記法。 name[count]{col1,col2,...}:の後に1行1行の値が続きます。キーは行数に関係なく正確に1回だけ表示されます。
  • オブジェクト記法。 {key:value,key2:value2} — キーに引用符なし、余分な空白なし。
  • 曖昧さのない解析。 ブール強制変換なし、インデント感度なし、仕様バージョンの乖離なし。
  • コメント構文なし。 TOONにはインラインコメントのメカニズムがありません — 設計上の選択です。これはデータ形式であり、ドキュメント形式ではありません。
  • 弱点。 ニッチなツール、人間による編集のストーリーなし、開発者が直接開いて編集するファイルには適していません。

並べて比較：各形式が得意とするデータ

最も正直な比較は、各形式が実際に得意とすることをやっている様子を示します — 一方が明らかに間違ったツールである直接対決を強制するのではなく。

まず、Kubernetesのデプロイメントマニフェスト。これはYAMLのホームフィールドです：コメント、共有値のアンカー、Kubernetesオブジェクトの論理的階層にマッピングされる深いネストを持つ、人間が保守する設定ファイルです：

yaml
# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  namespace: production
  labels:
    app: payments-service
    version: "2.4.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-service
  template:
    metadata:
      labels:
        app: payments-service
    spec:
      containers:
        - name: payments-service
          image: registry.example.com/payments-service:2.4.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              valueFrom:
                secretKeyRef:
                  name: payments-db-secret
                  key: host
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

これをTOONで書くことは無意味です — 表形式データではなく、人間によって編集され、非明白な値を説明するコメントから恩恵を受けます。ここではYAMLが正しいツールであり、競争の余地はありません。

今度は同じデータをTOONのホームフィールドで：分析のためにLLMに渡されるユーザーデータセット。これがTOONの表形式記法が活躍する場所です：

text
users[12]{id,email,plan,mrr,country,signupDate,churned}:
  1001,[email protected],pro,99.00,US,2024-01-15,false
  1002,[email protected],starter,19.00,GB,2024-02-03,false
  1003,[email protected],enterprise,499.00,DE,2023-11-20,false
  1004,[email protected],pro,99.00,CA,2024-03-10,true
  1005,[email protected],starter,19.00,AU,2024-01-28,false
  1006,[email protected],pro,99.00,US,2023-12-05,false
  1007,[email protected],enterprise,499.00,FR,2024-02-14,false
  1008,[email protected],starter,19.00,IN,2024-03-22,true
  1009,[email protected],pro,99.00,US,2024-01-09,false
  1010,[email protected],enterprise,499.00,JP,2023-10-31,false
  1011,[email protected],starter,19.00,BR,2024-04-01,false
  1012,[email protected],pro,99.00,US,2024-02-19,true

これをYAMLで書くと — 7つのキーを持つ12個のオブジェクトの配列 — 7つのキー名が12回繰り返されます。それは84個の値に対して84個のキー宣言です。TOONは各キーを1回だけ宣言します。

YAMLが常にTOONに勝る場面

人間が開き、読み、編集するファイルはすべてYAML（またはより単純な場合はJSON）に属します。決定的な利点はコメントとアンカーです — TOONが単純に持っていない2つの機能です。

  • CI/CDパイプライン。 GitHub Actions、GitLab CI、CircleCI — すべてYAMLネイティブ。デバッグ中にステップをコメントアウトできる能力は本当に便利です。
  • KubernetesとHelm。 すべてのマニフェスト、すべての値ファイル、すべてのチャートテンプレート。YAMLのアンカーシステムは、環境設定の繰り返しを避けるために複雑なHelmチャートで積極的に使用されています。
  • Docker Compose。 非明白なポートバインディング、ボリュームマウント、ネットワーク設定を説明するコメント付きのマルチサービス定義。
  • アプリケーション設定ファイル。 pyproject.tomlスタイルの設定、アプリケーション設定、インラインで説明コメント付きの機能フラグ。
  • 人間がPRでレビューするバージョン管理内のあらゆるファイル。 YAML設定のコメントはドキュメントの一部です。TOONはこのワークフローに全く参加できません。
アンカーに関する注意： YAMLのアンカー(&anchor)とエイリアス(*alias)は使われていませんが強力です。複数のコンテナ間で同じ環境変数を共有するKubernetes設定は、&common-envで一度定義し、*common-envでブロックを参照できます — テンプレートエンジンなしでファイルをDRYに保つことができます。TOONには同等のメカニズムがありません。

TOONが常にYAMLに勝る場面

プログラムによって生成されLLMに渡されるデータはすべてTOONに属します。YAMLはこのユースケースではJSONよりも悪いです — その重いインデント構文と繰り返されるキー名は、モデルが必要とする情報を追加することなくトークンを追加します。

  • LLMプロンプトペイロード。 分析、分類、またはエンリッチメントのためにGPT-4o、Claude、またはGeminiにデータセットを供給します。TOONの表形式記法はJSONと比べてトークン数を40〜60%削減し、YAMLと比較するとさらに差は大きくなります。
  • LLM出力指示。 TOONで応答するようにモデルに指示すると、より短く安価な出力が生成されます。LLMからのYAML出力は冗長でインデント感度が高く — 一つのずれたスペースで解析が失敗します。
  • プログラムで生成されたデータセット。 コードがデータを構築しているなら、TOONを構築すべきです。コメントや読みやすいインデントから恩恵を受ける人間の編集者はいません。
  • 大量バッチ処理パイプライン。 1日に10,000件のレコードをLLMで処理していますか？50%のトークン削減は、API請求書のその行の50%削減を意味します。
  • コンテキストウィンドウの圧力。 モデルのコンテキスト制限内により多くのデータを収めるとき、TOONは同じトークンコストでより多くの行を詰め込むことができます。

トークン数の現実

3つの形式で同じ10行のデータセットを示します。数値は概算ですが、OpenAIトークナイザーがGPT-4oのトークン化について報告する内容と一致しています。

YAMLオブジェクト配列：

yaml
- id: 1
  username: alice_chen
  plan: pro
  mrr: 99.00
  country: US
- id: 2
  username: bob_martin
  plan: starter
  mrr: 19.00
  country: GB
- id: 3
  username: carol_white
  plan: enterprise
  mrr: 499.00
  country: DE
- id: 4
  username: dan_patel
  plan: pro
  mrr: 99.00
  country: CA
- id: 5
  username: eve_torres
  plan: starter
  mrr: 19.00
  country: AU
- id: 6
  username: frank_liu
  plan: pro
  mrr: 99.00
  country: US
- id: 7
  username: grace_kim
  plan: enterprise
  mrr: 499.00
  country: FR
- id: 8
  username: henry_obi
  plan: starter
  mrr: 19.00
  country: IN
- id: 9
  username: iris_novak
  plan: pro
  mrr: 99.00
  country: US
- id: 10
  username: james_sato
  plan: enterprise
  mrr: 499.00
  country: JP

TOON表形式記法、同じデータ：

text
users[10]{id,username,plan,mrr,country}:
  1,alice_chen,pro,99.00,US
  2,bob_martin,starter,19.00,GB
  3,carol_white,enterprise,499.00,DE
  4,dan_patel,pro,99.00,CA
  5,eve_torres,starter,19.00,AU
  6,frank_liu,pro,99.00,US
  7,grace_kim,enterprise,499.00,FR
  8,henry_obi,starter,19.00,IN
  9,iris_novak,pro,99.00,US
  10,james_sato,enterprise,499.00,JP
このデータセットの概算トークン数： YAML ≈ 290トークン。JSON（等価なオブジェクト配列）≈ 230トークン。TOON ≈ 115トークン。YAMLはTOONよりも悪いだけでなく — 表形式データではJSONよりも悪いです。その理由は、インデント構文がJSONの中括弧にはないトークンを追加するためです。TOONはYAMLに対して約2.5倍、JSONに対して約2倍勝っています。OpenAIトークナイザーで確認してください。

YAMLが表形式データでJSONより悪いパフォーマンスを示す理由は構造的です：YAMLはインデントを使って1キー-値ペアあたり1行を使用するため、5フィールドのオブジェクトはリストマーカーに加えて5行かかります。JSONは少なくともオブジェクト全体を1セットの中括弧で包みます。TOONはキーの繰り返しを完全に排除します — キーは1回表示され、値は行にパックされます。節約は行数とフィールド数に比例して増加します。

コードでTOONを使う

@toon-format/toonパッケージはエンコードとデコードを処理します：

bash
npm install @toon-format/toon
ts
import { encode, decode } from '@toon-format/toon';

// Your dataset — could come from a database query, API response, anywhere
const users = [
  { id: 1001, email: '[email protected]', plan: 'pro',        mrr: 99.00,  country: 'US' },
  { id: 1002, email: '[email protected]',   plan: 'starter',    mrr: 19.00,  country: 'GB' },
  { id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
  // ...more rows
];

// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
//   1001,[email protected],pro,99.00,US
//   1002,[email protected],starter,19.00,GB
//   1003,[email protected],enterprise,499.00,DE

const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.

Dataset:
${toonPayload}`;

// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }

判断ガイド

YAMLとTOONの選択は実際にはほとんど曖昧ではありません：

  • YAMLを使う場合：人間がファイルを読むか編集する場合 — CI/CDパイプライン、Kubernetesマニフェスト、Docker Compose、アプリケーション設定、Ansibleプレイブック。
  • YAMLを使う場合：非明白な値を説明するためのインラインコメントが必要な場合。
  • YAMLを使う場合：複雑な設定をDRYに保つためのアンカーとエイリアスが必要な場合。
  • YAMLを使う場合：慣例によりYAMLを期待するツールで作業している場合（Helm、GitHub Actions、k8s kubectl apply）。
  • TOONを使う場合：データがLLMプロンプトに入る場合 — 特に複数行の表形式データ。
  • TOONを使う場合：LLMに構造化データを返させ、より短く安価な出力が欲しい場合。
  • TOONを使う場合：トークン数が重要な場合 — 大量パイプライン、長いデータセット、コンテキストウィンドウの圧力。
  • TOONを使う場合：データがプログラムで生成され、人間が直接編集しない場合。
  • JSON（YAMLでもTOONでもなく）を使う場合：REST APIを構築する、データベースにデータを保存する、またはJSONを期待するサードパーティのツールと統合する場合。

まとめ

YAMLとTOONはスタック内で完全に異なる位置を占めています。YAMLはコードの隣のリポジトリに属します — 設定ファイル、パイプライン定義、インフラマニフェスト。TOONはアプリケーションとLLM APIの境界に属し、送信前に構造化データを最もトークン効率の良い表現に変換し、モデルの応答を帰り道で戻します。これらの用途には意味のある重複がありません。だから問いかけは「どちらが優れているか」ではなく「ここにはどちらが属するか」なのです。

TOONで作業している場合、TOONフォーマッターとTOONバリデーターはTOON文字列を検査・検証する最速の方法です。JSON to TOONコンバーターは既存のJSONペイロードをLLM用のTOONに変換し、TOON to JSONコンバーターはモデルがTOONで応答し下流のシステムがJSONを期待する場合の帰り道を処理します。また、YAMLに関するWikipediaの記事はフォーマットの簡潔な歴史と既知のエッジケースのまとめを提供しています。

← All TOON articles Browse all categories →