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.

よくある質問 / FAQ

JSONで表現できるものはすべてYAMLで表現できる?

はい。YAML 1.2はJSONの上位互換として設計されており、構文的に有効なJSONはそのまま構文的に有効なYAMLでもあります。逆にYAMLにはコメント・アンカー参照・複数ドキュメントなどJSONにない機能があるため、YAML→JSON変換ではこれらの情報が失われることがあります。

Norway Problemとは何?

YAML 1.1のパーサーが、クォートなしの no や yes、on、off といった文字列をブール値と誤解釈してしまう有名なバグの通称です。国名コード「NO」(ノルウェー)がfalseとして解釈されてしまう事例に由来します。文字列として保持したい値は必ずクォートで囲むのが回避策です。

Why does my YAML file break when I use tabs?

The YAML specification disallows tab characters for indentation — only spaces are valid. A tab accidentally pasted into an indented block typically causes a 'found character that cannot start any token' or similar parse error. Configure your editor to insert spaces instead of tabs in .yaml/.yml files.

JSON配列はYAMLでどう表現される?

JSONの配列はYAMLのシーケンス(sequence)に対応し、各要素の先頭にハイフンとスペース(- )を付けてインデントで表現します。フロースタイル(JSONと同じ[a, b, c]の1行表記)もYAMLの構文として有効ですが、可読性の観点からブロックスタイル(改行+ハイフン)が一般的に好まれます。

JSONにコメントを書けないのはなぜ?

JSONの仕様(RFC 8259)にはコメント構文が定義されていないため、標準準拠のパーサーはコメントを含むJSONをエラーにします。設定ファイルにコメントを残したい場合は、コメントをサポートするYAMLやJSON5・JSONCのような拡張形式を使うのが実務上の解決策です。

関連ツール / Related tools

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

関連ガイド / Related guides

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