CreaTools LogoCreaTools
Tech Notes
JSON ⇄ YAML Converter

YAML完全ガイド｜文法・罠・JSON比較・docker-compose実践まで

2025-01-03

この記事の役割

「YAMLで設定を書いているが、なぜか動かない」「JSONとどう使い分けるべきか分からない」という人のためのナビゲーション記事です。

YAMLは便利だが、静かに壊れる。エラーを出さずに「別の意味」として解釈される。

この記事でYAML全体像を掴み、用途に応じて詳細記事に進んでください。

結論：YAMLで事故らないための3原則

原則理由
迷ったらクォートで囲むon/off/yes/no は boolean になる
インデントはスペース2つタブは使えない。ズレると構造が壊れる
ポート番号・バージョンは文字列3.10 は 3.1 になる、80:80 は時刻になる

この3つを守るだけで、YAMLの事故の80%は防げる。

YAMLで起きる本番事故

⚠ 静かに壊れる例

入力意図実際の解釈結果
enabled: on文字列 "on"boolean true設定が意図と違う
port: 080文字列 "080"数値 80（または8進数）ポート指定ミス
version: 3.10文字列 "3.10"数値 3.1バージョン違い
country: NOノルウェー国コードboolean falseデータ破損

YAMLはエラーを出さない。間違った値として処理される。

⚠ docker-compose で即死する例

services:
  app:
    ports:
      - 080:80  # ← 8進数として解釈される可能性
    environment:
      FEATURE_FLAG: on  # ← true になる

対策：

services:
  app:
    ports:
      - "080:80"  # クォートで囲む
    environment:
      FEATURE_FLAG: "on"  # クォートで囲む

即決フロー：どの記事を読むべきか

YAMLについて知りたい
        ↓
┌───────────────────────────────┐
│ 基本文法を知りたい？          │
└───────────────────────────────┘
        ↓ Yes
→ [YAML構文の基本](/notes/json-yaml-converter/yaml-syntax-basics)

        ↓ No
┌───────────────────────────────┐
│ on/off/yes/no が勝手に変換    │
│ される問題を解決したい？      │
└───────────────────────────────┘
        ↓ Yes
→ [YAMLの暗黙型変換の罠](/notes/json-yaml-converter/yaml-implicit-type-conversion)

        ↓ No
┌───────────────────────────────┐
│ docker-compose.yml を書く？   │
└───────────────────────────────┘
        ↓ Yes
→ [docker-compose.ymlの書き方](/notes/json-yaml-converter/docker-compose-yaml-guide)

        ↓ No
┌───────────────────────────────┐
│ JSONとYAMLを変換したい？      │
└───────────────────────────────┘
        ↓ Yes
→ [JSON ⇄ YAML変換ツールの使い方](/tech-notes/how-to-use-json-yaml-converter)

JSONとYAMLの選定基準

即決表

観点JSONYAML
人間可読性△◎
厳密性◎△
機械生成◎△
事故耐性◎△
コメント✗✓
複数行文字列面倒簡単

どちらを選ぶか

場面推奨理由
API通信JSON厳密、パース速い
プログラムで生成JSON事故りにくい
CI/CD設定YAMLコメントが書ける
docker-composeYAMLエコシステムの慣習
KubernetesYAMLエコシステムの慣習
人が手書きYAML可読性が高い

JSONを選ぶべき場面（重要）

以下の場合はYAMLではなくJSONを選ぶ：

  • 機械が自動生成するファイル
  • 型の厳密性が必要
  • 暗黙の型変換を避けたい
  • API のリクエスト/レスポンス

YAMLの「親切さ」が事故の元になる場面では、JSONを選べ。

詳細は JSONとYAMLの違い を参照。

変換時の注意

JSON → YAML は安全

問題なく変換できる。

YAML → JSON で失われるもの

失われる要素影響
コメント設定の説明が消える
アンカー/エイリアス重複定義になる
複数行文字列の形式エスケープ文字に変換

型変換で壊れる例

YAMLJSON変換後
enabled: on"enabled": true
port: 01"port": 1
version: 3.10"version": 3.1

このツールは型変換を検出し、警告を表示する。

詳細は JSON ⇄ YAML変換ツールの使い方 を参照。

シリーズ記事一覧

基礎

記事内容到達点
YAML構文の基本インデント、配列、複数行YAMLを読み書きできる
YAMLの暗黙型変換の罠on/off、先頭ゼロ事故を未然に防げる

比較・選定

記事内容到達点
JSONとYAMLの違い構文、用途、落とし穴適切な形式を選べる

実践

記事内容到達点
docker-compose.ymlの書き方サービス、ポート、環境変数本番投入レベルで書ける
JSON ⇄ YAML変換ツールの使い方変換、警告、修正安全に変換できる

よくある事故と対策

事故原因対策
on が true になった暗黙の型変換"on" とクォートで囲む
ポート番号がおかしい数値解釈"80:80" とクォートで囲む
バージョンが違う3.10 → 3.1"3.10" とクォートで囲む
インデントずれで壊れたタブ or スペース数違いスペース2つに統一
構造が意図と違うインデントミスエディタの表示設定を確認

まとめ

判断正解
基本文法YAML構文の基本
型変換の罠YAMLの暗黙型変換の罠
JSON/YAML選定APIならJSON、設定ファイルならYAML
docker-composedocker-compose.ymlの書き方
変換JSON ⇄ YAML変換ツール

YAMLは便利だが、静かに壊れる。迷ったらクォートで囲め。

関連ツール