JSON to YAML変換ガイド - 構造対応表と落とし穴

Kubernetesのマニフェスト、GitHub Actionsのワークフロー、docker-composeの設定―― インフラ周りの設定ファイルの多くはYAML形式である一方、APIレスポンスや内部データは JSONで扱うことが多く、json to yaml の変換が必要になる場面は頻繁にあります。 両者は表現力こそ近いものの、インデントの厳密さや yes/no の 解釈など、変換時にハマりやすい違いがあります。この記事では構造対応表と主要な落とし穴を整理します。

JSON and YAML can represent the same data, but converting between them isn't purely mechanical. This guide maps JSON constructs to their YAML equivalents, covers indentation and quoting pitfalls (including the infamous "Norway Problem"), and shows conversion code in three languages.

TL;DR

• 有効なJSONはそのまま有効なYAML(YAML 1.2はJSONの上位互換)
• JSONオブジェクト→YAMLマッピング、JSON配列→YAMLシーケンス
• YAMLのインデントはスペースのみ。タブは構文エラーの原因になる
• クォートなしのyes/no/on/offはブール値と誤解釈されうる(Norway Problem)
• JSONにはないコメント・アンカーはYAML変換後に手で追加する必要がある

1. 構造の対応表 / Structural mapping

2. 変換例 / Side-by-side example

// JSON
{
  "name": "devtoolspot",
  "version": 2,
  "public": true,
  "tags": ["dev", "tools"],
  "owner": {
    "email": "hello@example.com",
    "verified": null
  }
}

# YAML(同じデータ)
name: devtoolspot
version: 2
public: true
tags:
  - dev
  - tools
owner:
  email: hello@example.com
  verified: null

Notice how YAML drops the braces, brackets, and most quotes — structure is conveyed purely through indentation and the leading -for sequence items, which is both YAML's biggest readability win and its biggest footgun.

3. よくある落とし穴 / Common pitfalls

3-1. インデントはスペースのみ

YAMLの仕様上、インデントにタブ文字は使えません。エディタの設定によっては 自動でタブが挿入され、貼り付け直後は正常に見えても保存後にパースエラーになることがあります。

3-2. Norway Problem(yes/noの誤解釈)

YAML 1.1の仕様では、クォートなしの yes、no、on、off、y、n などがブール値として解釈されます。 国名コード「NO」(ノルウェー)を文字列として書いたつもりがfalse になってしまう事例が有名で、「Norway Problem」と呼ばれています。

# 危険な例
country: NO       # ← ブール値 false と解釈される可能性がある(パーサー依存)

# 安全な書き方
country: "NO"      # 文字列として明示

3-3. 数値の先頭ゼロ

zip: 07001 のように先頭に0が付く値をクォートなしで書くと、 パーサーによっては数値として解釈され先頭の0が失われることがあります。 郵便番号や電話番号などはクォートで囲み文字列として明示してください。

3-4. YAMLのみの機能はJSON変換時に失われる

YAMLのコメント(#)、アンカー/エイリアス (&anchor / *aliasによる参照の再利用)、複数ドキュメント(---区切り)はJSONに存在しない機能のため、 YAML→JSON変換時にはこれらの情報が失われるか展開された値に置き換わります。

4. 言語別の実装例 / Code examples

JavaScript / Node.js (js-yaml)

import yaml from "js-yaml";

const obj = JSON.parse(jsonString);
const yamlString = yaml.dump(obj);        // JSON -> YAML
const backToObj = yaml.load(yamlString);  // YAML -> JSON相当のオブジェクト

Python (PyYAML)

import json, yaml

data = json.loads(json_string)
yaml_string = yaml.dump(data, allow_unicode=True, sort_keys=False)  # JSON -> YAML
back_to_data = yaml.safe_load(yaml_string)                          # YAML -> dict

Go (yaml.v3)

import (
    "encoding/json"
    "gopkg.in/yaml.v3"
)

var data map[string]interface{}
json.Unmarshal(jsonBytes, &data)
yamlBytes, _ := yaml.Marshal(data) // JSON -> YAML

まとめ / Summary

json to yamlの変換自体は「オブジェクト→マッピング、配列→シーケンス」という単純な対応関係で 説明できますが、タブ禁止のインデント規則、Norway Problem、先頭ゼロの数値誤解釈という 3つの落とし穴を知らずに手動変換すると、意図しないデータ破損につながります。 設定ファイルの変換は自動変換ツールに任せるのが確実です。

Converting JSON to YAML maps cleanly — objects become mappings, arrays become sequences — but three gotchas bite developers who convert by hand: YAML forbids tabs for indentation, unquoted yes/no/on/off can silently become booleans (the Norway Problem), and unquoted values with leading zeros can lose them. Let a proper converter handle quoting so the resulting YAML round-trips safely.

関連ツール / Related tools

• JSON / YAML Converter — JSON⇔YAMLの相互変換
• YAML Formatter / Validator — YAMLの検証・整形
• JSON Formatter & Validator — JSONの整形・検証

関連ガイド / Related guides

• YAMLインデントエラーの直し方
• JSON Schemaで型を保証する基本