FormatArcかんたんデータ変換
YAML構文入門

YAML の書き方ガイド — 正しい構文をゼロから学ぶ

YAML の書き方を実例付きで解説します。インデント規則、キーバリュー、リスト、マルチライン文字列、アンカー、コメント、初心者がハマりやすい間違いまでを網羅します。

FormatArc の YAML to JSON で構文チェックを行った画面

YAML とは、どこで使われているのか

YAML（YAML Ain't Markup Language）は、人間が読みやすいテキスト形式の構造化データフォーマットです。文字列・数値・真偽値・null・リスト・マッピングという、JSON と同じデータモデルを扱えますが、構文は括弧ではなくインデントで階層を表現します。

現代の DevOps やクラウドネイティブのツールを使っていれば、すでに YAML を目にしているはずです。

  • Kubernetes マニフェスト、Helm チャート
  • Docker Compose
  • GitHub Actions、GitLab CI、CircleCI のワークフロー
  • Ansible プレイブック
  • OpenAPI 仕様
  • 静的サイトジェネレーター（Hugo, Jekyll, Eleventy）

この記事では、実際に使う YAML の構文をすべて、具体例と初心者がハマりやすい間違いのリストとともに解説します。YAML と JSON を直接比較したい場合は YAML と JSON の違い を参照してください。

YAML を構成する 3 つの要素

YAML ファイルに現れるものは、次の 3 種類のいずれかです。

  • スカラー — 文字列・数値・真偽値・null など、単一の値
  • シーケンス — 順序付きのリスト
  • マッピング — キーと値のペア

これらは自由に入れ子にできます。マッピングがリストを含むことも、リストがマッピングを含むこともできます。これだけで、JSON と互換のある構造ならすべて表現できます。

インデント規則

YAML の階層構造はインデントで表現します。覚えておくべきルールはいくつかあります。

  • スペースのみを使う。タブ文字は多くのパーサーで構文エラー
  • インデント幅を決めたら一貫させる（通常は 2 スペース）
  • 同じ階層の要素は同じインデントにそろえる
  • 構造は閉じ括弧ではなくインデントで決まる

シンプルな有効例です。

database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

database はマッピングで、host、port、credentials を含みます。credentials はさらに入れ子のマッピングです。2 スペースのインデントで構造がひと目でわかります。

キーバリュー（マッピング）の書き方

マッピングは key: value の形式で書きます。コロンの後には半角スペースが必要です。key:value と書くと 1 つの文字列として扱われ、マッピングにはなりません。

name: Alice
age: 30
is_admin: true
bio: null

キーは通常は単純な文字列ですが、クォートすればスペースを含めることもできます。

"full name": Alice Cooper

値にはスカラー・シーケンス・マッピングなど YAML のどの型でも置けます。

リスト（シーケンス）の書き方

シーケンスは行頭に - （ハイフン＋半角スペース）を置きます。

fruits:
  - apple
  - banana
  - cherry

リストには入れ子のマッピングも入れられます。

users:
  - name: Alice
    role: admin
  - name: Bob
    role: editor

ハイフンが新しいリスト項目の開始を示し、次のハイフンまでの内容がその項目に属します。

JSON に近いインライン（フロー）記法もあります。

fruits: [apple, banana, cherry]
users: [{name: Alice, role: admin}, {name: Bob, role: editor}]

フロー形式は短いリストでは便利ですが、データが大きくなると読みにくくなります。現実のファイルではブロック形式を使うのが無難です。

文字列とクォート

YAML の文字列はほとんどの場合クォートなしで書けます。

greeting: Hello, world

クォートが必要なのは次のようなケースです。

  • 別の型として解釈されてしまう場合: version: "1.0"・country: "NO"・postal_code: "07030"
  • 値が -・:・[・{・|・>・*・&・!・%・@ のような特殊文字で始まる
  • 値にコロン＋スペースが含まれる（マッピングと誤認されるため）
  • \n や \t のようなエスケープシーケンスを使いたい

シングルクォートとダブルクォートの両方が使えます。ダブルクォートはエスケープを解釈し、シングルクォートはそのまま文字として扱います。

escaped: "line1\nline2"
literal: 'line1\nline2'

マルチライン文字列

長いテキストには二つの書き方があります。

リテラルブロック | は改行をそのまま保持します。

description: |
  これが 1 行目です。
  これが 2 行目です。

  空行の後の 4 行目です。

フォールドスカラー > は改行を空白に畳み込むので、ソース中で折り返した長文を 1 行にまとめるのに便利です。

paragraph: >
  この長い文章はソース中で複数行に
  分けて書かれていますが、YAML は
  これを 1 行に畳み込みます。

末尾の改行の扱いは追加記号で制御できます。

  • |- で末尾の改行を 1 つ削る
  • |+ で末尾の空行をすべて残す
  • >- で畳み込み＋末尾改行を削る

数値・真偽値・null・日付

YAML はクォートなしの値から型を推論します。

integer: 42
float: 3.14
negative: -7
boolean_true: true
boolean_false: false
null_value: null
tilde_null: ~
date: 2026-04-13
timestamp: 2026-04-13T09:30:00Z

クォートすれば文字列として固定できます。

version_string: "1.0"    # 数値の 1.0 ではなく文字列
zip_code: "07030"        # 数値の 7030 ではなく文字列

YAML 1.1 では yes・no・on・off も真偽値として扱われます。意図せず変換されてしまった場合は値をクォートしてください。

コメント

コメントは # から行末までです。単独の行にも、値の後ろにも書けます。

# 上流リクエストの最大リトライ回数
retries: 3  # これ以上は上流のタイムアウトを超えてしまう

コメントは設定ファイルにおける YAML の最大の強みのひとつです。「何をしているか」ではなく「なぜこの値なのか」を説明するのに使ってください。JSON に変換するとすべて消えるので、YAML を一次ソースとして保管するのが安全です。

アンカーとエイリアスで再利用する

YAML は & でアンカーを打ち、* でエイリアスを参照できます。<<: のマージキーでマッピングをデフォルト値として取り込めます。

defaults: &defaults
  adapter: postgres
  host: db.internal
  pool: 5

development:
  <<: *defaults
  database: myapp_dev

production:
  <<: *defaults
  database: myapp_prod
  pool: 20

production は defaults を引き継ぎつつ pool を上書きしています。環境ごとの設定をコピペせずに共通化できる、きれいな書き方です。

マルチドキュメント

1 つの YAML ファイルに複数のドキュメントを入れることができます。区切りは --- の行です。

---
kind: Service
name: web
---
kind: Deployment
name: web
replicas: 3

Kubernetes で複数マニフェストを 1 ファイルにまとめるときに使う形式です。JSON にはこれに相当する仕組みがないため、変換時はどちらか一方を選ぶか、外側を配列でラップする必要があります。

よくある間違いと見つけ方

多くの開発者が一度はハマる YAML の落とし穴です。

  • タブ文字でインデントしている — 見えないタブが混入すると分かりにくいエラーになる
  • コロンの後にスペースがない — key:value は 1 つの文字列として扱われる
  • インデントがそろっていない — 同じ階層の要素は同じ幅でそろえる必要がある
  • クォートなしの NO・OFF・YES・ON が真偽値になる（ノルウェー問題）
  • クォートなしの値にコロンが含まれる — time: 10:30 が 60 進数として解釈されることがある
  • ブロック形式とフロー形式の混在でパーサーが混乱する
  • 同じマッピング内で重複キーを使う — 実装依存の挙動になる

こうした間違いを一番早く見つける方法は、パーサーに読ませることです。インストール不要で試すなら、FormatArc の YAML to JSON 変換ツール に貼り付けるだけでチェックできます。正しい YAML なら JSON が即座に表示され、間違っていれば行番号付きのエラーメッセージで問題箇所を指してくれます。

FormatArc でブラウザ内 YAML バリデーション

FormatArc のブラウザ完結ツールは簡易 YAML リンターとしても使えます。

YAML to JSON の変換結果、行番号付きで構文チェックが通った画面

  • YAML to JSON → — YAML を貼り付けて JSON を得る。エラー時は行番号付きで表示
  • JSON to YAML → — JSON から出発して YAML の形を学びたいときに
  • JSON Formatter → — 変換結果の JSON を整形・エラー表示する

すべてブラウザで完結します。内部の設定ファイルやシークレットをデバッグ中に貼り付けても、データは手元から出ません。

よくある質問

YAML のインデントにタブを使えますか?

使えません。YAML 仕様はスペースのみを許容しており、タブ文字は多くのパーサーで構文エラーになります。.yml や .yaml の編集時は Tab キーで 2 スペースが入るようにエディタを設定してください。

.yml と .yaml の違いは?

違いはありません。どちらの拡張子も YAML パーサーはまったく同じように扱います。公式仕様では .yaml を推奨していますが、.yml も広く使われていて問題ありません。

文字列は必ずクォートすべきですか?

いいえ、基本的にはクォートなしで書けます。クォートが必要なのは、別の型として解釈されてしまう値や、特殊文字 -・:・[・{・|・> で始まる値です。

version: 1.0 と書いたのに 1 になってしまうのはなぜですか?

YAML は 1.0 を浮動小数点数としてパースし、一部のツールはそれを 1 としてシリアライズし直します。文字列として保持したい場合は version: "1.0" のようにクォートしてください。

インデントのスペース数はいくつが正解ですか?

2 スペースが慣習です。Kubernetes、Docker Compose、GitHub Actions など、ほとんどの例が 2 スペースを使っています。4 スペースでも動きますが、1 つのファイル内では必ず統一してください。

インストールせずに YAML を検証する方法は?

FormatArc の YAML to JSON 変換ツール に貼り付けるだけで検証できます。有効な YAML なら即座に JSON が出力され、無効なら行番号付きのエラーメッセージが表示されます。

1 つのファイルに複数の YAML ドキュメントを入れられますか?

入れられます。区切りは --- だけの行です。Kubernetes でマニフェストをまとめるときの標準的な形式です。1 ファイルにいくつでもドキュメントを並べられます。

関連記事

まとめ

  • YAML は括弧ではなくインデントで構造を表現します
  • インデントはスペースのみで、一貫させることが重要です
  • 文字列は誤解釈されるときだけクォートします
  • コメント・マルチライン・アンカーで設定ファイルを読みやすくできます
  • 構文の検証は FormatArc の YAML to JSON ツール に貼り付けるのが最速です

関連ツール

YAML → JSON