TOML を JSON に変換

TOML は Python や Rust のパッケージングで長く標準になっていますが、リポジトリまわりのツール群がそれに追いついていないことがあります。jq しか使えない CI のステップや、Cargo.toml からバージョンを読み取る必要がある Node のスクリプト、200 のリポジトリの依存関係を数えるダッシュボード。これらはすべて JSON なら読めても、新しい依存関係を足さずには TOML を読めません。

この変換はそうした場面のためのもので、2 つのデータモデルがほぼ完全に重なるため、きれいに動きます。TOML は入れ子と配列を持つキーと値のテーブルであり、それは入れ子と配列を持つ JSON オブジェクトそのものです。興味深いのは、TOML が知っていて JSON が知らない 4 つの点です。

角括弧で書かれた見出しは入れ子のオブジェクトになり、ドット区切りの見出しは何段も入れ子になります。ツール用の見出しの下にリンター用の見出しがあれば、オブジェクトの中にオブジェクトができ、JSON のパスは見出しとそのまま一致します。構造自体を解釈し直す必要はありません。

二重角括弧の見出しはテーブルの配列で、出現するたびに 1 つのオブジェクトを持つ JSON の配列になります。Python パッケージの作者情報や Rust クレートのバイナリ、ビルドのターゲットはこの形で表され、いちばん心配されがちでいちばん心配しなくてよい構造です。順序は保たれます。

このジャンルの中で本物の時間型を持つのは TOML だけです。オフセット付き日時、ローカル日時、ローカルの日付、ローカルの時刻が仕様に含まれ、パーサーはそれらを日付として返します。JSON には日付型がまったくないため、それぞれが文字列になります。

値そのものは 1 か所を除いて保たれます。オフセット付き日時は UTC に正規化されず、オフセットを保持したまま渡ります。ローカルの日付はそのまま渡ります。ローカルの時刻には元になかったミリ秒の要素が付き、朝 8 時と書かれた時刻に小数部分が付きます。後段でこの文字列を解析せず比較しているものがあると、その余分な部分のせいで比較がずれることがあります。

TOML 1.0 は 64 ビットの符号付き整数を扱えることを実装に求めていますが、JSON の数値は IEEE の倍精度浮動小数点で、正確に表せるのはおよそ 900 兆までです。その範囲を超える整数を持つ TOML はまったく正当なファイルですが、パーサーは間違った数値の JSON を出す代わりに、その整数を正確に表せないというエラーで止まります。

これは正しい振る舞いで、なんとなく回避するのではなく理解しておく価値があります。静かに丸められた識別子は、何週間か後に一致しない結合として表面化するバグです。もし TOML の中に大きな値——スノーフレーク ID や大きな連番、ナノ秒単位の整数タイムスタンプなど——があるなら、元の TOML の側でそれを文字列として括ってください。もともと数量ではなかったものであり、そう扱うことで下流のすべてが正しくなります。

TOML の浮動小数点には inf と nan がリテラルとして含まれます。JSON にはどちらもなく、シリアライザーは両方を null として書き出します。これは JavaScript の標準的な挙動ですが、何も警告なく情報が失われます。上限として設定された無限大と、設定されていない上限が、JSON では同じものになってしまいます。

もう少し目立ちにくい損失は型の区別です。TOML は整数と浮動小数点を区別するので、1 と 1.0 は異なる型の異なる値であり、スキーマやアプリケーションはその違いに依存できます。JSON には数値の型が 1 つしかなく、1.0 は 1 として書き出されます。ある値が浮動小数点として宣言されていたことを JSON 側の利用者が知る必要があるなら、その情報は別の方法で伝える必要があります。ファイルの中には残っていません。

テーブルとキーは TOML が宣言した順序のまま出力されるため、変換後のファイルは読みやすく、2 回の変換結果を比較する差分も意味を持ちます。出力は 2 スペースのインデントで、末尾には改行が付きます。

例外は数値のキーです。年やポート番号でインデックスするような設定に現れる、数値である引用符付きの TOML キーは、そのオブジェクトの他のキーより前に並べ替えられ昇順にソートされます。JavaScript のオブジェクトが整数風のキーを扱う順序に合わせたためで、この変換で唯一、元の並びどおりに読めない箇所です。

出力は普通の JSON なので、フラグなしで jq がそのまま読み込めます。プロジェクトのバージョンを取り出す、依存関係の名前を一覧する、あるツールのセクションが存在するかを確認する——どれも 1 行の式で済み、TOML ファイルを grep するだけだったシェルスクリプトを、きちんと問い合わせできるものに変えられます。

JSON Schema は成熟しており広く実装されている一方、TOML には仕様の中にスキーマ言語がありません。変換してから検証することは、多くのリポジトリにわたって社内ルールを強制する実際的な方法になります。すべてのパッケージがライセンスを宣言していること、すべてのクレートが edition を固定していることなど、TOML のままでは確認できないことが確認できるようになります。

TOML はコメントに対応しており、それが多用されます。依存関係を固定している理由、回避策の横にあるチケット番号、ある設定がどの環境に適用されるかを説明するブロック。JSON には RFC 8259 の下でコメントの構文がなく、これらは一切渡りません。

この非対称性が両者の関係を決めます。TOML は人が編集しレビューするファイルであり、JSON はそれを何かが読む必要があるたびに生成されるものです。JSON を TOML と一緒にリポジトリへコミットすると、いずれずれる二重の真実ができてしまいます。ビルドのステップで生成するなら、そのずれは起きません。