JSON vs YAML vs TOML 設定ファイル形式の使い分け

3形式の生まれと位置づけ

JSON（2001年〜）: ダグラス・クロックフォード氏がJavaScriptオブジェクトの記法から派生させた形式。RFC 8259とECMA-404で標準化。Web APIのデータ交換でデファクトスタンダード。

YAML（2001年〜）: YAMLは「YAML Ain't Markup Language」の略。インデント（字下げ）でネストを表現し、人間に読みやすいことを最優先に設計。設定ファイル・CI/CD定義に普及。

TOML（2013年〜）: GitHub共同創業者のTom Preston-Werner氏が「Tom's Obvious Minimal Language」として作成。INIファイルのような見た目で、明示的な型システムを持つ。RustのCargo・Pythonのpyproject.tomlで採用。

同じデータを3形式で書き比べ

「ユーザー田中（30歳）が東京と大阪に住所を持つ」というデータを、3形式で書くと次のようになります。

JSON：

YAML：

TOML：

人間が手で書くなら YAML > TOML > JSON の順で楽。プログラムから出力するなら JSON が最も単純、というのが直感的な印象です。

機能比較表

実際の採用事例

JSON採用例: package.json (npm)、tsconfig.json (TypeScript)、composer.json (PHP)、appsettings.json (.NET)、Web APIのリクエスト/レスポンス、JSON Schema、JSON-LD、JWT、AWSのIAMポリシー。

YAML採用例: GitHub Actions ワークフロー、Kubernetes マニフェスト、Docker Compose、Ansible Playbook、CircleCI、GitLab CI、Helm Chart、OpenAPI/Swagger 仕様書、Hugo/Jekyllのフロントマター。

TOML採用例: Cargo.toml (Rust)、pyproject.toml (Python)、Hugoのhugo.toml、Pythonのblack設定、Cloudflare wrangler.toml（旧形式）、PoetryのPython依存管理。

見ての通り「データ交換にはJSON、人間が書く設定にはYAML/TOML」という棲み分けが大体できています。

それぞれの落とし穴

JSONの罠: コメント不可・末尾カンマ不可。設定ファイルとして使うと「ここは何のため？」がコメントで書けず、説明用キー（_comment等）を別途追加する苦肉の策が必要。

YAMLの罠: インデント1つずれるだけで構造が変わる。文字列「yes」「no」「on」「off」がBoolean型に解釈される歴史的問題（YAML 1.1）。「Norway Bug」と呼ばれる、国名コード「NO」がfalseに化ける事例も有名。

TOMLの罠: ネスト構造を表現する記法が複雑（[table]、[[array of tables]]、ドット表記）。深いネストを書くのは苦手。日付型のタイムゾーン仕様が厳密でハマる。

どれを選ぶべきか

JSONを選ぶ: API通信・データ保存・他プログラムへの受け渡し。コメントが要らず、機械が読み書きすることが主の場合。

YAMLを選ぶ: GitHub Actions・Kubernetes・Docker Composeなど、エコシステムが既にYAMLを採用している場合。人間がメインで読み書きする長い設定ファイル。

TOMLを選ぶ: Rust・Pythonのプロジェクト。比較的フラットな構造で、明示的な型と人間の読みやすさを両立したい場合。

迷ったときの基準：「自分が書くのか、機械が出すのか」「コメントを書きたいか」「インデントの整合性を保てる自信があるか」。この3つで自然と決まります。