設定ファイルの JSON vs YAML：構文、落とし穴、選び方

问题

YAML が利便性を発揮する場面、YAML が知らずにデータを変換してしまう場面、JSON が機械間インターフェースの境界であり続ける理由、そして設定ファイルの実用的な選択基準を解説します。

ステップ

1. 1. The ergonomic difference

   YAML trades JSON's punctuation for indentation: no braces or quotes for most values, comments (#) are first-class, anchors (&base) and aliases (*ref) deduplicate repeated blocks, and multi-line strings are native (| and >). JSON has none of these — but what JSON lacks in comfort it returns in predictability: the grammar fits on a business card, every parser agrees on it, and diffs are purely structural.

2. 2. The coercion pitfalls (the Norway problem)

   YAML 1.1 interprets unquoted scalars against a type table, and the surprises are legendary: no becomes false (the Norway problem — country code NO silently turning into a boolean), version 1.10 becomes the number 1.1, on/off/yes/true/false are all booleans, and leading zeros can make values octal. YAML 1.2 fixed the worst of it (no is now the string no in core schema), but parsers are inconsistent about which version they implement — which is exactly why quoting version strings, country codes, and anything starting with 0 is mandatory discipline in real YAML files.

3. 3. Where each one wins

   JSON wins at machine boundaries: API payloads, log events, IPC, anything two independent programs must parse identically — its spec is unambiguous and its parsers are the most-tested code in the ecosystem. YAML wins where humans maintain the file: Kubernetes manifests, CI pipelines (GitHub Actions, GitLab CI), docker-compose — places where comments, multi-line strings, and anchors reduce real maintenance cost. Note the pattern: the industry converged on 'YAML at the human edge, JSON underneath' — Helm charts are YAML templates rendering JSON objects, and most YAML tools parse to the same data model JSON uses.

4. 4. The migration checklist

   When converting between the two (in either direction), verify four things: quote anything that looks numeric or boolean; expand or deliberately preserve anchors and aliases (JSON cannot represent them); check for duplicate keys (legal in lax YAML parsers, invalid in JSON, silently last-wins in others); and diff the parsed data models, not the text — the files can look right while the values have changed type. A formatter that validates JSON before conversion catches syntax errors at the first step instead of after deployment.

期待される結果

YAML の暗黙の型強制(ノルウェー問題など)が設定を壊す箇所を特定し、マシン間連結の境界として JSON を選ぶ根拠を説明し、フォーマット移行前にチェックリストを適用できるようになります。