PART 03 — 基本記法
マッピング・シーケンス・スカラー値とインデントルール

シーケンスの中にマッピングを書くとき、ハイフンの位置を毎回迷っていました。「マッピング・シーケンス・スカラーの3つしかない」と要素を数で捉え直してから、どんなに深くネストしても読み解けるようになった気がします。

YAMLの3要素

図1: インデントの深さがそのままツリーの階層になる

YAMLで表現できるデータは、以下の3種類の組み合わせだけで構成されています。

マッピングの値やシーケンスの要素として、別のマッピング・シーケンス・スカラーを自由に入れ子にできます。これが「ネスト」であり、YAMLで複雑な構造を表現する仕組みそのものです。

マッピング（辞書）の書き方

マッピングは キー: 値 の形式で書きます。コロンの直後に半角スペースが1つ必須である点に注意してください。

name: web-app
version: 1.2.0
description: サンプルアプリケーション

ネストしたマッピング（マッピングの値として、さらにマッピングを書く）は次のように表現します。

database:
  host: db.example.com
  port: 5432
  credentials:
    user: admin
    password: secret

database の値は空にして改行し、次の行から2スペース深くインデントすることで「databaseの中にhost・port・credentialsがある」という階層を表現しています。

シーケンス（配列）の書き方

シーケンスは、各要素の先頭に -（ハイフン + 半角スペース）を付けて表現します。

fruits:
  - apple
  - banana
  - orange

マッピングのキーに紐づくシーケンスは、キーと同じインデント位置に - を置いても、1段深くインデントしても、どちらも同じ意味として解釈されます（多くのパーサー・Lintツールでは後者の書き方が推奨されます）。

users:
  - name: Alice
    role: admin
  - name: Bob
    role: viewer

この例では users がシーケンスで、その各要素が「nameとroleを持つマッピング」になっています。- name: Alice の name と、次の行の role が同じインデント位置（-の後ろの文字の位置）にそろっている点がポイントです。

スカラー値の型

スカラー値には型がありますが、YAML自体は「文字列っぽく見えるものを、文脈から型推論する」という設計になっています。

文字列にコロン・ハイフン・特殊記号を含む場合や、意図的に数値・真偽値と誤解されるのを防ぎたい場合は、シングルクォート（'...'）またはダブルクォート（"..."）で明示的に囲みます。

インデントルール

YAMLの階層構造はすべてインデント（字下げ）の深さで決まります。ここがJSON/XMLと最も違う部分であり、最も事故が起きやすい部分でもあります。

• インデントには半角スペースのみ使用する — タブ文字は仕様上禁止されている
• 同じ階層は必ず同じ幅でそろえる — 1つでもズレるとエラーになるか、意図しない階層になる
• スペースの数自体に決まりはないが、慣習的に2スペースが最も広く使われる

service:
  name: web-app
   port: 8080   # ← nameより1スペース深く、階層が崩れてエラーになる

ネストの書き方

実務でよく登場する「マッピングの中にシーケンス、シーケンスの中にマッピング」というネストの組み合わせをまとめて見ておきます。

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    environment:
      - ENV=production
      - DEBUG=false
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

この例では、services（マッピング）の中に web と db（マッピング）があり、それぞれの中に ports や environment（シーケンス）が入っています。最後の volumes: → db-data: のように、値を省略してnullを表す書き方もよく使われます。

コメントの書き方

コメントは # から行末までです。行全体をコメントにすることも、値の後ろに付けることもできます。

# このファイル全体の説明
service:
  port: 8080  # 開発環境では8080、本番では環境変数で上書きされる

まとめ：記法早見表