IT研修講師向け YAMLの原理原則

うさうさ研修工房 YAMLの原理原則 コピペで終わらせない構文リテラシー ― 国内外の一次情報から学ぶ 対象読者： IT研修受講者／新人エンジニア／セカンドキャリアIT人材 ゴール： 構文の丸暗記ではなく「なぜそう書くか」を理解し、初見のYAMLも読み解ける状態になる YAML Ain't Markup Language ／ 現行仕様 v1.2.2 (2021)

AGENDA 本日の構成 原理 → 落とし穴 → 実務チェックリストの順で、体系的に理解します 01 02 03 YAMLとは何か 書式の原理原則 型推論の罠 3つの基本構造とYAML 1.2.2仕様の位置づけ インデント／スカラー／ブロック文字列の設計思想 04 05 06 構造化とDRY 実務チェックリスト 一次情報源 シーケンス・マッピングの入れ子とアンカー／エイ リアス 現場で刺さる落とし穴と防止策、他形式との比較 国内外の公式仕様・技術記事の参照先一覧 Norway Problem・真偽値22パターンなど暗黙変換 の危険性 02

WHY YAML なぜ今、YAMLを原理から学ぶのか 設定ファイルの記述ミスは、本番障害に直結する Kubernetes GitHub Actions Docker Compose Ansible マニフェスト定義の標準形式 CI/CDワークフロー記述 コンテナ構成の宣言的定義 Playbookによる構成管理 読みやすさの裏に潜む危険性 YAMLは「人間に優しい」設計であるがゆえに、暗黙の型変換やインデントの曖昧さが事故の温床になり ます。構文を感覚で覚えると、初見の設定ファイルで誤読・誤設定が起こります。 03

FOUNDATIONS YAMLを構成する3つの基本要素 すべてのYAML文書は、この3つの組み合わせでできている スカラー (Scalar) シーケンス (Sequence) マッピング (Mapping) 文字列・数値・真偽値・null など、単一の値その 順序を持つ値の集合。他言語の配列・リストに相 キーと値の組。他言語の連想配列・ハッシュに相 もの 当 当 name: Suzuki - Apple - Orange key: value 補足：現行の仕様はYAML 1.2（改訂版1.2.2, 2021年10月）。JSONの完全なスーパーセットとなるよう設計されている。 04

PRINCIPLE 01 インデントは「構造」そのものである 括弧を使わない分、空白の数が階層構造を決定する 正しい例：階層ごとに一貫した空白数 customer: first_name: Dorothy address: city: East Centerville state: KS items: - part_no: A4786 price: 1.47 - part_no: E1628 price: 133.7 NG例：タブ混在・不揃いな階層 customer: first_name: Dorothy address: # ← 1文字多い city: East Centerville items: - part_no: A4786 # ← 親と同列 price: 1.47 # ← 対応が崩れる 原則：① タブ文字は使用不可（表示幅が環境依存のため） ② 同じ階層は必ず同 じ空白数 ③ スペース数自体に規定値はないが、チーム内で統一する（2または4 が主流） 05

PRINCIPLE 02 スカラーには4つの書式があり、挙動が異なる どの引用符を選ぶかで、エスケープや型解釈の結果が変わる プレーン（無引用） msg: Hello World 最も簡潔。ただし : や # 等の特殊文字や、型推論の対象になる点に注意 シングルクォート msg: 'It''s YAML' エスケープ処理をしない。引用符自体は '' と二重にして表現する ダブルクォート msg: "Line1¥nLine2" ¥n や ¥t 等のエスケープシーケンス、Unicode指定 ¥uNNNN が使える唯一の書式 ブロックスカラー msg: | 複数行の テキスト 改行を保持する | と、折りたたむ > の2種類（次スライドで詳説） 06

PRINCIPLE 03 ブロックスカラーは「改行の扱い」を明示的に選ぶ | ／ > とチョンピング指示子で、末尾の改行まで制御できる | リテラルスタイル > フォールドスタイル 改行をそのまま保持する。シェルスクリプトやSQLなど、改行そのものに意味が ある内容に使う 1つの改行はスペースに変換される（空行のみ改行として残る）。長い説明文を 折り返して書きたいときに使う script: | echo start echo done → 解釈結果： desc: > これは長い 説明文です。 "echo start¥necho done¥n" → 解釈結果： "これは長い 説明文です。¥n" チョンピング指示子（末尾改行の制御） 無印＝末尾改行を1つだけ残す ｜ -（strip）＝末尾改行を全て除去 ｜ >- >+ +（keep）＝末尾の空行も全て保持 例： |- |+ 07

PRINCIPLE 04 ― DANGER ZONE 型推論の罠 ―「ノルウェー問題」を知っているか クォートを省略すると、意図しない型に自動変換されることがある country: NO YAML 1.1系 パーサー ノルウェーの国コードのつもり false 真偽値になってしまう 背景：YAML 1.1仕様では y/yes/on/true と n/no/off/false を含む22通りの表記が真偽値として解釈される。YAML 1.2で true/false のみに厳格化されたが、PyYAML等 の実装は現在も1.1系のデフォルト挙動を引きずっているケースが多い。 その他の暗黙型変換トラップ version: 1.10 浮動小数点 1.1 として解釈され、末尾の0が消える zip: 010 YAML1.1では8進数10進換算8。1.2では 0o010 と書かないと8進数にならない flag: on / off 真偽値 true / false として解釈される 対策の原則： 曖昧になり得る値は必ずクォートで囲む（"NO" ／ "on" ／ "1.10"）。真偽値は true/false のみを使う。 08

PRINCIPLE 05 シーケンスとマッピングは自由に入れ子にできる 実務データは、この2つの組み合わせだけで表現される customer: の下 receipt: Oz-Ware Purchase Invoice customer: first_name: Dorothy family_name: Gale items: - part_no: A4786 descrip: Water Bucket price: 1.47 quantity: 4 - part_no: E1628 descrip: High Heeled Slippers price: 133.7 quantity: 1 bill-to: street: | 123 Tornado Alley Suite 16 city: East Centerville マッピングがネスト。firstとfamilyは兄弟キーとして同一階層。 items: の下 シーケンス。各要素がさらにマッピング（part_no, price…）を持つ＝リスト の中にオブジェクト。 bill-to.street: マッピングの値としてブロックスカラー(|)を持たせられる。値の種類に制限 はない。 原則：階層の深さそのものに上限はないが、深くなるほど可読性が落ちる。 実務では3〜4階層を目安に、それ以上はファイル分割や別キーへの切り出し を検討する。 09

PRINCIPLE 06 ブロックスタイルとフロースタイルは併用できる フロースタイルはJSONと同じ記法 ― YAMLがJSONの上位互換である所以 ブロックスタイル フロースタイル インデントで階層を表現（可読性重視） 波括弧・角括弧で表現（JSONと同一構文） fruits: - Apple - Orange - Strawberry user: name: Taro fruits: [Apple, Orange, Strawberry] user: {name: Taro, age: 30} age: 30 両者は完全に等価であり、混在も可能。ネストが浅く一行で収まる小さな配列・オブジェクトはフロースタイルの方が簡潔になる場面もある。 10

PRINCIPLE 07 アンカーとエイリアスでDRY原則を実現する & で定義し、* で参照し、<< でマージする ― 3点セットで理解する ② マージ（<<）で参照先を展開し 個別キーで上書き（エイリアス *） ① アンカー定義（&） default_settings: &defaults adapter: postgresql pool: 5 development: <<: *defaults database: myapp_dev test: <<: *defaults database: myapp_test &名前 アンカー定義 ― このノードに「名前」というラベルを付ける *名前 エイリアス ― ラベルが付いたノードをそのまま参照・複製する <<: *名前 マージキー ― マッピングの内容を展開し、個別キーで上書き可能にする 注意：多用すると参照関係を追いにくくなる。共通化の粒度はコメントで意図を補足しながら適切なバランスを保つ。 11

PRINCIPLE 08 1つのファイルに複数のYAML文書を格納できる --- で開始し ... で終端する ― ストリームという考え方 %YAML 1.2 %YAML 1.2 ディレクティブ。パーサーに使用する仕様バージョンを伝える（省略可） --- # document 1 codename: YAML release: 2001 --- --- # document 2 ドキュメント開始マーカー。1ファイル内で複数回使うと、複数文書（ストリー uses: ム）になる - configuration language - data persistence ... ... --- # document 3 ドキュメント終端マーカー（省略可能）。次のディレクティブの前には必須 company: usausa-lab domain: [devops, training] 実務での注意：言語・ライブラリによっては load/safe_load 系の関数が最初 の1文書しか読まない実装がある。複数文書ファイルを扱う場合はload_all系 の関数の使用を確認する。 12

PRACTICAL CHECKLIST 現場で刺さる、実務チェックリスト8箇条 コードレビューやCI（yamllint等）で機械的にチェックできる項目 曖昧な値は必ずクォートで囲む（国コード・on/off・バージョン番号など） 真偽値は true / false のみを使い、yes/no/on/off を避ける インデントにタブ文字を使わない。スペース数はチーム内で統一する 同一マッピング内でキーを重複させない（後勝ちか、エラーになるかは実装依 存） 信頼できない外部YAMLは safe_load 系の安全なロード関数で読み込む アンカー／エイリアスは共通化の粒度を意識し、多用しすぎない 行末の余分な空白・改行コードの混在（CRLF/LF）を統一する yamllint 等のLintツールをCIに組み込み、書式ミスを自動検出する 13

COMPARISON YAML・JSON・TOMLの使い分け 「読みやすさ」と「厳密さ」はトレードオフの関係にある 観点 YAML JSON TOML 可読性 ◎ 括弧が少なく人間向け △ 括弧・カンマが多い ○ セクション単位で明快 コメント ◎ # で記述可能 × 標準では不可 ◎ # で記述可能 曖昧さ △ 型推論の罠がある ◎ 型が明示的 ◎ 型が明示的 主な用途 K8s / CI/CD / Ansible API通信 / データ交換 Rust/Python等の設定 JSON互換性 ○ 上位互換（フロー式） ― × 非互換 14

SOURCES 参考にした一次情報源（国内・海外） 本資料は公式仕様と検証済み技術記事に基づいて作成しています 海外 (International) 国内 (Domestic) yaml.org るびま（Rubyist Magazine） YAML公式サイト／YAML 1.2.2 仕様書 プログラマーのためのYAML入門（初級編） yaml/yaml-spec (GitHub) Qiita 各種記事 仕様書ソースリポジトリ 初心者向け構文解説／アンカー・エイリアス実例 InfoWorld Zenn "7 YAML gotchas to avoid" 実務トラップ解説 設定ファイルの読みやすい書き方 解説記事 Wikipedia (EN) NTTドコモビジネス Engineers' Blog YAML の歴史・設計思想の概説 知ってるようで知らないYAMLのご紹介 15

SUMMARY まとめ：コピペから卒業するための3ステップ 原理を理解すれば、初見のYAMLも自力で読み解ける STEP 1 STEP 2 STEP 3 3つの基本要素で読む 型推論を疑う Lintと安全なロードを習慣化 スカラー・シーケンス・マッピングの組み合わせ として構造を捉える クォートなしの値を見たら「これは本当に文字列 か？」と一呼吸置く yamllintと safe_load を標準装備にし、事故を仕 組みで防ぐ うさうさ研修工房｜構文を覚えるのではなく、原理を理解して現場で応用できるエンジニアへ。 16