JSON・YAML・XML、実際にどう使い分けるべきか

JSON、YAML、XMLはいずれも、ネストしたオブジェクト、リスト、キーと値のペア、単純な値といった、基本的には同じデータを表現できます。だからこそ、その中からどれを選ぶかは、じっくり検討した末の判断というより、習慣やフレームワークの既定値に左右されがちです。しかしこの3つは異なる時代に、異なる主要用途のために設計されており、その当時の設計目標は今も実務上の本物の違いとして表れています。手で編集していて心地よいのはどれか、機械が厳密に検証できるのはどれか、深くネストしても読みにくくならないのはどれか、そしてどのツール群がすでにその形式を前提にしているか、といった違いです。習慣ではなくこうした違いに基づいて選ぶことこそが、単なる慣例ではなく本当に良い形式選びを実現します。

JSONはJavaScriptのオブジェクトリテラルの構文からそのまま取り出されたものであり、その出自こそがJSONがWeb APIのデータ交換形式として既定の地位を得た理由です。あらゆるJavaScript環境がライブラリなしにネイティブで解析でき、その文法は他のほぼどんな言語でも一日あれば正しく実装できるほど小さく、コメント不可・末尾カンマ不可・キーは二重引用符必須といった厳格なルールのおかげで、JSONパーサーが解決すべき曖昧さはごくわずかです。これによりJSONは解析が速く、正しく生成するのも容易になっています。しかし、この同じ厳格さこそが、人が直接手で編集することを想定した用途におけるJSONの最大の弱点でもあります。コメントが使えないため設定ファイルに説明のメモを残す方法がなく、構造が3〜4階層より深くネストすると、句読点だらけの中括弧構文を目で追うのが本当に困難になります。

これが、APIのレスポンス、サービス間のデータ交換、主にコードによって生成・消費されるもの — つまり人が読んで編集するというより機械同士がやり取りするもの — においてJSONが優位に立つ理由です。一方で、人が手で管理することを前提とした設定ファイルにとっては、いくぶん扱いにくい選択であり続けています。

YAMLはJSONとは正反対の優先順位で設計されました。人間にとっての可読性と手編集のしやすさを重視し、その代償としてJSONよりかなり複雑な構文仕様を抱えています。ネストの表現には中括弧ではなくインデントを使い、`#`による本物のコメントに対応し、多くの一般的なケースでは引用符なしの文字列を許容します。これらすべてが相まって、きちんと整形されたYAMLファイルはコードというよりほとんどプレーンな構造化メモのように読めます。だからこそYAMLは、CI/CDパイプラインの定義、コンテナオーケストレーションのマニフェスト、人が実際に直接読んで書き換える必要があるアプリケーション設定など、開発ツール群の広い範囲で設定ファイルの標準になりました。トレードオフとして、YAMLが構造を空白文字に依存していることは、正しく手編集するうえで本当に脆さを生みます。インデントを一箇所間違えただけで、明らかなエラーを出すことなく、どのブロックに属するかが静かに変わってしまうのです。また、より許容度が高く機能豊富な仕様であるがゆえに、異なるYAMLライブラリ間で実際に文書化された解析の食い違いが長年にわたって発生してきました。これは、はるかに厳格なJSONの文法ではそもそも生まれる余地のない曖昧さです。

XMLはJSONやYAMLより前に生まれた形式で、また別の優先順位のために設計されました。厳格で検証可能な文書構造と、それを取り巻く成熟した標準のエコシステムです。アプリケーションコードが触れる前に文書の構造を検証できるスキーマ言語、文書内を検索するためのXPath、異なる出所の語彙を名前の衝突なく組み合わせるための名前空間などです。このツールの厚みは、エンタープライズや文書中心の文脈では今もJSONやYAMLに真似できません。厳格なデータ交換要件を持つ業界、標準化された文書形式、それを中心に構築された長寿命のレガシーシステムが今もXMLに頼っているのは、単なる惰性ではなく、まさにこの検証とツールの成熟度ゆえです。よく知られたトレードオフは冗長さです。同じネストされたデータをXMLで表現すると、たいてい同等のJSONよりも目に見えて多くの文字数が必要になります。あらゆる値に開始タグと終了タグが必要で、句読点一文字では済まないからです。これが、Webサービスが成熟し、ペイロードサイズと解析の単純さが文書スタイルの検証よりも優先されるようになるにつれて、XMLがAPIの標準形式という座をJSONに譲った主な理由です。

APIのリクエストやレスポンスの本体には、今日ではほぼ常にJSONが正しい既定の選択です。ほとんどのクライアントライブラリ、ほとんどのドキュメンテーションツール、そして統合の相手側にいるほとんどの開発者が、摩擦なく期待するのがJSONだからです。CIパイプライン、アプリケーション設定、Infrastructure as Codeの定義など、人が定期的に読んで手編集する設定ファイルには、YAMLのコメントとすっきりしたネストが本当に価値を発揮します。ただし、その周りのツール群が構文を注意深く検証していることが条件で、そこがまさにYAMLの空白依存の脆さが最も痛手になる部分だからです。厳格なスキーマ検証が本当に必要な文書中心の形式、組み合わせた語彙にまたがる名前空間の管理、あるいは既存のXMLベースのエンタープライズシステムとの統合が必要な場合には、XMLの冗長さは、他の2つが完全には再現できないツールの成熟度に対する妥当な対価です。プロジェクトに本当に役立つ形式選びとは、そのファイルを最も頻繁に読み書きするのが誰か、あるいは何かに合わせたものであり、そのときたまたま流行っている既定値に合わせたものではありません。