JSON・YAML・XMLの違いと、変換で失われるもの
JSON、YAML、XMLはデータモデルが異なるため、相互変換は書き方の置き換えではなく、規則に基づく対応付けです。コメント、アンカー、属性、配列の形、値の型が、変換で最も失われやすい部分です。
ConvertBox公開
同じデータの三つの書き方ではなく、三つのデータモデル
JSON、YAML、XMLは、同じデータを別の書き方で表すだけの形式として紹介されがちです。実際にはそれぞれ独自のデータモデルを持ち、モデルが食い違う箇所では変換ツールが規則を決めなければなりません。JSONの値はちょうど6種類です。YAML 1.2はJSONで表現できるものをすべて表現でき、JSON文書がそのまま有効なYAMLになるよう設計されたうえで、コメント、参照、複数の文字列記法が加わっています。XMLは文書のための形式です。名前付きの要素が属性とテキストを持つ木構造であり、数値、真偽値、配列という概念は文法にありません。
| JSON | YAML | XML | |
|---|---|---|---|
| 値の型 | 文字列、数値、真偽値、null、配列、オブジェクト | JSONと同じ型を、引用符のない値の書き方から推論 | テキストのみ。型はスキーマか読み手が決める |
| コメント | なし | #から行末まで | <!-- ... --> |
| 属性 | なし | なし | あり:<user id="7"> |
| ブロックの再利用 | なし | アンカーとエイリアス:&base、*base | DTDの実体参照のみ |
| テキストとマークアップの混在 | 不可 | 不可 | 可:<p>Hello <b>world</b></p> |
| 構文上の規則 | 二重引用符のみ、末尾のカンマは不可 | インデントが構造を表し、タブではインデントできない | すべてのタグを閉じ、ルート要素は一つだけ |
パーサーの厳格さと、間違いが隠れる場所
JSON(RFC 8259)は三つの中で最も書き方に厳しい形式です。キーと文字列には二重引用符が必要で、末尾のカンマはエラーになり、コメントは存在しません。その代わり、文書は解析できるか、はっきり失敗するかのどちらかです。当サイトのJSONフォーマッターが結果の代わりにエラーを表示するときは実際に不備があり、原因はたいてい末尾のカンマ、一重引用符、コメント、またはJavaScriptコンソールから貼り付けたNaNのような値です。
XMLも整形式であることについては同じくらい厳格です。すべてのタグを閉じ、属性値を引用符で囲み、ルート要素をちょうど一つにする必要があります。さらにXSDなどのスキーマ言語を使えば、正しい要素が正しい順序と型で現れるかまで検証できます。これはJSONにもYAMLにも標準では備わっていません。YAMLは逆です。書くのは簡単ですが、構造がインデントで決まるため、2文字分余計に字下げした行も有効なYAMLのまま別の意味になり、警告は出ません。YAMLファイルをJSONに変換すると、パーサーが実際にどう解釈したかを確認できます。波括弧と角括弧が入れ子を明示するからです。
それぞれの形式が自然に選ばれる場面
- JSONはプログラム同士のやり取りに使います。Web API、ブラウザーのストレージ、ログのレコード、パッケージのマニフェストなどです。主要な言語はどれも標準で解析でき、型の種類がプログラムの扱う型と一致します。
- YAMLは人が手で編集するファイルに使います。Kubernetesのマニフェスト、Docker Composeファイル、CIパイプラインの定義、Ansibleのプレイブックなどです。コメントとアンカーのおかげで、長い設定も読みやすく保てます。
- XMLは文書と、スキーマで決められたデータ交換に使います。SOAPサービス、RSSやAtomのフィード、SVG、.docxや.xlsxの内部ファイルがXMLです。テキストとマークアップが混在する場合や、受け取る側がXSDで検証する場合に選びます。
- 目安はこうです。プログラムが書いてプログラムが読むならJSON、人が保守するならYAML、規格や相手先が要素名を指定しているならXMLです。
YAMLの型推論とノルウェー問題
YAMLは引用符のない値の型を書き方から判断し、その規則はバージョンによって異なります。YAML 1.1はyes、no、on、offとその大文字表記を真偽値として扱うため、国コードの一覧にノルウェーを表すNOがあると、falseとして読み込まれます。YAML 1.2ではtrueとfalseだけが残りましたが、PyYAMLをはじめ、広く使われているパーサーにはいまも1.1の規則に従うものがあります。同じファイルがツールによって違う意味になりうるということです。
対策はどこでも同じで、別の型として読まれうる文字列を引用符で囲みます。当サイトのJSON to YAML変換ツールは出力時にこれを行います。'012'、'true'、'2024-01-01'のような文字列に加え、YAML 1.1のyes、no、on、offも一重引用符で囲むため、結果は古いパーサーでもそのまま読めます。
| 引用符なしのYAML | YAML 1.1のパーサー(PyYAMLなど) | ConvertBoxのYAML to JSON(js-yaml、YAML 1.2の規則) |
|---|---|---|
| country: NO | false | "NO" |
| enabled: yes | true | "yes" |
| zip: 012 | 10(8進数として解釈) | 12 |
| version: 1.20 | 1.2 | 1.2 |
| released: 2024-01-01 | 日付の値 | "2024-01-01T00:00:00.000Z" |
JSONとYAML:往復変換で落ちるもの
JSONからYAMLへの変換ではデータは失われません。どのJSONの値にも対応するYAMLの書き方があるからです。変わりうるのは付随的な部分です。当サイトの変換ツールはまずブラウザーのJSONパーサーで入力を読むため、1.0は1と書かれ、2^53(9007199254740991)を超える整数は末尾の桁が変わり、重複したキーは最後の一つにまとめられ、整数に見えるキーはオブジェクトの先頭に移動します。
情報が消えるのはYAMLからJSONへの方向です。コメントは落ちます。アンカー(&base)とエイリアス(*base)は完全な複製に展開され、マージキー(<<: *base)はマージ済みの内容になるため、JSONとしては正しくても、五つのサービスが一つのブロックを共有していたという事実は残りません。ブロックスカラーは通常の文字列になり、文字列以外のキーは文字列になり、.infと.nanはJSONに該当する数値がないためnullになります。また、YAML to JSONツールは---で区切られた複数文書のストリームと、CloudFormationの!Refのようなアプリケーション固有のタグを受け付けないため、文書を一つずつ変換してください。原本はYAMLファイルとして管理します。JSONに変換して戻すと同等のデータにはなりますが、元のファイルには戻りません。
JSONとXML:属性、繰り返し要素、型
XMLには配列がなく、JSONには属性がありません。そのため変換ツールはそれぞれ独自の規約を採用しており、規約はツールによって異なります。表は当サイトの二つの変換ツールが使う規約です。
JSON to XMLの方向では、全体をrootという名前の要素で包み、属性は生成せず、要素名に使えない文字をアンダースコアに置き換えます。first nameというキーはfirst_nameになり、日本語で書いたキーはすべてアンダースコアになります。SOAPやRSSのように要素名、名前空間、属性が決まっている形式に合わせるには、結果を手で修正するか、対応付けを明示できるライブラリを使う必要があります。
| 入力 | 出力 | 注意点 |
|---|---|---|
| JSON "tag": ["a", "b"] | <tag>a</tag> <tag>b</tag> | 配列は包む要素なしで繰り返し要素になる |
| XML <tag>a</tag>が一つだけ | "tag": "a" | 要素が一つなら文字列、二つなら配列 |
| JSON "age": 30, "ok": true | <age>30</age> <ok>true</ok> | JSONに戻すとどちらも文字列の"30"と"true" |
| JSON "items": [] | 何も出力されない | 空の配列は痕跡が残らない |
| XML <user id="7">Ann</user> | "user": {"@attributes": {"id": "7"}, "#text": "Ann"} | 属性は予約されたキーの下に保持される |
| XML <p>Hello <b>big</b> world</p> | "p": {"b": "big"} | 子要素の間にあるテキストは捨てられる |
実際のファイルを変換する前に確認すること
- 数値、真偽値、日付に見えるYAMLの文字列は引用符で囲みます。バージョン番号、郵便番号、国コード、時刻が該当します。
- 15桁を超える識別子は文字列として扱います。JavaScriptベースのツールは2^53を超える整数を丸めます。
- XMLをJSONに変換した後は、繰り返す可能性のある要素について、単一の値と配列の両方を受け付けるコードを書きます。
- 署名やチェックサムがバイト列そのものを対象にしている場合は、整形や変換の前に検証します。再シリアライズするとバイト列が変わるためです。