YAMLとは — JSONとの違いと基本の書き方

YAML（YAML Ain't Markup Language）は、人が読み書きしやすいことを最優先に設計されたデータ記述言語です。Kubernetes・GitHub Actions・Docker Composeなど、現代の開発で触れる設定ファイルの多くがYAMLで書かれています。本記事では、JSONとの違い、インデント・リスト・マップ・複数行文字列・アンカーといった基本の書き方、そして使いどころとつまずきやすい点を、実例コードで順に解説します。

1. YAMLとは

YAMLは2001年に登場したデータシリアライゼーション言語で、現在の最新仕様はYAML 1.2（改訂版1.2.2は2021年公開）です。名前は「YAML Ain't Markup Language」の再帰的頭字語で、HTMLのような文書マークアップではなく、設定やデータ構造の記述を目的としています。拡張子は .yaml または .yml が使われます。

表現できるデータ構造はJSONと同じく、スカラー（文字列・数値・真偽値・null）、シーケンス（リスト）、マッピング（キーと値）の3種類の組み合わせです。このため、YAMLで書ける内容はほぼそのままJSONに変換できます。

2. JSONとの違い

もっとも大きな違いは「誰のための表記か」です。JSONはプログラム間のデータ交換を主眼にした最小限の構文で、YAMLは人が直接編集することを主眼にしています。

なおYAML 1.2はJSONをほぼ上位互換として扱えるよう設計されており、多くの正しいJSON文書はそのままYAMLパーサーで読み込めます。両者の使い分けはCSVとJSONの比較記事でも触れています。

3. 基本の書き方 — マップ・リスト・ネスト

キーと値は キー: 値（コロンの後に必ずスペース）、リストは行頭の - （ハイフンの後にスペース）で書きます。階層はインデントで表し、スペース2個が慣用です。タブは使えません。

# コメントが書ける（JSONとの大きな違い）
name: sample-app        # 文字列は引用符なしでよい
version: "1.2"          # 数値に見せたくない場合は引用符で文字列に
debug: false            # 真偽値は true / false
services:               # ネストしたリスト
  - name: web
    port: 8080
  - name: db
    port: 5432
database:               # ネストしたマップ
  host: localhost
  options:
    pool: 10

これをJSONに変換すると次のようになります。同じ構造が、YAMLでは引用符と波かっこなしで書けていることが分かります。

{
  "name": "sample-app",
  "version": "1.2",
  "debug": false,
  "services": [
    { "name": "web", "port": 8080 },
    { "name": "db", "port": 5432 }
  ],
  "database": { "host": "localhost", "options": { "pool": 10 } }
}

4. 複数行文字列 — | と >

改行を含む文字列は、ブロックスカラーと呼ばれる記法で書きます。|（リテラル）は改行をそのまま保持し、>（折りたたみ）は改行をスペースに変換して1行につなげます。スクリプトの埋め込みには |、長文の説明には > が向いています。

script: |
  echo "1行目"
  echo "2行目"     # 改行がそのまま残る

summary: >
  この文章は折りたたまれて
  1行の文字列になります。   # 改行はスペースになる

5. アンカーとエイリアス — 値の再利用

同じ値を繰り返し書きたいときは、&名前（アンカー）で値に印を付け、*名前（エイリアス）で参照します。<<:（マージキー）と組み合わせると、マップの内容を継承して一部だけ上書きできます。CIの設定などで重複を減らすのに便利です。

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults      # defaults の内容を取り込む
  timeout: 60        # timeout だけ上書き

staging:
  <<: *defaults

JSONにはこの仕組みがないため、YAML→JSON変換ではエイリアスが実際の値に展開されます。

6. 使いどころと注意点

YAMLが選ばれているのは、Kubernetesのマニフェスト、GitHub ActionsやCircleCIなどのCI設定、Docker Compose、AnsibleのPlaybook、OpenAPI定義といった「人が読み書きし、レビューする設定ファイル」の領域です。逆に、プログラム同士のデータ交換やWeb APIのレスポンスには、仕様が小さく処理が速いJSONが標準です（JSONとは参照）。

書くときは次の3点に注意してください。

• インデントはスペースのみ。タブを使うと構文エラーになります。同じ階層は同じ幅に揃えます。
• コロン・ハイフンの後のスペースを忘れない。key:value は誤りで、key: value が正しい書き方です。
• 紛らわしい値は引用符で囲む。旧仕様のYAML 1.1では no・yes・on・off が真偽値に解釈され、国コードの NO（ノルウェー）が false になる「Norway問題」が有名です。YAML 1.2で解消されましたが、1.1系のパーサーも残っているため "NO" のように書くのが安全です。バージョン番号 1.20 が数値 1.2 に丸められるのを防ぐのにも引用符が有効です。

7. 実際に試せる方法

手元のYAMLがどんなJSONになるかを確かめると、構造の理解が一気に進みます。下記の変換ツールにYAMLを貼り付けると、その場でJSONに変換され、構文エラーがあれば行番号つきで表示されます。逆方向（JSON→YAML）の変換もできます。

8. 参考資料

本記事は次の一次情報を参照しています。より詳しい仕様はこちらを確認してください。

• YAML公式仕様「YAML Ain't Markup Language (YAML) version 1.2.2」（yaml.org）：https://yaml.org/spec/1.2.2/
• js-yaml 公式リポジトリ（JavaScript向けYAML 1.2実装・nodeca）：https://github.com/nodeca/js-yaml