YAML

YAML とは

YAML (YAML Ain't Markup Language) は、インデントベースの人間が読みやすいデータシリアライゼーション形式である。Kubernetes マニフェスト、GitHub Actions、Docker Compose、CloudFormation など、設定ファイルのデファクトスタンダードだ。仕様は 1.2 系が現行で、最新改訂は 1.2.2 (2021 年 10 月) である。ただしパーサー側の追随はまばらで、広く使われている実装が旧版 1.1 の解釈を保っていることが、後述する落とし穴の原因になっている。

基本構文

スカラー (文字列 / 数値 / 真偽値)、配列、マップの 3 つと、改行を保持する | と 1 行に折りたたむ > の使い分けを押さえれば、設定ファイルの読み書きは大半が足りる。

# 文字列
name: Alice
message: "Hello, World"

# 数値・真偽値
age: 30
active: true
score: 3.14

# 配列
tags:
  - typescript
  - aws
  - kubernetes

# オブジェクト (マップ)
address:
  city: Tokyo
  zip: "100-0001"

# 複数行文字列
description: |
  これは複数行の
  文字列です。
  改行が保持されます。

# 折りたたみ文字列
summary: >
  これは長い文章ですが
  1 行に折りたたまれます。

JSON との比較

同じデータを表せるが、想定している読み手が違う。人が編集して差分をレビューする設定ファイルは YAML、機械が生成して機械が読むデータ交換は JSON という住み分けが実務の既定になっている。

YAML の落とし穴

暗黙の型変換

# ❌ 意図しない型変換
version: 1.0    # float (文字列ではない!)
country: NO     # YAML 1.1 系パーサーでは boolean false (Norway ではない!)
zip: 01234     # YAML 1.1 系パーサーでは 8 進数と解釈され 668 になる

# ✅ クォートで文字列を明示
version: "1.0"
country: "NO"
zip: "01234"

どこまで型変換が起きるかは、パーサーが準拠する仕様版で変わる。1.1 では y / yes / on / no なども真偽値として扱われ、先頭が 0 の数字列は 8 進数と解釈される。1.2 の core schema では真偽値が true / false だけになり、8 進数は 0o14 のように接頭辞を要求するため、NO は文字列、01234 は 10 進の 1234 になる。国名コードのこの例が「Norway 問題」として知られる。2026 年 8 月時点でも Python の PyYAML は既定で 1.1 の解釈を採るので、同じファイルを Python と JavaScript の両方から読むと値が食い違う。版差を意識せずに済ませる最も確実な方法は、文字列として扱いたい値を必ずクォートすることである。

インデントエラー

# ❌ タブ文字は使えない (スペースのみ)
items:
	- item1    # タブ → パースエラー

# ✅ スペース 2 つ
items:
  - item1

アンカーとエイリアス

同じ内容の繰り返しは、& で名前を付けて * で参照するとまとめられる。

defaults: &defaults
  retries: 3
  timeout: 30

job_b: *defaults      # defaults の内容をそのまま参照

job_a:
  <<: *defaults       # マージキー: 展開して一部だけ上書き
  timeout: 60

エイリアスによる参照は 1.2 の仕様に含まれるが、マージキー << は 1.1 で定義された機能で 1.2 の仕様には無い。そのため 1.2 に準拠したパーサーでは既定で展開されず、<< という名前のキーがそのまま残る実装がある (オプションで有効化する)。共通設定をまとめる書き方は、読み込む側の実装を確かめてから使う。

使われる場面

いずれも人が手で書き、レビューし、差分を追う種類のファイルである。コメントを書けることと、括弧や引用符をほとんど要求しないことが、この用途で選ばれる理由になっている。

TOML との比較

どちらも設定ファイル向けだが、TOML は型と構造を明示する方向、YAML は記述量を減らす方向に振れている。ネストが深い構造は YAML、平坦なキーと値の集まりは TOML の方が読みやすい。

マルチドキュメント

1 つのファイルへ独立した複数のドキュメントを並べられるのも YAML の特徴である。

# 1 つのファイルに複数のドキュメント
apiVersion: v1
kind: ConfigMap
metadata:
  name: config
---
apiVersion: v1
kind: Service
metadata:
  name: my-service

--- で区切ることで、1 ファイルに複数の Kubernetes リソースを定義できる。

設定ファイルの書式として見ると、覚える構文が少ないことが最大の利点で、暗黙の型変換が最大の弱点である。クォートの習慣と、読み込む側のパーサーが準拠する版の把握、この 2 点で実務の事故はほぼ防げる。