YAMLとJSONを変換するときの注意点

YAMLとJSONは何が違うか

YAML 1.2はJSONとの互換性を意識して設計されていますが、両者の表現力は同じではありません。JSONは値をオブジェクト、配列、文字列、数値、真偽値、nullとして表します。YAMLにはコメント、複数行文字列、アンカーとエイリアス、明示的なタグなど、JSONに直接対応しない表現があります。

そのため、変換に成功しても元の文書を完全に復元できるとは限りません。

YAMLからJSONで失われる可能性があるもの

コメントと書式

JSONのデータモデルにはコメントがありません。YAML内の説明コメント、引用符の選び方、改行のスタイル、空行などは通常失われます。設定ファイルのコメントが運用手順を兼ねている場合、変換前のYAMLも保存してください。

アンカーとエイリアス

YAMLではアンカーを使って同じ値を再利用できます。JSONへ変換すると、多くの実装は参照先の値をそれぞれ展開します。変換後のJSONから、元の共有構造を復元することはできません。

型の自動判定

引用符のない値は、ローダーのスキーマによって数値、真偽値、日付、文字列などに解釈されます。たとえば識別子の 0012 や文字列として保持したい true は、意図しない型になる可能性があります。型を変えたくない値は明示的に引用してください。

JSONに向かないキー

JSONオブジェクトのキーは文字列です。YAMLで数値や複合値をキーに使っている場合、JSONへの変換で文字列化されたり、変換自体が失敗したりします。

変換前後を確認する手順

1. 元ファイルを保存します。
2. YAMLにコメント、アンカー、タグ、複数文書区切りがないか確認します。
3. YAMLからJSONへ変換します。
4. 識別子、日付らしい値、真偽値らしい文字列の型を確認します。
5. 必要ならJSON整形アプリで構文と全体構造を確認します。
6. 利用先のアプリケーションで検証してから置き換えます。

たとえば次のYAMLでは、enabled は真偽値、code は文字列として扱いたい値です。

enabled: true
code: "0012"
items:
  - red
  - blue

期待するJSONは次の形です。

{
  "enabled": true,
  "code": "0012",
  "items": ["red", "blue"]
}

JSONからYAMLへ変換するとき

JSONからYAMLへの変換は比較的素直ですが、生成されたYAMLにコメントや運用上の説明が自動で加わるわけではありません。読みやすさのために書式を調整しても、値の型を変えないよう注意してください。また、JSONで同名キーが重複していた場合、読み込み時点ですでに値が失われている可能性があります。

参考資料

• YAML 1.2.2 Specification
• RFC 8259: The JavaScript Object Notation