YAMLシンタックスチュートリアル：実践的な入門ガイド

YAML（YAML Ain't Markup Language）は、設定ファイル、CI/CDパイプライン、Infrastructure as Codeで広く使用されている、人間が読みやすいデータシリアライゼーションフォーマットです。Docker Compose、Kubernetes、GitHub Actions、Ansibleを使っているなら、すでに毎日YAMLを使っています。このチュートリアルでは、YAMLを自信を持って書くために必要なすべてを解説します。

なぜYAMLなのか？

YAMLの最大の利点は可読性です。同じデータをJSONとYAMLで比較してみましょう：

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAMLは少ない記号で同じ構造を表現できます。波括弧なし、シンプルなケースでは角括弧なし、必須の引用符もなし。これにより、設定ファイルが読みやすく、手動での編集も容易になります。

基本データ型

スカラー

YAMLは値から型を自動的に推論します：

string: hello world          # 文字列（引用符不要）
quoted: "hello world"        # 明示的な文字列
integer: 42                  # 整数
float: 3.14                  # 浮動小数点数
boolean: true                # ブール値（true/false, yes/no, on/off）
null_value: null             # Null（~ や空値も可）
date: 2025-01-15             # 日付（ISO 8601）

よくある落とし穴：yes、no、on、off のような値はブール値として解釈されます。文字列としての "yes" を意味する場合は、引用符で囲みましょう："yes"。

文字列と引用符

文字列に引用符が必要になることはまれですが、いくつかのケースでは必要です：

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

複数行文字列

YAMLには2つの複数行スタイルがあります：

リテラルブロック（|） — 改行を保持：

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

折りたたみブロック（>） — 行をスペースで結合：

description: >
  This is a long paragraph
  that will be folded into
  a single line.

末尾の改行を除去するには - を追加（|-、>-）、保持するには + を追加（|+、>+）します。

コレクション

リスト（シーケンス）

# ブロックスタイル
fruits:
  - apple
  - banana
  - cherry

# フロースタイル（インライン）
fruits: [apple, banana, cherry]

マップ（マッピング）

# ブロックスタイル
person:
  name: Alice
  age: 30
  city: London

# フロースタイル
person: {name: Alice, age: 30, city: London}

ネストされた構造

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

アンカーとエイリアス

アンカー（&）とエイリアス（*）を使うと値を再利用できます：

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # デフォルトを上書き

<< マージキーはアンカーからすべてのプロパティを取り込みます。マージ後に定義されたプロパティは、アンカーの値を上書きします。高度なアンカーパターンについては、YAMLアンカーとエイリアスガイドをご覧ください。

複数ドキュメント

1つのYAMLファイルに --- で区切られた複数のドキュメントを含めることができます：

---
# Document 1: Config
apiVersion: v1
kind: ConfigMap
---
# Document 2: Service
apiVersion: v1
kind: Service

これはKubernetesマニフェストでよく使用されます。

よくある落とし穴

1. インデントエラー

YAMLはスペースを使用し、タブは使用しません。一貫性のないインデントが最もよくあるエラーです：

# 間違い - インデントが混在
server:
  host: localhost
    port: 8080  # エラー：予期しないインデント

# 正しい
server:
  host: localhost
  port: 8080

YAMLフォーマッターを使って、インデントの問題を自動的に修正できます。

2. ノルウェー問題

NO（ノルウェー）のような国コードはブール値の false として解釈されます：

# 間違い
countries:
  - NO  # falseとして解釈される！
  - SE
  - DK

# 正しい
countries:
  - "NO"
  - SE
  - DK

3. 引用符なしの特殊文字

値にコロン、ハッシュ、角括弧が含まれる場合は引用符が必要です：

# 間違い
message: Error: file not found
url: http://example.com  # 問題が発生する可能性あり

# 正しい
message: "Error: file not found"
url: "http://example.com"

4. バージョン番号の落とし穴

1.0 のようなバージョン番号は浮動小数点数として解析されます：

# 間違い
version: 1.0  # 1（浮動小数点数）になる

# 正しい
version: "1.0"  # 文字列

YAMLの検証

デプロイ前に必ずYAMLを検証しましょう。YAMLの構文エラーはアプリケーションで原因不明の障害を引き起こす可能性があります。YAMLバリデーターは、エラーの正確な行と列をハイライトして、構文を即座にチェックします。

YAMLとJSONの違いについてさらに詳しくは、YAML vs JSON比較をご覧ください。

FAQ

YAMLのインデントにはスペースをいくつ使うべきですか？

2スペースが最も一般的な規約で、Kubernetes、Docker Compose、GitHub Actions、およびほとんどのDevOpsツールで使用されています。4スペースを使用するプロジェクトもあります。重要なルールはファイル内での一貫性です — インデントレベルを混在させてはいけません。

YAMLにコメントを含めることはできますか？

はい、YAMLは # による単一行コメントをサポートしています。複数行コメントの構文はありません。コメントは解析時に除去され、読み込まれたデータ構造では利用できません。

関連リソース

• YAMLフォーマッター — YAMLファイルの整形と美化
• YAML vs JSON — どちらのフォーマットを使うべきか
• Docker ComposeのためのYAML — Docker固有のYAMLパターン