設定ファイルはどれを選ぶ？JSON / XML / YAML の特徴とおすすめの使いどころ

2025年10月30日2025年11月30日

その他

システムの設定ファイルは、一度書いたら長く使い続ける「インフラの一部」です。

ところが、JSON / XML / YAML など候補が多く、「とりあえずよく見かける形式を選ぶ」だけでは、後になって保守が大変になることもあります。

本記事では、これら3つの形式の特徴や基本ルールを整理しながら、実際にどんな場面で使い分けるとよいのかを丁寧に解説していきます。

JSON / XML / YAML とは何かを整理しよう

設定ファイルとは何か

設定ファイルとは、アプリケーションやシステムの「動作を決めるための外部ファイル」のことです。

プログラム本体を書き換えずに、ポート番号や接続先URL、機能のON/OFF、ログレベルなどを後から変更できるようにするために使われます。

多くの設定ファイルはテキスト形式で、開発者や運用担当者がエディタで直接編集できるようになっています。

このとき、どのような形式(フォーマット)で書くかとして代表的なのが JSON / XML / YAML です。

JSONとは

JSON(JavaScript Object Notation)は、もともと JavaScript のオブジェクト表記をベースにしたデータ形式です。

現在では「Web API でデータをやり取りするときの標準的な形式」として広く定着しています。

JSONは主に次のような用途で使われます。

Webブラウザとサーバー間のデータ交換
REST API / GraphQL API のレスポンス
JavaScriptや多くのプログラミング言語での設定ファイル
NoSQLデータベース(MongoDBなど)のドキュメント表現

人間にも比較的読みやすく、機械にも扱いやすいバランスの取れた形式です。

XMLとは

XML(Extensible Markup Language)は、HTMLに似た「タグ」で構造を表現するテキスト形式です。

文書構造や階層構造を厳密に表現でき、スキーマによるバリデーションなどが充実している点が特徴です。

XMLは次のような場面でよく使われてきました。

古くから存在する業務システム間のデータ連携
SOAP Webサービス
Office系ファイル(docx, xlsx など)の内部形式
Javaや.NETの設定ファイルやビルド設定ファイル(Ant, Maven など)

現在ではJSONに押されてはいるものの、大規模システムや古いシステムでは依然として現役で使われています。

YAMLとは

YAML(YAML Ain’t Markup Language)は、人間が読み書きしやすいことを最重視したデータ記述形式です。

JSONやXMLと比べて見た目がすっきりしており、設定ファイルとして人気があります。

YAMLは次のような場面で多用されています。

インフラ構成管理ツール(Ansible, Kubernetes, Docker Compose など)の設定
CI/CDツール(GitHub Actions, GitLab CI)の設定
アプリケーションフレームワーク(Ruby on Rails, Djangoの一部ツールなど)の設定

インデントで階層を表現するため、見た目はシンプルですが、そのぶん書き方を間違えると意図しない構造になるという注意点もあります。

JSONの特徴と使いどころ

JSONのメリット

JSONには、設定ファイルとしてもデータ交換形式としても有利な点が多くあります。

1. シンプルで分かりやすい構造 JSONは{} と [] でオブジェクトと配列を表現し、キーと値をペアで並べる、非常に素直な構造を持っています。

そのため、初見でもある程度直感的に理解しやすい形式です。

2. ほとんどの言語で標準サポート JavaScriptはもちろん、Python / Java / C# / Go / PHP / Ruby など、主要な言語は JSON のパーサやシリアライザを標準ライブラリかデファクトのライブラリとして提供しています。

追加のパッケージなしに扱える場合が多いのは大きな利点です。

3. 機械処理がしやすい形式がシンプルで曖昧さが少ないため、パースが高速で、ツール間の互換性も高いです。

静的型付き言語と合わせても、型定義とマッピングが行いやすくなっています。

4. Webとの相性が抜群ブラウザ側(JavaScript)とサーバー側の両方で違和感なく扱えるため、フロントエンドとバックエンドのデータフォーマットを統一しやすいという利点があります。

JSONのデメリット

一方で、設定ファイルとして使うときの JSON にはいくつかの弱点もあります。

1. コメントが書けない(仕様上) 標準的な JSON 仕様ではコメントを許可していません。

そのため「この設定はなぜこの値なのか」をファイル内に残しにくいという問題があります。

実装によっては拡張としてコメントを受け付けるパーサもありますが、ツール間の互換性を考えると避ける場合も多いです。

2. 冗長に感じることがある全てのキー名をダブルクォーテーションで囲む必要があり、配列やネストが深くなるとカンマや括弧が増えて視認性が落ちることがあります。

3. データ型が限定的 JSONの型はstring / number / boolean / null / array / objectに限られています。

日付やバイナリなどを表したい場合は、文字列などにエンコードする必要があります。

JSONが向いているケース

これらを踏まえると、JSONが特に向いているのは次のようなケースです。

Web API や SPA など、JavaScript が絡むシステム
フロントエンドとバックエンドで同じ形式を使いたい場合
設定内容が比較的シンプルで、長文のコメントが不要な設定ファイル
各種ツールやクラウドサービスとデータをやり取りする場合(多くが JSON をサポート)

逆に、人間が手で長くメンテナンスする複雑な設定ファイルでは、JSONよりも YAML や専用フォーマットが選ばれることも多いです。

初心者でもわかるJSONの基本ルール

JSONの文法ルールを最低限押さえておくと、エラーに悩まされることが減ります。

1. ルート要素は1つだけファイル全体はオブジェクト({})か配列([])のいずれか1つで始める必要があります。

2. キーは必ずダブルクォーテーションキー名は"key"のようにダブルクォーテーションで囲みます。

シングルクォーテーションは使えません。

3. 値の区切りにはカンマ、最後の要素の後ろには付けない配列やオブジェクトの各要素をカンマで区切り、最後の要素の後ろにカンマを付けてはいけません。

4. 文字列はダブルクォーテーションで囲む文字列も"value"のようにダブルクォーテーションで囲みます。

JSONの簡単な例

JSON

{
  "appName": "sample-service",
  "port": 8080,
  "debug": true,
  "databases": [
    {
      "name": "main",
      "host": "db.example.com",
      "port": 5432
    }
  ]
}

XMLの特徴と使いどころ

XMLのメリット

XMLには、JSONやYAMLにはない強みがあります。

1. スキーマによる厳密な定義とバリデーション XML Schema や DTD を使うことで、「要素の出現順」「属性の必須/任意」「型(整数・文字列など)」を厳密に定義できます。

これにより、大規模システム間でのデータ連携において、フォーマットの破綻を防ぎやすくなります。

2. タグで意味を明示しやすい開始タグと終了タグで囲むため、文書構造や意味を明示的に表現できます。

属性を使えば、要素にメタ情報をぶら下げることも容易です。

3. ツールや既存資産が豊富長年使われてきたフォーマットであり、エディタ、バリデーションツール、変換ツール(XSLTなど)、ライブラリが充実しています。

4. コメントや処理命令を書ける  の形式でコメントを埋め込めるため、設定内容の意図をファイル内に残しやすいです。

また、処理命令(<? … ?>)により、特定のツール向けの指示を書くこともできます。

XMLのデメリット

XMLは柔軟で強力な反面、設定ファイルとして使うときに気をつけたいポイントも多いです。

1. 冗長で読みづらくなりやすい開始タグと終了タグを書かなければならないため、階層が深くなると行数や記述量が膨らみやすいです。

人間が手で編集する設定ファイルとしては、見通しが悪くなることがあります。

2. パースが比較的重い JSONに比べると文法ルールや機能が多いため、パースの実装が複雑で、処理も重くなりがちです。

リアルタイム性が求められるシステムでは不利になることもあります。

3. 学習コストが高め XML自体の文法に加え、名前空間、スキーマ、XSLT など関連技術も多く、初心者にはとっつきにくい面があります。

XMLが向いているケース

XMLは次のようなケースで特に威力を発揮します。

スキーマで厳密に形式を定義したいシステム間連携
長く運用されているエンタープライズシステムとの連携(既にXMLが採用されている場合)
設定やデータ構造が非常に複雑で、文書中心のデータ(帳票、契約書データなど)を扱う場合
既存のXMLツールチェーン(XSLT, XPath など)を活用したい場合

逆に、小規模なサービスの軽量な設定ファイルであれば、JSON や YAML の方が扱いやすいことが多くなります。

初心者向けXMLの基本ルール

XMLの基本的な文法ルールを押さえておくと、パーサエラーに遭遇した際にも原因を特定しやすくなります。

1. すべてのタグは閉じる <tag></tag> のように、開始タグには必ず対応する終了タグが必要です。

内容がない要素は<tag />のように空要素として書くこともできます。

2. ルート要素は1つだけ JSONと同様、ファイル全体を包むルート要素は1つでなければなりません。

例えば<config>...</config>のようにします。

3. 属性と子要素を使い分ける <server host="example.com" port="80" /> のように属性で設定を書くことも、子要素として<host>example.com</host>と書くこともできます。

プロジェクト内でスタイルを統一することが重要です。

4. コメントは <!– … –> で書く設定の意図や注意点を残したい場合は、XMLコメントを使うとよいです。

XMLの簡単な例

XML

<?xml version="1.0" encoding="UTF-8"?>
<config>
  <!-- アプリケーション設定 -->
  <app name="sample-service" debug="true" />

  <!-- データベース設定 -->
  <databases>
    <database name="main">
      <host>db.example.com</host>
      <port>5432</port>
    </database>
  </databases>
</config>

YAMLの特徴と使いどころ

YAMLのメリット

YAMLの最大の売りは「人間に優しい」ことです。

1. 見た目がシンプルで読みやすい波括弧やダブルクォーテーションを省略でき、インデントで階層を表現するため、設定の全体像を視覚的に把握しやすいです。

JSONに比べてノイズが少なく、設定ファイルに向いています。

2. コメントが書ける # から行末までがコメントになるため、設定の意図や注意書きを自由に記述できます。

長期運用する設定ファイルでは大きなメリットです。

3. 複雑な構造もコンパクトに書ける配列やマップのネストが深くなっても、インデントを揃えるだけで自然に表現できます。

そのため、インフラやCI/CDなど多数のオプションを持つ設定との相性が良いです。

4. JSON と相互変換しやすい YAMLはJSONの上位互換的な位置づけであり、YAMLのサブセットとしてJSONを解釈できる実装も多いです。

ツール間での変換も容易です。

YAMLのデメリット

便利な一方で、YAMLならではの落とし穴も存在します。

1. インデントに厳密に依存する インデントのスペース数のズレが、そのまま構造の誤りにつながるため、見た目では気づきにくいバグを生みやすいです。

タブとスペースを混ぜると特に危険です。

2. 文法が思ったより複雑シンプルに見えますが、実はアンカー・エイリアス、複数ドキュメント、スカラーの書き方など、仕様全体はかなりリッチです。

ツール同士での対応状況もまちまちです。

3. パーサの実装差に注意が必要特にセキュリティの観点から、任意オブジェクトのデシリアライズなどの危険な機能を持つパーサもあり、利用時にはライブラリの特性を理解する必要があります。

YAMLが向いているケース

これらを踏まえると、YAMLは次のようなケースで特に向いています。

人間が手で頻繁に編集・レビューする設定ファイル
インフラ構成、CI/CD、コンテナオーケストレーションなど、オプションが多く複雑な設定
コメントとともにドキュメント的に設定内容を残したい場合
チームで運用するリポジトリ内の設定(レビューしやすい形式が求められる)

逆に、エンドユーザー向けのシンプルな設定や、他社サービスとのAPI連携などでは、JSONの方が無難なことも多いです。

初心者向けYAMLの基本ルール

YAMLを設定ファイルとして安全に使うために、最低限押さえておきたいルールをまとめます。

1. インデントはスペースで、数を統一する タブは使わず、スペース2つまたは4つなどに統一します。

プロジェクトのコーディング規約で決めておくと安心です。

2. マップ(連想配列)は key: value 形式 key: value の形式でキーと値を書きます。

値の後ろにスペースを入れ忘れないよう注意します。

3. 配列はハイフン(-)で表現 - item1 のように-から始める行が配列の要素になります。

配列の階層はインデントで表現します。

4. 文字列は基本的にクォート不要特殊な文字(コロンを含む、先頭が[や{など)を含まない限り、ダブルクォーテーションは省略できます。

必要に応じて"value"や'value'で囲みます。

YAMLの簡単な例

YAML

appName: sample-service
port: 8080
debug: true

databases:
  - name: main
    host: db.example.com
    port: 5432

JSON / XML / YAMLの選び方と判断基準

ここまで見てきたように、3つの形式にはそれぞれ得意・不得意があります。

「どれが一番優れているか」ではなく「どの条件ならどれが適しているか」で選ぶことが重要です。

「誰が読むか」で選ぶ

最初に考えたいのは「そのファイルを主に誰が読む・編集するのか」です。

開発者やツールが中心で、人間があまり直接触らない場合
→ JSON が第一候補。ツールサポートが豊富で、機械処理に向いています。
インフラエンジニアやアプリ開発者が日常的に手書き・レビューする場合
→ YAML が有力候補。可読性が高く、コメントも書けます。
業務システム担当者や別システムとの連携がメイン、スキーマが重要な場合
→ XML が選ばれやすい。既存の標準やツールチェーンがXML前提であることも多いです。

「どれくらい長く使うか」で選ぶ

次に「設定ファイルをどれくらいの期間、どれくらいの人数でメンテナンスするか」も重要です。

短命なスクリプトや一時的なツールの設定
→ 既に採用している形式(JSON など)に合わせてしまって問題ないことが多いです。
数年以上使い続ける本番システムの設定
→ 将来の保守を考えると、コメントを書ける形式(YAML / XML)が有利です。「なぜこの値なのか」を残せるかどうかは、数年後の自分やチームを助けます。
社内標準や社外とのインタフェース仕様として長く残るもの
→ スキーマや標準規格の有無(XMLベースの仕様が多い)も考慮します。

「何と連携するか」で選ぶ

最後に「周辺のツール・サービス・ライブラリが何を前提としているか」も重要な判断材料です。

Web API やフロントエンドと連携
→ ほぼ確実に JSON が第一候補です。APIドキュメントやSDKもJSON前提で提供されることが多くあります。
クラウドやCI/CDツール、コンテナ関連ツールと連携
→ YAMLを採用しているプロダクトが非常に多いため、そのツールの標準に合わせてYAMLを選ぶのが自然です。
既存のエンタープライズシステムや業界標準との連携
→ XMLベースの標準仕様が存在するケースが多く、その場合はXMLを採用せざるを得ません。

初心者向けおすすめ組み合わせ

最後に、これから開発環境を整える初心者の方に向けて、現実的なおすすめパターンをまとめます。

1. Webアプリケーション開発をする場合

API の入出力: JSON
フロントエンド(React/Vue等)の設定: JSON(package.jsonなど既存慣習に従う)
CI/CD やインフラ関連(Docker Compose, Kubernetes, GitHub Actions): YAML
アプリ固有の複雑な設定(人がよく触るもの): YAML を検討

2. 小〜中規模のバックエンドサービス

外部サービスとのデータ交換: JSON(相手がXML指定でない限り)
アプリの設定ファイル(envファイルに収まらない部分): YAML か JSON
→ コメントが欲しいなら YAML、ツールとの親和性を優先するなら JSON。

3. 既存の企業システムと連携する場合

先方の仕様が XML なら、XML を避けるのではなく理解して付き合うのが現実的です。
自分のシステム内部では JSON / YAML を使い、境界で変換する構成もよく取られます。

まとめ

本記事では、JSON / XML / YAML の違いと使い分けのポイントを整理しました。

JSONは、シンプルで機械処理に向いたデータ形式であり、特にWeb APIやフロントエンドとの連携で事実上の標準となっています。

一方で、コメントが書けないなど、人間が長期的にメンテナンスする設定ファイルとしてはやや不便な面もあります。

XMLは、スキーマや豊富なツール群に支えられた強力な形式です。

冗長さや学習コストの高さはあるものの、エンタープライズシステムや既存資産との連携では依然として重要な選択肢であり続けています。

YAMLは、人間が読み書きしやすいことを重視した形式で、インフラやCI/CDの設定に広く採用されています。

インデントに起因するバグなどの注意点はあるものの、コメントを書きながら複雑な設定を整理できる点は大きな魅力です。

最終的な選択は、「誰が読むか」「どれくらい長く使うか」「何と連携するか」という3つの観点から決めるのがおすすめです。

どれか1つにこだわるのではなく、用途に応じて複数の形式を使い分けることで、開発効率と保守性のバランスが取りやすくなります。

今後、新しいプロジェクトで設定ファイルを選ぶ場面に出会ったときは、本記事の内容を思い出しながら、自分たちのチームやシステムにとって最適な形式を検討してみてください。