YAML_Advanced_Specification_Course .pptx

うさうさ研修工房 CORPORATE IT TRAINING SERIES %YAML 1.2 --config: YAML完全仕様 マスター講座 ― 上級編 タグ・アンカー・バージョン差異・セキュリティまで、 YAMLだけを徹底的に掘り下 げる専門講座 対象：基本構文を習得済みのエンジニア／YAMLを深く理解したい実務者 所要時間：約150〜180分（演習含む） 2026 version: !!str 1.10 retries: 3 <<: *defaults # Deep dive into the spec

ABOUT THIS COURSE この講座について この講座の位置づけ 10章 専門トピックで構成 24枚 スライド構成 4言語 パーサー実装を比較 実例4本 本番相当の設定ファイル 本講座は「基本構文は書けるが、タグ・アンカーの細部やバージョン差異 まではわからない」というエンジニア向けの専門講座である。 YAML仕様 そのものに焦点を絞り、実務で誤解されやすいポイントを重点的に扱う。 前提知識 key: value、リスト、ネスト構造など、 YAMLの基本を読み書きできること。 到達目標 YAML 1.2仕様に基づいて構文を正確に説明でき、パーサーのバージョ ン差異やセキュリティ上のリスクを踏まえた設定ファイルを設計できるレ ベル。 この講座について YAML完全仕様マスター講座（上級編） 02

COURSE OUTLINE 目次 01 YAMLの歴史とバージョン仕様 06 YAML 1.1 vs 1.2／スキーマ検証 02 フロースタイル vs ブロックスタイル 07 セキュリティ： YAML爆弾 03 スカラー型推論とタグ 08 多言語パーサー実装比較 04 複合キー／アンカー／マージキー深掘り 09 実践：本番相当の設定ファイル 4種 05 タグシステムとディレクティブ 10 検証パイプラインとよくある間違い 目次 YAML完全仕様マスター講座（上級編） 03

CHAPTER 01 YAMLの歴史とバージョン仕様 2001年、Clark Evansらにより設計が開始され、2004年にYAML 1.0が、2005年にYAML 1.1が、2009年にYAML 1.2が公開された。 YAML 1.2で最も重要な変更は「JSONとの完全互換性」の獲得である。YAML 1.2の仕様上は、有効なJSONはすべて有効なYAMLとして解 釈できる。 一方で、多くの言語の実装（例：PyYAMLの既定ローダー）は今も YAML 1.1 ベースで動作しており、この差異が実務トラブルの温床になって いる（第6章で詳述）。 2001 2004 2005 2009 設計開始 YAML 1.0 YAML 1.1 YAML 1.2 Clark Evans, Ingy döt Net, Oren Ben-Kiki 初の正式仕様公開 現在も多くの実装既定値 JSONとの完全互換を実現 YAMLの歴史とバージョン仕様 YAML完全仕様マスター講座（上級編） 04

CHAPTER 02 フロースタイル vs ブロックスタイル YAMLにはインデントで表す「ブロックスタイル」と、JSONのような記号で表す「フロースタイル」の2つの表記法があり、混在も可能。 ブロックスタイル（推奨・可読性重視） user: フロースタイル（ JSON風・1行で完結） user: {name: Aoi, roles: [admin, editor]} name: Aoi roles: - admin - editor 使い分けの目安：構造が深い・行数が多い設定ファイルはブロックスタイル。短い配列や、他システムとの互換性を意識する場合はフロースタイルが便 利。 フロースタイル vs ブロックスタイル YAML完全仕様マスター講座（上級編） 05

CHAPTER 03 スカラー型推論と明示的タグ YAMLはクォートのない値から自動で型を推論するが、「!!」で始まる明示的タグを使うと、パーサーの推論に頼らず型を強制できる。 # 暗黙的な型推論 # 明示的タグで型を固定 port: 8080 # int version: !!str 1.10 debug: true # bool count: !!int "007" name: prod-01 empty: null # str # null flag: !!bool yes raw: !!binary R0lGODlh... 実務での勘所：バージョン番号（1.10）やゼロ埋めコード（007）は、クォートまたは !!str で明示的に文字列化しないと数値と誤解釈される。 スカラー型推論と明示的タグ YAML完全仕様マスター講座（上級編） 06

CHAPTER 03 複数行文字列 完全ガイド ― チョンピング指示子 | ／ > のあとに付ける - や + は「チョンピング指示子」と呼ばれ、末尾の改行の扱いを制御する。 記法 名称 末尾改行の扱い strip: |- | clip（既定） 末尾に改行を1つだけ残す line1 line2 |- strip 末尾の改行をすべて取り除く |+ keep 末尾の改行をすべて保持する 折り畳み＋clip 改行をスペースに変換し、末尾 改行を1つ残す > # → "line1\nline2" ( 改行なし終 端) keep: |+ line1 line2 # 空行も保持される 複数行文字列 完全ガイド YAML完全仕様マスター講座（上級編） 07

CHAPTER 04 複合キー（ Complex Mapping Key） 通常のキーは単純な文字列だが、YAMLでは「? 」を使うことで、リストやマップそのものをキーとして使う「複合キー」も表現できる。 実務での使用頻度は高くないが、座標データや複合条件をキーにする設定で登場することがあり、読めるようにしておく価値がある。 # 複合キー：? のあとにキー、次の行の : に値 ? [x, y] : coordinate label # 複数キーのマップをキーに使う例 ? { lat: 35.6, lng: 139.7 } : Tokyo Office 複合キー YAML完全仕様マスター講座（上級編） 08

CHAPTER 04 アンカー・エイリアス・マージキー 深掘り マージキー << は、複数のアンカーをリストで指定して合成することもできる。合成時は「後から書いた値が優先」される。 base: &base timeout: 30 retries: 3 logging: &logging level: info production: <<: [*base, *logging] retries: 5 # base の 3 を上書き # production の実質的な内容： # timeout: 30, retries: 5, level: info アンカー・エイリアス・マージキー深掘り YAML完全仕様マスター講座（上級編） 09

CHAPTER 05 タグシステムとディレクティブ !! で始まる標準タグ以外に、YAMLには順序を保証するコレクション型のタグや、独自タグを定義する仕組みがある。 ディレクティブ（ %） !!map 順序を問わない通常のマッピング（既定） %YAML 1.2 !!omap キーの順序を保証する順序付きマップ %TAG !app! tag:example.com,2024: --role: !app!admin ... !!set 値を持たない、一意な要素の集合 !!seq 通常のシーケンス（リスト、既定） タグシステムとディレクティブ %YAML はパーサーに使用バージョンを、%TAG は独自タグの接頭辞を宣言する。 --- の直前にのみ書ける。 YAML完全仕様マスター講座（上級編） 10

CHAPTER 06 YAML 1.1 vs 1.2 ― Norway Problem の正体 「Norway Problem」は、国名コード NO がブール値と解釈されてしまう有名な事故例。原因はバージョン間のブール値リテラルの違いにある。 YAML 1.1 YAML 1.2 真として扱われる値 y, yes, on, true, Y, YES... true のみ 偽として扱われる値 n, no, off, false, N, NO... false のみ 国名コード NO の扱い ブール値 false に解釈される 文字列 "NO" のまま 主な既定実装 PyYAML（safe_load含む） ruamel.yaml, js-yaml, snakeyaml 2系 実務での対策：国名コードや yes/no を値に持つ設定は、必ずクォートで囲んで文字列であることを明示する。 YAML 1.1 vs 1.2 YAML完全仕様マスター講座（上級編） 11

CHAPTER 06

JSON Schema によるYAML検証
YAML 1.2はJSONの上位互換であるため、JSON Schemaをそのまま流用してYAMLファイルの構造・型を検証できる。IDEの入力補完にも
使われる仕組み。

# schema.json

# config.yaml

{

port: "8080"

# ✗ 文字列は型エラー

"type": "object",
"required": ["port"],

# 検証コマンド例

"properties": {

# npx ajv validate \

"port": { "type": "integer" }

#

-s schema.json -d config.yaml

}
}

VS Code等のエディタでは、 YAMLファイル冒頭に # yaml-language-server: $schema=... と書くだけでスキーマを紐付けられる。

JSON Schema によるYAML検証

YAML完全仕様マスター講座（上級編）

12

CHAPTER 07 — SECURITY セキュリティ： YAML爆弾と安全な読み込み アンカー・エイリアスは便利な反面、悪用すると「YAML爆弾（Billion Laughs Attack）」と呼ばれるDoS攻撃に使われうる。エイリアスが指数関 数的に展開され、わずか数十行のファイルでメモリを枯渇させる。 a: &a ["lol", "lol", "lol"] b: &b [*a, *a, *a] # 3 × 3 = 9要素 c: &c [*b, *b, *b] # 9 × 3 = 27要素 # これを十数段繰り返すだけで、要素数は数十億に達する ● 信頼できない入力には yaml.safe_load()（Python）など安全なローダーを必ず使う ● 多くの言語で既定の load() は任意コード実行やエイリアス展開の制限がなく危険 ● サイズ・深さ・エイリアス展開数に上限を設けたパーサー設定を利用する セキュリティ：YAML爆弾 YAML完全仕様マスター講座（上級編） 13

CHAPTER 08

多言語パーサー実装比較
主要言語のYAMLライブラリで、同じファイルを安全に読み込むコードを比較する。
Python (PyYAML)

Node.js (js-yaml)

import yaml

const yaml = require('js-yaml')

with open("c.yaml") as f:

const data = yaml.load(

data = yaml.safe_load(f)

Go (yaml.v3)

fs.readFileSync('c.yaml', 'utf8'))

Java (SnakeYAML)

var data Config

Yaml yaml = new Yaml(new SafeConstructor());

err := yaml.Unmarshal(

Map<String,Object> data =

raw, &data)

多言語パーサー実装比較

yaml.load(inputStream);

YAML完全仕様マスター講座（上級編）

14

CHAPTER 09 — HANDS-ON 実践編： Docker Compose 詳細解説 depends_on services: web: 起動順序を制御するが、アプリの起動完了は保証しない image: nginx:1.27 ports: - "80:80" healthcheck depends_on: - api コンテナの死活監視。 test はフロースタイルのリストで記述 api: build: ./api environment: NODE_ENV: production healthcheck: environment マップ形式・配列形式（ NAME=value）どちらも可能 test: ["CMD", "curl", "-f", "http://localhost/"] interval: 30s 実践編：Docker Compose YAML完全仕様マスター講座（上級編） 15

CHAPTER 09 — HANDS-ON 実践編： GitHub Actions ワークフロー on.push.branches name: CI on: 配列はフロースタイルでもブロックスタイルでも等価 push: branches: [main] strategy.matrix jobs: build: runs-on: ubuntu-latest 複数バージョンでの並列実行を 1つの定義で表現 strategy: matrix: node: [18, 20] steps: - uses: actions/checkout@v4 uses / run 同じ steps 内でも各要素は独立したマップ（ - がその印） - run: npm ci && npm test 実践編：GitHub Actions YAML完全仕様マスター講座（上級編） 16

CHAPTER 09 — HANDS-ON 実践編： Kubernetes マルチリソースマニフェスト 1つのファイルに複数のリソースを --- で区切って定義するのは、 Kubernetesマニフェストで特に一般的なパターン。 apiVersion : v1 kind: Service metadata: name: web-svc spec: selector : { app: web } ports: [{ port: 80 }] # ドキュメント区切り：ここから 2つ目のリソース --- apiVersion : apps/v1 kind: Deployment metadata: name: web-app spec: replicas : 3 template : spec: containers : 実践編：Kubernetes - name: web, image: myapp:1.0 YAML完全仕様マスター講座（上級編） 17

CHAPTER 09 — HANDS-ON 実践編： Ansible Playbook 最上位はリスト - name: Webサーバー構築 hosts: web_servers Playbook全体が - name: から始まるシーケンス become: true vars: nginx_port : 80 tasks は入れ子のリスト tasks: - name: nginxをインストール 各タスクがさらに独立したマップを持つ apt : name : nginx state : present 日本語キー値OK - name: サービス起動 service : YAMLはUnicode文字列を問題なく扱える name : nginx state : started 実践編：Ansible Playbook YAML完全仕様マスター講座（上級編） 18

CHAPTER 10 検証パイプラインの構築 CIパイプラインにYAML検証を組み込むことで、構文ミスをレビュー前に機械的に検出できる。 # .github/workflows/lint.yaml - name: YAML構文チェック run: yamllint -d relaxed . - name: Kubernetesスキーマ検証 run: kubeval manifests/*.yaml 1. ローカル 2. pre-commit 3. CI 4. デプロイ前 エディタ拡張機能でリアルタイム検証 コミット前に yamllintを自動実行 プルリクエスト時にスキーマ検証も追 加 対象ツールの dry-run／plan相当で最 終確認 検証パイプラインの構築 YAML完全仕様マスター講座（上級編） 19

CHAPTER 10 よくある間違いトップ 10（上級編） 1 2 3 4 5 タブ文字の混入（インデントはスペースのみ） コロン直後のスペース忘れ（ key:value は不可） 同一階層のインデント幅不一致 Norway Problem（NO、on/offなどの意図しないブール化） バージョン番号の数値誤認識（ 1.10 → 1.1） よくある間違いトップ10 6 7 8 9 10 マージキー(<<) の対象がマップでない（配列やスカラーには使えない） アンカー未定義でのエイリアス参照（ *name が &name より前に出現） 信頼できない入力への load() 使用（safe_load推奨） 複数ドキュメントの --- 忘れによる意図しない上書き タブ幅・改行コード（ CRLF/LF）の混在による diffノイズ YAML完全仕様マスター講座（上級編） 20

SUMMARY 講座のまとめ ● YAML 1.2はJSON完全互換だが、多くの実装は今も1.1既定であり、Norway Problem等の差異を理解しておく必要がある。 ● !!タグによる明示的型指定、複合キー、マージキーの合成など、仕様の細部を知ることで曖昧な設定ファイルを避けられる。 ● アンカー・エイリアスはYAML爆弾のリスクを伴うため、信頼できない入力には必ず安全なローダーを使う。 ● Docker Compose・GitHub Actions・Kubernetes・Ansibleはいずれも同じYAML仕様の上に成り立っており、基礎を理解すれば横展 開できる。 修了チェックリスト ✓ | と >、4種のチョンピング指示子を説明できる ✓ safe_load を使うべき理由を説明できる ✓ 自分の言語の YAMLライブラリでファイルを安全に読み込める まとめ YAML完全仕様マスター講座（上級編） 21

APPENDIX 参考資料 YAML 1.2.2 公式仕様 yaml.org — 本講座の一次情報源。タグ・ディレクティブの正式定義。 PyYAML ドキュメント pyyaml.org — safe_load 等API仕様、既定バージョンの挙動。 js-yaml GitHub github.com/nodeca/js-yaml — Node.js向け実装、SCHEMA設定。 kubeval / yamllint 各種リンター公式ドキュメント。CI組み込み手順。 Billion Laughs Attack 関連CVE情報 各言語のYAMLライブラリのセキュリティアドバイザリ。 本講座の内容は YAML 1.2公式仕様および各ツールの公式ドキュメントに基づき、うさうさ研修工房が独自にまとめたものです。 参考資料 YAML完全仕様マスター講座（上級編） 22