YAMLの基礎

インデントこそが構文

YAMLにおいて、空白文字は飾りではありません――構造そのものです。マッピングは、キー、コロン、スペース、値という並びです。ネストした値は次の行に、さらにインデントを深めて書き、同じインデントの2行は兄弟です。タブはまったく禁じられています。仕様はタブの幅を決められないので、パーサーは推測する代わりにタブを拒否します。エディターはコピーペーストのたびにタブを入り込ませてくる――だからこそ、完璧に見えるのにパースを拒むファイルがあまりに多いのです。

慣習では、1レベルにつきスペース2個です。4個でも6個でも同じく有効です――仕様が禁じているのはタブだけ――しかし2個は、KubernetesとComposeが使い、あらゆるリンターが期待し、深いマニフェストが横にスクロールするのを防ぐ値です。1つのファイルの中で幅を混在させるとインデントエラーが生まれます。2個に決めて、エディターに強制させましょう。

• 1レベル＝任意の固定スペース数。慣習は2個。
• インデント内のタブは、変換ではなく拒否される。
• シーケンスの項目は、親キーと同じインデントに置ける――ダッシュが印だから。
• 値はフロースタイルでインラインに書くこともできる：ports: [8080]。

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

スカラーとノルウェー問題

クォートされた値は常に文字列です。クォートなしの値は推論で型が決まり、YAMLの評判はこの推論から生まれました。素の8080は数値8080になり、空の値はnullになります。これは助けになります――ただし、国コードやバージョン文字列のように、テキストのつもりで書いたものまで推論が型づけするまでは。

古典的な失敗は、ISO国コードのリストでNO――ノルウェー――が真偽値falseとしてパースされることです。これがノルウェー問題。デプロイフラグを黙って無効化するまでは笑い話で済みます。バージョン1.1は、表のとおり、さらに遠くまで行っていました。1.2のコアスキーマはtrueとfalseだけを真偽値として解決し、下の表の残りはプレーンな文字列か十進数の数値として読みます――しかし、あまりに多くのソフトウェアが依然として1.1のルールを適用しているため、防御の習慣としては、文字列であり続けるべきものはすべてクォートすることです。

クォートとブロックスカラー

YAMLで文字列を書く方法は3つあります。クォートなしは既定で、ほとんどの値に向いています。シングルクォートはリテラル――エスケープはクォートを重ねる（'it''s fine'）ことだけです。ダブルクォートは\nや\tのようなバックスラッシュエスケープに対応していて、これはJSONが使うスタイルです。防御のルールもそのまま引き継がれます。構造と誤解されうるもの――コロン、ハッシュ、予約語――が値に含まれるなら、意図的にクォートしてください。

複数行のテキストにはブロックスカラーを使います。|で書くリテラルブロックは、入力したとおりの改行をすべて保持します――シェルスクリプトや証明書に合う形です。>で書くフォールデッドブロックは、行を1つの流れるような段落につなげます――長い説明文に合う形です。どちらもチョンピングインジケーターを取ります。|-は最後の改行を取り除き、|+は末尾の改行をすべて残し、素の|はちょうど1つ残します。

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

アンカー、エイリアス、再利用

YAMLでは、あるノードに名前を持たせ、他のノードから参照できます。キーの後に&nameと書けば値をアンカーし、別の場所に*nameと書けばエイリアスになります。パーサーはアンカーされたノードのコピーを代わりに差し込みます。1つのリトライポリシーを共有するジョブは、単一の定義を指すだけで済み、変更は1か所で済みます。

この仕組みに乗った拡張が2つあります。マージキー（<<: *nameと書く）は、アンカーされたマッピングのすべてのキーを現在のマッピングに継ぎ接ぎます――ComposeやAnsibleのファイルでよく見られ、1.1時代の慣習で、1.2のコア文法には入らなかったものです。アンカーは悪用もできます。エイリアスの中にエイリアスを入れ子にすれば、10個の定義が100万ノードに膨れ上がります――billion-laughs攻撃――信頼できるパーサーは、ハングアップする代わりに、展開に上限を設け、その上限を報告します。

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

コメントと複数ドキュメント

コメントは#で始まり行末まで続きます。クォートされた文字列の中のハッシュはコメントになりません。これは、設計上コメントを排除したJSONに対するYAML最大の人間工学的な勝利であり、人間が保守する設定がYAMLへ流れ込む理由です。ファイルがインラインで自己説明し、レビューでは1行とそのコメントを1つのdiffハンクで引用できるのですから。

1つのファイルに複数のドキュメントを入れることもできます。ダッシュ3つの行で区切ります。先頭の---は任意の開始マーカーで、...がドキュメントの終わりです。これにより、1つの成果物がステージング用設定と本番用設定を並べて運べます。このサイトのコンバーターはすべてのドキュメントをパースし、最後のドキュメントを対象に操作します。一般的なCLIの挙動に合わせたものです。

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

このサイトのコンバーターが受け入れるもの

どのYAMLパーサーも、サブセットのパーサーです――1.2の完全な文法は有名なほど大きいため――コンバーターが信頼を得るには、失敗に気づかせて発見させるのではなく、自分のサブセットを明示することです。このサイトのYAMLライブラリは、実際の設定ファイルに現れるブロック構文とフロー構文の上に1.2コアスキーマを実装し、仕様が無制限の作業を許す箇所には意図的な制限を設けています。表がその契約です。