YAMLチートシート - 構文・型・実用パターンリファレンス

概要

YAML（YAML Ain’t Markup Language）は人間にとって読みやすいデータシリアライゼーション言語です。インデントによる階層構造、最小限の記号、JSON のスーパーセットという特徴から、Kubernetes、GitHub Actions、Ansible、Docker Compose、各種フレームワークの設定ファイルなどで広く採用されています。本チートシートは現行仕様 YAML 1.2.2 を対象に、実用上必要となる構文と注意点を整理します。

基本ルール

• インデントは半角スペースのみ。タブは禁止。
• 同じ階層は同じインデント幅で揃える。
• コメントは # から行末まで。
• 文字列は基本的にクォート不要だが、特殊文字を含む場合は必須。
• ファイル拡張子は .yaml または .yml（公式は .yaml 推奨）。
• 1 ファイルに複数ドキュメントを書く場合は --- で区切り、... で終端できる。

スカラー型

文字列のクォート

クォートが必要な代表例:

• 値が true/false/yes/no/null/~ などの予約語
• 数字に見える文字列（"007"、"3.14"）
• 先頭が : - ? & * ! | > ' " % @ の文字
• コロン + スペースを含む文字列

シーケンス（配列）

# ブロック形式
fruits:
  - apple
  - banana
  - cherry

# フロー形式（JSON 風）
fruits: [apple, banana, cherry]

# ネスト
matrix:
  - [1, 2, 3]
  - [4, 5, 6]

マッピング（オブジェクト）

# ブロック形式
user:
  name: Alice
  age: 30
  email: alice@example.com

# フロー形式
user: { name: Alice, age: 30 }

# シーケンス内のマッピング
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

複数行文字列

literal: |
  line 1
  line 2
  line 3

folded: >
  this is
  one long
  sentence

trimmed: |-
  no trailing newline

double: "escape \n included"

アンカーとエイリアス

同じ値を再利用する仕組みです。&name で定義し、*name で参照、<<: *name でマージできます。

defaults: &defaults
  adapter: postgres
  host: localhost
  pool: 5

development:
  <<: *defaults
  database: app_dev

production:
  <<: *defaults
  database: app_prod
  host: db.prod.example.com

注意: マージキー << は YAML 1.1 の拡張で、1.2 仕様では公式機能ではありませんが、多くのパーサ（PyYAML、libyaml、Ruby Psych など）で実装されています。GitHub Actions など一部のパーサではサポートされない場合があるため、利用前に対象パーサを確認してください。

明示的なタグ

タグで型を強制できます。

複数ドキュメント

Kubernetes マニフェストなどでよく使われます。

実用例

1. GitHub Actions ワークフロー

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test

2. Docker Compose

services:
  web:
    image: nginx:1.27
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - api
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
    restart: unless-stopped
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

3. Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

4. Ansible Playbook

- hosts: web
  become: true
  vars:
    package: nginx
  tasks:
    - name: Install nginx
      apt:
        name: "{{ package }}"
        state: present
        update_cache: true
    - name: Ensure nginx running
      service:
        name: nginx
        state: started
        enabled: true

5. アプリケーション設定（Spring Boot 風）

server:
  port: 8080
  servlet:
    context-path: /api
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app
    password: secret
  jpa:
    hibernate:
      ddl-auto: validate
logging:
  level:
    root: INFO
    com.example: DEBUG

6. アンカーで重複排除

.x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  api:
    <<: *common
    image: my/api
  worker:
    <<: *common
    image: my/worker

7. 環境ごとに値を切り替え

defaults: &defaults
  log_level: info
  timeout: 30

development:
  <<: *defaults
  debug: true

production:
  <<: *defaults
  log_level: warn
  timeout: 10

8. JSON との互換

YAML 1.2 は JSON のスーパーセットなので、JSON はそのまま貼り付けて読み込めます。

{ "name": "Alice", "tags": ["dev", "ops"] }

よくある落とし穴

バリデーションツール

yq クイック例

トラブルシューティング

Tips & ベストプラクティス

• 半角スペース 2 文字インデントを基本にし、ファイル全体で統一する。
• ブール風の値や数字風の文字列はクォートする。特に country: NO のような国コードは要注意。
• 機密情報を直接書かず、環境変数や Secret 管理ツール（Vault、SOPS、Kubernetes Secret）を使う。
• 大規模な YAML はアンカー/エイリアスで重複を減らすか、テンプレートエンジン（Helm、kustomize）を活用する。
• CI で yamllint を回し、スタイルエラーを早期発見する。
• スキーマがあるツール（Kubernetes、Compose、GitHub Actions）はエディタの拡張機能（YAML Language Server）でリアルタイム検証する。
• 1 ファイルの行数が多くなったら分割を検討する。Kubernetes は --- で複数ドキュメントを 1 ファイルにまとめられる。
• YAML を生成するスクリプトでは、安全な公式ライブラリ（PyYAML の safe_dump、Ruby Psych など）を使い、独自に文字列連結しない。
• 互換性を重視するなら 1.2 仕様に従い、yes/no などの曖昧な値は避ける。
• 設定ファイルは git 管理し、レビューを通すことで構文崩れを防ぐ。

YAML と JSON の対応関係

YAML 1.2 は JSON のスーパーセットです。多くの場合、JSON はそのまま有効な YAML として読み込めます。

JSON ⇄ YAML 変換は yq で簡単に行えます。

ファイル冒頭の宣言

YAML ファイルにはオプションでバージョン宣言やタグ宣言を書けます。

実際の運用ではほとんど省略されます。

ベストな書き方の例

ドキュメントヘッダ付きの設定

# config.yaml
# アプリケーション設定。環境ごとに override する。
---
app:
  name: my-app
  version: 1.0.0
  log_level: info

server:
  host: 0.0.0.0
  port: 8080
  read_timeout: 10s
  write_timeout: 10s

database:
  driver: postgres
  host: db.internal
  port: 5432
  name: app
  pool:
    max_open: 25
    max_idle: 5
    max_lifetime: 1h

複数環境を 1 ファイルに

common: &common
  log_level: info
  timeout: 30

environments:
  development:
    <<: *common
    debug: true
    database_url: postgres://localhost/app_dev
  staging:
    <<: *common
    database_url: postgres://staging.db/app
  production:
    <<: *common
    log_level: warn
    database_url: postgres://prod.db/app

Kubernetes に複数リソース

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: my/web:1.0.0
          ports:
            - containerPort: 8080

エディタ設定のヒント

• VS Code: redhat.vscode-yaml 拡張機能で YAML Language Server を有効化し、スキーマ検証と補完を有効にする。
• Vim/Neovim: set expandtab tabstop=2 shiftwidth=2 を ftplugin で設定。
• EditorConfig を使うとプロジェクト全体で統一できる:

[*.{yaml,yml}]
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

参考リソース

• YAML 1.2.2 仕様（公式）
• YAML 公式サイト
• yamllint ドキュメント
• yq ドキュメント (mikefarah)
• YAML Language Server (Red Hat)