JSON vs YAML vs TOML:設定ファイル形式を正直に比較する

すべての開発者は設定形式についての意見を積み上げる — たいてい YAML のインデントの傷を通して得たものだ。支配的な 3 形式が共存するのには現実の理由があり、その間を移動することは日々の仕事だ — CI パイプラインは YAML を欲しがり、アプリの設定は TOML を欲しがり、API は JSON を欲しがる。ここに正直な比較と、変換ボタンを押す前に知っておくべき罠がある。

一行バージョン

• JSON(2001) — 万能のデータ交換形式。マシンファースト、冗長、コメントゼロ。
• YAML(2001) — 人間可読のヘビー級。インデント駆動、機能豊富、時折危険。
• TOML(2013) — 威厳のある設定ファイル形式。明示的で曖昧さなし、人間が手で維持するファイルのために作られた。

JSON:交換の背骨

JSON が勝ったのは退屈だからだ:1 ページの仕様、あらゆる言語のパーサー、プログラミングのデータ型に直接マッピングする構造。だから API、パッケージレジストリ、ブラウザツールの言語だ — マシンがマシンと話すあらゆる場所で。

限界は人間的なものだ。コメントがない(永遠の不満 — "//" キーから死んだ設定エントリまで、すべての workaround は傷だ)、引用符と波括弧は必須、複数行文字列はすぐ醜くなる。JSON はプログラムが書くために最適化されていて、200 行の package-lock.json を手で編集させられると即座に気づく。

敬意を払う価値のある細部が一つ:JSON の数値モデルだ。2^53 を超える大きな整数は JavaScript ツールチェーンで精度を失う(外部システムの ID が静かに破壊される)、そして重複キーは技術的には未定義の挙動だ — ほとんどのパーサーは最後のものを残し、変換時にデータが静かに隠されうる。

YAML:強力で、時折危険

YAML の提案は可読性だ:インデントによるネスト構造、ダッシュによるリスト、最小限の句読点。Kubernetes、GitHub Actions、すべての CI システムの母国語だ — だから「YAML を JSON に変換」は通常「CI ファイルをマシン可読にする」を意味する。

だが YAML は長い機能の尾を持つスーパーセットで、その尾が噛む:

1. ノルウェー問題。country: NO は boolean の false にパースされる。version: 1.20 は数値 1.2 にパースされ、ソフトウェアのバージョンが静かに壊れる。引用符なしのスカラは型推論を受け、いずれ誰もが驚く。
2. アンカーとエイリアス(&anchor、*alias)は 1 ブロックが別を参照できるようにする — 大きなパイプラインの重複除去には素晴らしい、そしてそれを展開しないコンバーターは構造的に間違った JSON を生む。
3. 複数ドキュメントファイル(--- で文書を分ける)と複数行文字列(| / > のファミリー)は、素朴なコンバーターが平らにする意味論を運ぶ。
4. インデントこそが構造だ — チャットからブロックを貼り付けると、ネストが静かに壊れたり合流したりしうる、しかもその結果は有効な YAML としてパースされる。これがすべての YAML ユーザーが持つ傷だ。

まともなパーサーで扱われる YAML は、そのニッチで優秀だ:人間が維持する大きなオーケストレーションファイル。正規表現で扱われる YAMLは、インシデントの生産方式だ。

TOML:行儀の良い設定ファイル

TOML は逆に賭けた:すべての構造を明示的にする。テーブルは [sections]、キー値は一目瞭然、日付はネイティブ型を持ち、どんなものにも書き方は一通りだけある — 型推論の驚きなし、whitespace-as-structure なし。Rust のエコシステム、Python の pyproject.toml、Cargo がそれに標準化したのは良い理由がある:3 つの異なるパーサーが読む TOML ファイルは、同じファイルだ。

コストは深さでの冗長性だ:深くネストしたデータは [a.b.c] のヘッダーの連鎖になり、巨大な繰り返し構造は反復的になる。TOML は人間が慎重に編集するファイルのために最適化されていて、任意のデータペイロードのためではない — そしてそれこそが設定の正体だ。

変換の罠

三者間の変換は損失境界の交渉であり、どの方向が「安全」かを知っていることはデバッグ時間を節約する:

• YAML → JSON は、コンバーターがアンカー/エイリアスと複数ドキュメントを正しく展開するならば、最も安全な方向だ。罠:YAML の引用符なしの文字列 on、off、yes — 型推論するコンバーターはあなたのリリースブランチ名を快く true に変える。
• JSON → YAML は構造的には無損失だ(YAML は JSON のすべてを表現できる — JSON は技術的に有効な YAML)、だが再パース時に YAML の型推論の癖を獲得しうる:数字、バージョン、boolean 語に見えるものにはすべて引用符を。
• JSON → TOML は TOML の厳格な型付けにぶつかる:JSON の混合型配列([1, "a", true])は TOML では無効だ — コンバーターは誠実にエラーを出すか、値を文字列化しなければならない(それは下流で型を破壊する)。深くネストした JSON も、扱いにくいヘッダーの連鎖として着地する。
• TOML → JSON はきれいだ — TOML の明示性が直接マッピングする;唯一の細部は TOML のネイティブ datetime 型で、JSON は文字列として表現する(ISO 形式を保つか、意味論を失う)。

当サイトのコンバーター(JSON から YAML、YAML から JSON、JSON から TOML、そして JSON、YAML、TOML の形式ガイド)は、本物のパーサーでパースする — 決して正規表現ではない — そしてすべてブラウザ内ローカルで動く。ここでは、通常よりそれが重要だ:設定ファイルは日常的にインフラのトポロジー、内部ホスト名、シークレットを含む。「Kubernetes の YAML を貼ってください」型のサイトは漏えいベクターだ;あなたのブラウザ内での変換は違う。

どれを使うべきか?

• API やマシン対マシンの何かを構築 → JSON、議論の余地なし。
• CI/CD、Kubernetes、DevOps エコシステムの何か → YAML — エコシステムがあなたの代わりに決めた。
• 人間が手で維持するアプリ設定(Rust、Python、Go プロジェクト)→ TOML。
• それらの間の変換 → 本物のパーサーを使い、曖昧なスカラには引用符を、そして反対側で型を再検証する。

FAQ

YAML は有効な JSON か?

いいえ — だが逆は真だ:すべての JSON ドキュメントは有効な YAML だ(JSON は初期のバージョンでは YAML のサブセットで、モダンな YAML パーサーは今もパースできる)。この一方通行が、「JSON → YAML はそのまま動く、逆方向には本物のパーサーが要る」の理由だ。

変換するとバージョン番号が変わるのはなぜ?

YAML は引用符なしのスカラに型を推論する:1.20 は float の 1.2 になり、1.0 は 1 になりうる。源流でバージョン文字列に引用符を付け(version: "1.20")、または元のスカラテキストを保持するコンバーターを使う。

TOML は JSON のすべてを表現できる?

できない。TOML は混合型配列を禁じ、JSON の任意のネストの深さは合法だが [a.b.c.d] のヘッダー連鎖として痛々しい。コンバーターはそのような構造を拒絶するか型を強制する — きれいなマッピングを仮定せず、コンバーターが何をしたか読むこと。

設定形式にコメントはなぜ必要なの?

設定は決断をエンコードするからだ(「このタイムアウトが 30 秒なのは上流の p99 のせい」)、そしてコンテキストのない決断は、次の人が「修正」する。JSON のコメントなし設計は最も恨まれる機能だ;YAML と TOML は両方ともファーストクラスのコメントを持つ。