設定ファイルにおける JSON vs YAML

JSON と YAML は、オブジェクト、配列、文字列、数値、真偽値、null 値という同じデータモデルを表現することが多いです。違いは、人間が編集するファイルと機械生成ワークフローでの振る舞いです。

誰が編集するか、パイプラインがどれだけ厳密である必要があるかに基づいて形式を選びます。

JSON は厳密で予測可能

JSON は、機械がファイルを生成または消費するときに適しています。

• API リクエスト・レスポンスの例。
• パッケージ metadata。
• 生成された設定。
• サービス間のデータ交換。
• どこでも同じ parse 結果になるべきテスト fixture。

厳密な構文は煩わしく感じることもありますが、曖昧さを減らします。文字列には引用符が必要で、カンマは重要であり、parser は概ね一致します。

JSON payload を素早く検証、確認、正規化する必要があるときは JSON Formatter を使います。

YAML は手編集設定に向いている

YAML は人間がメンテナンスするファイルで人気があります。

• Kubernetes manifest。
• GitHub Actions workflow。
• Docker Compose ファイル。
• アプリケーション設定。
• ドキュメントの例。

ネストが深くコメントが重要なとき、読みやすくなります。トレードオフは、インデント、暗黙の型、複数ドキュメントファイルが人を驚かせることがある点です。

適用やコミット前に重要な YAML は YAML Formatter / Validator で確認してください。

YAML が問題を起こす場面

よくある YAML の問題:

• スペースが期待される場所にタブがある。
• on、yes、no が予期せず解釈される。
• 2 つのドキュメントが 1 ファイルに貼り付けられる。
• 見た目は正しいが構造を変えるインデント。
• 自動変換でコメントが失われる。

管理可能ですが、実運用上のリスクは本物です。

JSON が問題を起こす場面

よくある JSON の問題:

• JavaScript からコピーした末尾カンマ。
• 厳密 JSON parser が拒否するコメントの追加。
• 読みにくい escaped 文字列。
• 手編集が難しくなる大きなファイル。

JSON は機械には安全ですが、常に人間に優しいわけではありません。

実践的なルール

厳密な相互運用が重要なら JSON を使います。コメント付きで読みやすい設定を人間が必要とするなら YAML を使います。慎重に変換し、デプロイ前に検証し、2 形式が双方向ですべての詳細を保持するとは限らないと認識してください。