XML を YAML に変換

XML は文字のおよそ半分を、要素がどこで終わるかを言うために費やします。YAML はそれをインデントで表現するので、同じ文書はかなり短くなり、それぞれの入れ子の階層は目で探す対の記号ではなく、一段の見た目の変化として現れます。Maven の pom や web.config なら、スクロールして探すのと読むのとの違いがそこにあります。

構造そのものは変わりません。すべての要素はキーになり、その子要素は下にぶら下がるマッピングになり、テキストは値になります。並べ替えも要約もされていません。目の前にあるのは同じ文書から句読点を抜いたものであり、それはまさにファイルが何を言っているかを理解したいときに欲しいものです。

属性は @ を頭に付けたキーとして渡り、属性とテキストの両方を持つ要素は、そのテキストを #text というキーの下に格納します。どちらも引用符で囲んで書かれます。YAML は @ を予約された記号として、# をコメントの開始として扱うからです。

見た目は雑音のようですが、これは正しさそのものです。手でファイルを編集するなら、その引用符は残してください。外すと解析に失敗するか、#text の場合は行の残りが静かにコメントとして扱われ、値が失われます。出力を値ファイルの形に組み替えながらキーを打ち直すときも同じことが当てはまります。

これが、この変換をする最大の理由です。XML の diff は悲惨です。一段深いところの変更が何行ものタグとして表示され、ツールによる整形は文書全体を書き換えます。両方の版を変換して YAML で diff すれば、変わった値だけが、その上にキーのパスを見せた状態で一行として表示されます。

ただし一つ注意点があり、それが結果を左右します。繰り返される単一の要素はマッピングに、二つならリストになるので、依存関係を一つ増やしたバージョンはその枝の中身だけでなく形そのものを変えてしまい、diff はそのブロックまるごとが書き換えられたように表示します。これは変換が情報を失っているのではなく、形が本当に変わっているのですが、あらかじめ知っておくと大きな diff を大きな変更として読み違えずに済みます。

接頭辞はキー名の一部として保たれるので、soap: や xsi: を使う文書はコロンを含むキーを生みます。書き出す側はそれらを引用符なしで出力し、同じパーサーで読み戻せば正しく解釈されます。名前空間の宣言自体も属性として残るので、既定の xmlns はルートの引用符付き "@xmlns" キーとして現れます。

ファイルが手元を離れる前に、引用符なしのキーの中のコロンは手で締めておく価値があります。この YAML が別のツールで読まれるなら、そのキーは自分で引用符を付けてください。コストはかからず、誰かがファイルを解析する段になって初めて現れる種類の問題を取り除けます。接頭辞を名前空間の URI に解決する仕組みは何もないので、同じ名前空間に別の接頭辞を使う二つの文書は、互いにきれいに diff できない YAML を生みます。

数字に見える値は、要素のテキストでも属性でも解析されます。Maven のバージョン 4.13.2 はドットが二つあり数値になれないので文字列のままですが、住所やパスも同じです。version 属性に書かれた 1.0 は 1 になり、007 と書かれたゼロ埋めの値は 7 になります。

実行されるのではなく読まれる設定ファイルなら、被害は見た目に限られますが、それでも重要です。1.0 のはずのスキーマバージョンがレビューで 1 と表示されれば、誰かがそれを疑うか、もっと悪ければそのままコピーしてしまいます。出力の中で数値らしく見える値は一度目を通してください。人間の目以外の場所に行くなら、識別子として意図されていたものは引用符で囲んでください。

改行を含む値はブロックスカラー ── パイプ記号の下にインデントされたテキスト ── として書かれ、一行にエスケープして押し込むより読みやすく保たれます。長い一行の値はそのまま折り返されずに書かれます。どちらも読むためのファイルにふさわしい選択です。

空、あるいは自己終了する要素は空文字列になり、引用符の対として書かれます。XML は空の要素と何も入っていない要素を区別しないので情報は失われませんが、空文字列は長いファイルの中では見た目に見落としやすいものです。設定ファイルの未設定の値を監査しているなら、目で追うより空の引用符を検索してください。

XML はコメントを持ち、YAML もコメントを持ちますが、どのコメントも生き残りません。パーサーはそれを読み飛ばし、何も書き戻しません。ペイロードなら関係ありませんが、ビルドファイルでは最大の損失になりがちです。固定されたバージョンの上にあるコメントはたいてい、なぜそこに固定したのかを示す唯一の記録だからです。

この落とし穴を避ける運用は、YAML を読むための控えとして扱い、XML を正本として残すことです。もし YAML のほうを正本にする ── Ansible や Helm チャートへの本当の移行 ── のであれば、コメントを移す作業を、XML を削除して理由が失われてしまう前の工程として組み込んでおいてください。

変換された設定は、まだ値ファイルや変数セットではありません。@ キーや #text キー、ルートの名前空間宣言、宣言行由来の ?xml キーといった XML の名残を運んでいて、それらは渡す先にとって意味を持ちません。それらを削るのが最初の一手です。

二つ目は命名です。XML の要素名は、背後にスキーマがあった時代の名残で冗長になりがちで、YAML の設定ではもっと短く平坦な名前が求められます。どちらの作業も手作業で、それこそが本当の移行です。変換は読める出発点をくれるだけで、タグの壁を渡してくれるわけではありません。

理解する、レビューする、比較することが目的なら変換してください。YAML は短く、構造はひと目で分かり、ファイルを落とせばブラウザーの中で一瞬で処理が終わります。手渡された設定ファイルを変更する前に把握しておく必要があるときの良い習慣です。

スキーマで検証される、署名されている、あるいは XML を読むツールが消費するファイルなら変換しないでください。その場合 XML こそが正本であり、YAML のコピーはもう一つの真実になって最初のものから乖離していきます。読むなら YAML として、変更するなら XML として扱ってください。