YAML 解説 + JSON vs. YAML

Docker Compose、GitHub Actions、Kubernetes といった現代的なツールの設定ファイルを編集したことがあるなら、すでに YAML を書いています。人が最も読みやすいように設計されたデータフォーマットですが、その読みやすさにはいくつかの鋭い角が伴います。このガイドは YAML の仕組み、注意すべき落とし穴、そして JSON との比較を説明します。

YAML とは

YAML（“YAML Ain’t Markup Language”）は JSON が表現するのと同じもの — キー/値ペア、リスト、入れ子構造 — を表現するデータフォーマットですが、人が手で読み書きしやすいよう調整された文法を持ちます。設定ファイルの定番であるのは、まさに目で追いやすいからです。

name: RunWebTools
active: true
tags:
  - json
  - free
address:
  city: London
  postcode: null

文法の仕組み

3 つの考え方が YAML のほとんどをカバーします:

• インデントが構造を示します。 入れ子は波括弧ではなく空白で表現します。同じインデント階層の項目は兄弟です。
• キー/値ペア は key: value を使います（コロンの後の空白は必須）。
• リスト は各項目の先頭に - を付けます。

落とし穴

空白であってタブは不可

YAML はインデントにタブ文字を禁じています — パースエラーになります。エディタが空白を挿入するよう設定しましょう。画面では両者は同じに見えますが、有効なのは一方だけです。

“ノルウェー問題”

YAML は型を推測しようとし、これがときどき裏目に出ます。引用符のない no、yes、on、off はブール値になります — 有名な話として、ノルウェーの国コード NO が false に変わり得ます。文字どおりの文字列を意図するなら引用符で囲みます: "NO"。

インデントのミスは静かです

空白が意味を持つため、一行ずれただけでエラーもなく構造が変わり得ます — ファイルはただ、あなたの意図しない何かにパースされます。パース結果を再出力してくれる YAML バリデーター に通すのが、YAML が実際に何を理解したかを確かめる最速の方法です。

YAML vs. JSON

両者は同じデータを表現できます — 実際、すべての有効な JSON は有効な YAML でもあります。トレードオフは:

• 読みやすさ: 人には YAML が勝ります — 波括弧も引用符もなく、コメント（#）に対応しますが JSON は対応しません。
• 厳格さ: 機械には JSON が勝ります — その厳格な文法は、YAML が許す型推測やインデントの不意打ちの余地をほとんど残しません。
• 用途: 人が編集するファイル（設定）には YAML を、プログラムがやり取りするデータ（API）には JSON を選びましょう。

両者を行き来する必要が? YAML フォーマッター と JSON フォーマッター でどちらも整形・チェックできます。YAML が扱いにくく感じるなら、JSON とよくあるエラー のガイドが良い併読になります。