--- title: YAML構文の原理原則 tags: #動画 #yaml author: [Yukiko](https://docswell.com/user/yukiko_it) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/LE3W3MX9E5.jpg?width=480 description: YAML構文の原理原則 by Yukiko published: July 02, 26 canonical: https://docswell.com/s/yukiko_it/5X227G-2026-07-02-100913 --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/LE3W3MX9E5.jpg) 構造化プロンプトのための YAML構文の原理原則 AI画像・動画生成のための構造化記述入門 うさうさ研修工房 面白きこともなき世を面白く 01 / 14 # Page. 2 ![Page Image](https://bcdn.docswell.com/page/8EDK46287G.jpg) AGENDA このセッションで扱う内容 01 02 03 04 05 なぜ AI生成プロンプト にYAMLか 基本文法：キー・値・イ ンデント リストとネスト構造 文字列・複数行・デー タ型 アンカー参照と実践例 ・落とし穴 自然文プロンプトとの違いと 利点 階層構造を表す最小ルール 配列と入れ子構造の書き方 クォート規則と | / > の使い分 け &/* による再利用とキャラ一 貫性プロンプト 02 / 14 # Page. 3 ![Page Image](https://bcdn.docswell.com/page/V7PKMY1WJ8.jpg) WHY YAML なぜAI生成プロンプトに YAMLを使うのか 自然文プロンプト 自然文プロンプトは読みやすい一方、要素同士の関係が曖昧になりが ちです。 紺のスーツを着た白いウサギのアナウンサーが、赤い蝶ネクタイをつけて、ニュース 番組風の背景で話している。表情は少し得意げ。 YAMLは「どの属性が何に属するか」を階層構造で明示できるため、 キャラクターの色・比率・ポーズなど多数のパラメータを 一貫して再現したい場面に向いています。 階層が視覚的に一目瞭然 YAML構造化プロンプト character: species: rabbit インデントがそのまま属性の所属関係を示す 属性の抜け漏れに気づきやすい キー名を固定できるためチェックしやすい 差分管理・再利用がしやすい outfit: navy suit accessory: red bow tie scene: setting: news studio expression: confident smile 一部の値だけ変更して別バリエーションを生成 03 / 14 # Page. 4 ![Page Image](https://bcdn.docswell.com/page/2JVV9GY9JQ.jpg) SYNTAX 01 キーと値 — key: value YAMLの最小単位は「キー：値」のペアです。 コロンの直後に半角スペースが 1つ必要という点が、 最初につまずきやすいポイントです。 outfit_color: navy キー 必ず半角 1つ 値 colon + space 「key: value」— コロンの後に必ず半角スペース 複数プロパティの例 name: shirousagi キー名は自由 英数字・アンダースコアが安全。日本語キーも使用可能 role: announcer voice_tone: warm and playful confidence: 8 値の型は自動判定 is_mascot: true 文字列・数値・真偽値などは書式から自動で推定される 04 / 14 # Page. 5 ![Page Image](https://bcdn.docswell.com/page/5EGLZ894JL.jpg) SYNTAX 02 インデント — 階層を作る唯一の手段 階層構造の例 YAMLには { } や end のような区切り記号がありません。 インデントの深さそのものが「どの階層に属するか」を表します。 character: appearance: fur_color: white 半角スペースのみ タブ文字は禁止。多くのパーサーがエラーになる 同じ階層は同じ幅 兄弟キーのインデント幅を厳密に揃える eye_color: ruby red outfit: jacket: navy blue bow_tie: red scene: 幅は 2または 4推奨 background: news studio 一つのファイル内で幅を統一する 05 / 14 # Page. 6 ![Page Image](https://bcdn.docswell.com/page/4JQYL9WR7P.jpg) SYNTAX 03 リスト（配列） — ハイフンで列挙する オブジェクトのリスト 複数の値を並べたいときは、行頭に「 - 」（ハイフン+半角スペース）を つけて列挙します。画像生成では「複数のポーズ候補」「参照する スタイルタグ」などを配列で表現すると便利です。 reference_shots: - angle: front expression: smiling - angle: side profile expression: neutral 2つの書き方 poses: - waving - pointing forward 「- 」の後に key: value を続けると、 リストの各要素自体がひとつのマップになる - thumbs up tags: [flat, cheerful, bold-outline] インライン形式（角括弧）でも同じ意味 06 / 14 # Page. 7 ![Page Image](https://bcdn.docswell.com/page/K74WDXKQE1.jpg) SYNTAX 04 ネスト構造 — マップの入れ子 3階層ネストの例 character: マップ（キー：値の集合）は、値の位置にさらにマップを 置くことで、いくらでも深く入れ子にできます。 appearance: palette: 「キャラクター＞外見＞配色」のような分類階層を fur: #FFFFFF そのままYAMLの階層に対応させると設計しやすくなります。 jacket: #1B2A4A bow_tie: #C0392B proportions: 設計のコツ head_to_body: 1:2.5 大分類（character / scene / style）を第1階層に置き、 各分類の中に詳細属性をぶら下げると、後から 要素を差し替えやすい構成になる。 07 / 14 # Page. 8 ![Page Image](https://bcdn.docswell.com/page/LJ1YZNXLEG.jpg) SYNTAX 05 文字列とクォートの規則 クォート不要 と 必要 の比較 YAMLでは多くの文字列にクォートは不要ですが、 style: flat illustration 特定の記号や意味を持つ語を値に含める場合は ↑ 通常の文字列はクォート不要 クォートで囲まないと解析エラーになります。 aspect_ratio: "16:9" ↑ コロンを含むためクォート必須 コロンを含む文字列 "ratio: 16:9" のように : を含む場合は必須 先頭が特殊記号 #, &, *, !, |, >, [, ] などで始まる値 true/false/null に見える文字列 シングル と ダブル の違い single: 'no escape needed' double: "line1\nline2" "true" や "null" を文字列として扱いたい場合 ダブルクォートのみ\n のようなエスケープシーケンスを解釈する 先頭・末尾の空白を保持したい 意図的な空白はクォートで明示する 08 / 14 # Page. 9 ![Page Image](https://bcdn.docswell.com/page/GJWG94NQ72.jpg) SYNTAX 06 複数行文字列 — | と > literal（|）の例 詳細な情景描写やネガティブプロンプトなど、長文を scene_note: | カメラは正面やや下から。 一つの値として書きたい場合はブロックスカラーを使います。 背景は柔らかいボケ。 改行を保持するか畳み込むかで記号を使い分けます。 照明は暖色系。 | （パイプ）＝ literal 改行をそのまま保持する。詩や台本のような 行区切りに意味がある文章に使う。 folded（>）の例 description: > > （フォールド）＝ folded 白いウサギのアナウンサーが 笑顔でカメラ目線を送っている 改行をスペースに変換して1行に畳み込む。 読みやすさ優先の長文説明文に向く。 → 実際は 1行の文字列として解釈される 09 / 14 # Page. 10 ![Page Image](https://bcdn.docswell.com/page/4EZL923373.jpg) SYNTAX 07 コメントとデータ型の自動判定 コメント付きサンプル # キャラクター設定シート # から行末まではコメントとして無視されます。 値はクォートなしで書くと文字列・数値・真偽値・ null が name: shirousagi 表記から自動的に判定される点に注意が必要です。 age_look: unspecified confidence_level: 8 文字列 整数 / 小数 flat illustration 3 真偽値 null（値なし） true / false null もしくは ~ is_mascot: true signature_prop: null / 1.5 # ↑ 小道具は場面ごとに指定 10 / 14 # Page. 11 ![Page Image](https://bcdn.docswell.com/page/Y76WKVXZ7V.jpg) SYNTAX 08 アンカーと参照 — & と * アンカー定義と参照 base_character: &rabbit &名前 で値に「アンカー（目印）」を付け、 *名前 で その値を別の場所から再利用できます。 fur: white jacket: navy 同じキャラクター設定を複数シーンで使い回すときに 重複記述を避けられ、一貫性の担保にも役立ちます。 scene_1: *rabbit scene_2: *rabbit 活用シーン *rabbit は &rabbit の内容をそのまま複製する。 scene_1・scene_2 どちらも同一の外見定義になる。 同一キャラクターの複数ポーズ・複数シーンを 1ファイルにまとめる際、外見定義をアンカー化して 使い回すと表記ゆれによる崩れを防げる。 11 / 14 # Page. 12 ![Page Image](https://bcdn.docswell.com/page/G75MPDX974.jpg) CASE STUDY 実践例：キャラクター一貫性プロンプト これまでの文法をまとめて、しろうさぎアナウンサーの生成プロンプトを構成する # しろうさぎアナウンサー 基本設定 character: &rabbit species: white rabbit outfit: jacket: navy blue suit bow_tie: red palette: fur: #FFFFFF jacket_color: #1B2A4A scene: cast: - *rabbit setting: news studio camera: front, slightly low angle negative_prompt: > blurry, extra limbs, inconsistent colors &rabbit / *rabbit 外見定義を一度書き、cast内で再利用 ネストされたpalette 色コードを別階層に分離して差し替えやすく > によるnegative_prompt 除外条件を1つの畳み込み文字列に集約 12 / 14 # Page. 13 ![Page Image](https://bcdn.docswell.com/page/9J2968X5ER.jpg) PITFALLS よくある落とし穴 画像・動画生成プロンプトを書く際、特につまずきやすい6点 タブ文字の混入 兄弟キーのインデントずれ コロンを含む未クォート文字列 エディタの自動インデントがタブを挿入していないか確認 1マスでもずれると別階層と解釈される "16:9" のように : を含む値は必ずクォート true/false/null の意図しない型変換 全角スペースの混入 末尾の不要な空白 文字列として使いたい場合は明示的にクォート 日本語入力時の全角スペースはパースエラーの原因 キー・値の末尾に見えない空白が残っていないか確認 13 / 14 # Page. 14 ![Page Image](https://bcdn.docswell.com/page/DEY49686JM.jpg) SUMMARY まとめ： 5つの原理原則 階層はインデントで表現する タブ禁止・幅を統一 リストは「 - 」で列挙する 配列 or オブジェクトのリスト 特殊文字を含む値はクォート 特に : を含む値は必須 長文は | / > で使い分け 改行保持か畳み込みか アンカー (&)と参照(*)で再利用 一貫性の担保と重複削減 うさうさ研修工房 面白きこともなき世を面白く 14 / 14