CreaTools LogoCreaTools
Tech Notes
JSON ⇄ YAML Converter

YAML構文の基本｜インデント・配列・複数行の書き方

2025-01-03

この記事を読むと

YAMLファイルを読み書きできるようになる。インデントや配列の書き方で迷わなくなる。

ただし、YAMLには「静かに壊れる」罠がある。基本文法を覚えた後は YAMLの暗黙型変換の罠 を必ず読むこと。

基本構文

key: value

コロンの後にスペースが必要。 スペースがないとパースエラー。

# NG: スペースがない
key:value

# OK
key: value

ネスト（インデント）

parent:
  child: value
  another:
    deep: nested
ルール守らないと
スペース2つが標準構造が壊れる
タブは使えないパースエラー
インデントを揃える構造が意図と違う
# NG: インデントがずれている
parent:
  child: value
   another: broken  # ← 1スペース多い

# OK
parent:
  child: value
  another: correct

インデントのズレはエラーにならないことがある。静かに構造が壊れる。

配列

# ブロックスタイル（推奨）
items:
  - apple
  - banana
  - orange

# フロースタイル（JSON風）
items: [apple, banana, orange]

オブジェクトの配列

users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

- の後のインデントに注意。 揃っていないと構造が壊れる。

文字列

# クォートなし（多くの場合OK）
name: hello world

# シングルクォート（エスケープしない）
path: 'C:\Users\name'

# ダブルクォート（エスケープする）
message: "Line1\nLine2"

⚠ クォートなしの危険

# これらは文字列にならない
enabled: on    # → true（boolean）
enabled: off   # → false（boolean）
port: 01       # → 1（数値）

文字列にしたいなら必ずクォートで囲む。

複数行文字列

# リテラル（改行を保持）
script: |
  echo "hello"
  echo "world"

# 折りたたみ（改行をスペースに）
description: >
  This is a long
  description that
  wraps to one line.
記法改行用途
|保持スクリプト、コード
>スペースに変換長い説明文

数値

integer: 42
float: 3.14
negative: -10
scientific: 1.2e+5

⚠ 先頭ゼロの危険

# 危険
port: 080   # → 8進数として解釈される可能性
version: 01 # → 1（数値）

# 安全
port: "080"
version: "01"

boolean

# true
enabled: true

# false
disabled: false

⚠ on/off/yes/no の危険

# これらもbooleanになる（危険）
- on     # → true
- yes    # → true
- off    # → false
- no     # → false

# 文字列にしたいなら
- "on"
- "yes"

true/false だけを使う。on/off/yes/no は避ける。

null

value: null
value: ~
value:    # 空も null

コメント

# 行コメント
name: value  # 行末コメント

JSONにはコメントがない。YAMLの利点の一つ。

アンカーとエイリアス

同じ値を再利用する。

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

&defaults で定義、*defaults で参照。

複数ドキュメント

---
document: 1
---
document: 2

--- で区切る。

よくあるミスと結果

ミス結果対策
コロン後のスペース忘れパースエラーkey: value
タブでインデントパースエラースペース2つ
インデントずれ構造が静かに壊れるエディタ設定を確認
on/off を文字列で使うbooleanになる"on" とクォート
先頭ゼロ数値になる"01" とクォート

まとめ

ルール守らないと
インデントはスペース（タブ不可）パースエラー
スペース2つで揃える構造が壊れる
配列は - で始める—
複数行は | か >—
on/off/yes/no は避けるbooleanになる
迷ったらクォートで囲む型変換事故を防げる

YAMLはエラーを出さずに「別の意味」として解釈することがある。ルールを守らないと静かに壊れる。

関連記事