docker-compose.ymlのインデントを1つ間違えただけでコンテナが起動しなくなり、原因究明に小一時間を溶かしたことがあります。「なんとなく書けてしまう」フォーマットだからこそ、一度ちゃんと整理しておこうと思ったのがこのシリーズのきっかけです。

YAMLとは

同じ設定内容をYAML・JSON・XMLで書いた場合の見た目の違いを比較した図

図1: 同じデータでも、記号の量と視認性が形式によって大きく異なる

YAML（YAML Ain't Markup Language、あるいは元の意味である Yet Another Markup Language の再帰的頭字語）は、インデント（字下げ）で階層構造を表現するデータシリアライゼーション言語です。2001年に最初の仕様が公開され、現在は多くの開発ツール・クラウドサービスの設定ファイル形式として事実上の標準になっています。

XMLやJSONと同じく「構造化データをテキストで表現する」ための形式ですが、YAMLは人間が読み書きすることを強く意識して設計されています。中括弧やクォートを最小限に抑え、インデントだけで階層を表現できる点が最大の特徴です。

主な用途 — どこで使われているか

YAMLは特定の言語やフレームワークに紐づかない汎用フォーマットのため、実に幅広いツールの設定ファイルとして採用されています。

Docker Compose
複数コンテナの構成を docker-compose.yml 1枚で定義する。サービス・ネットワーク・ボリュームを宣言的に記述。
GitHub Actions
.github/workflows/*.yml でCI/CDパイプラインのジョブ・ステップ・トリガー条件を定義する。
Kubernetes
Pod・Deployment・Serviceなど、あらゆるリソースのマニフェストがYAML形式。kubectl apply -f で適用する。
Ansible
サーバー構成管理のPlaybookをYAMLで記述し、タスクの手順を宣言的に定義する。

このほかにも、静的サイトジェネレータのFront Matter、OpenAPI（Swagger）仕様書、各種Lintツールの設定ファイル（.eslintrc.yml など）まで、「アプリのコードではなく、周辺の設定を書く」場面でYAMLが選ばれることが非常に多くなっています。

JSON・XMLとの比較（○×表）

同じ「構造化データの記述言語」として比較されることが多いJSON・XMLと、実務でよく問題になる観点で比較しました。○＝標準で対応、△＝実装や運用でカバー可能、×＝標準では非対応という基準です。

観点 YAML JSON XML
コメントの記述 ○ # で可能 × 標準では非対応 △ <!-- -->で可能
人間にとっての読みやすさ ○ 記号が少なく高い △ 括弧・クォートが多い × 閉じタグで冗長
プログラムからの扱いやすさ △ パーサー依存の差異あり ○ 仕様がシンプルで一貫 △ スキーマ定義は強力だが複雑
複数ドキュメントの表現 ○ ---区切りで標準対応 × 標準では非対応 × ルート要素は1つのみ
データ型の表現力 ○ 日付型なども解釈可能 △ 文字列・数値・真偽値のみ × すべて文字列（属性で補完）
パース速度 × JSONより低速な傾向 ○ 高速 △ ツール・実装依存

⚠️ インデント依存はメリットでもリスクでもある

YAMLの読みやすさは「インデントで階層を表す」という設計から来ていますが、裏を返せばインデントのズレがそのまま構造の誤りに直結します。タブ文字が使えない・全角スペースが混入すると即座にエラーになる点は、JSON/XMLにはない注意点です。この対策はPART 02・PART 05で扱います。

YAMLが設定ファイルの標準的な選択肢になった背景には、単に「読みやすいから」だけでなく、いくつかの実務的な理由があります。

  • コメントが書ける — 「なぜこの値なのか」を設定ファイルの中に残せる。JSONにはこれができない。
  • 差分が読みやすい — Gitのdiffで見たときに、変更箇所が直感的に把握しやすい。
  • 言語非依存 — Python・Go・Rubyなど、ほぼすべての主要言語に成熟したパーサーライブラリが存在する。
  • JSONの上位互換に近い — 多くのYAMLパーサーはJSONもそのまま読み込める（JSONはYAMLのサブセットに近い）。

YAMLの弱点も知っておく

普及している一方で、YAML特有の落とし穴も知られています。代表的なのが「ノルウェーの問題」と呼ばれるもので、YAML 1.1では NO や YES、on / off といった単語が自動的に真偽値（boolean）と解釈されてしまい、国名コード「NO（ノルウェー）」を文字列のつもりで書いたら false になっていた、という事故が実際に起きています。

💡 回避策

意図せず真偽値・数値と解釈されるのを防ぐには、文字列として扱いたい値を "NO" のように明示的にクォートで囲みます。この点はPART 03（スカラー値の型）で詳しく扱います。

本シリーズの構成

全5回で、ツール導入から基本記法、応用記法、記述ルールの統一までを一通り解説します。

PART内容
01（本記事）YAMLの特徴、用途、JSON/XMLとの比較
02ツール導入 — VS Code拡張機能とyamllintによる構文チェック環境構築
03基本記法 — マッピング・シーケンス・スカラー値とインデントルール
04応用記法 — アンカー・参照・複数ドキュメント・フロースタイル
05記述ルールとベストプラクティス — Lint統一とCI組み込み、まとめ

✅ 次の章では…

PART 02 では、VS CodeへのYAML拡張機能導入と、yamllintによるコマンドライン構文チェック環境の構築手順を解説します。

→ PART 02 — ツール導入へ