JSON を TOML に変換

JSON にはコメントがありません。これは見落としではなく仕様書に明記されていることで、JSON で書かれた設定の保守が不快になる最大の理由です。タイムアウトが 45 秒である理由を、その 45 の隣に書いておく場所がないのです。TOML は 8 年間の 0.x 版を経て 2021 年 1 月に 1.0 に到達し、いまでは Cargo や pyproject.toml、Hugo の設定形式になっていますが、コメントを持っています。これがこの変換のほぼすべての動機です。

2 つ目の理由は平坦さです。3 段の入れ子を持つ JSON の設定は、3 段の中括弧と大量のインデントになります。同じものを TOML にすると、[server.tls.client] という見出し行と、その下の短いキーの一覧になります。データは何も変わっていませんが、レビュアーが 1 つの値の移動を見るときの差分は、再インデントされたブロックではなく 1 行になります。

TOML の文書はテーブルです。JSON の文書のように配列で始めることができないので、最外殻の文字が角括弧であるファイルは、対応させる先がありません。この変換は失敗するのではなく対処します。オブジェクトではない値は items というキーの下に包まれ、出力は [[items]] から始まります。

これはファイルを有効に保ちますが、答えというより仮の置き場です。そのリストがファイルを読むツールにとって dependencies と呼ばれるべきか、servers と呼ばれるべきか、plugins と呼ばれるべきかを、どんな変換ツールも知りようがありません。最初の行のキー名をリネームすれば、ファイルの残りはすでに正しくなっています。1 単語の編集で済み、隠すのではなくあえて目立つようにしてあります。

これは毎回確認する価値のある落とし穴です。TOML には null リテラルがなく、書き出す処理もそれを新たに作り出しません。JSON の値が null だったキーは単に書かれません。{"a": null} を変換すると、出力は空のファイルになります。本物のキー 1 つと null のキー 1 つを持つテーブルを変換すると、本物のキーだけが現れます。

これが問題になるかどうかは、結果を読むツール次第です。多くの設定パーサーは、キーが存在しないことと null であることを同じように扱い——どちらも既定値にフォールバックします——その場合は何も失われていません。それらを区別するツールもあり、その場合はこの変換が静かに設定を変えてしまったことになります。防御策は、あとで 2 つのファイルを見比べるのではなく、変換する前に JSON の中の null を検索することです。存在しない行は、変わった行よりずっと気づきにくいからです。

これは、TOML を JSON より弱い形式だと思っている人がたいてい驚く部分です。レコードの一覧は、同じテーブル見出しの繰り返しとして表現されます。[[servers]] が 3 回あれば、それぞれ独自のキーを持つ 3 台のサーバーになります。JSON の配列より冗長ですが、編集はずっと簡単です。4 台目のサーバーを足すには、括弧のバランスを取るのではなく 5 行をコピーするだけで済みます。

メンバーが揃っている必要もありません。最初のオブジェクトが id と name を持ち、2 つ目に region が加わっている配列も、文句を言われずに変換され、TOML は有効なままです。各ブロックは自分が持つキーだけを運びます。これはこのサイトの表形式の変換先に対する本物の優位性です。表形式では、何かを書き出す前に異種混合の配列を 1 組の列にすり合わせる必要があるからです。

TOML のテーブル見出しは、次の見出しまでのすべてを自分のものとします。つまり [server] のあとに置かれた素のキーは、書いた人の意図にかかわらず server に属することになります。そのため、書き出し処理はすべてのトップレベルのスカラー値を最初のテーブル見出しより上に引き上げます。{"server": {"host": "localhost"}, "debug": true} は debug = true、空行、[server]、host という順で出てきます。

したがって出力は JSON にあった順序ではなく、そうすることもできません。これは意味を保つ唯一の並べ替えで、他のどんな並べ替えもキーがどのテーブルに属するかを変えてしまいます。元のグループ分けが読みやすさのために重要だったなら、個々のキーを見出しの上下に動かすのではなく、テーブルのブロックごと動かして復元してください。それなら安全です。

4 段の JSON の入れ子は 1 行の見出しになります。{"a":{"b":{"c":{"d":1}}}} は [a.b.c] と、その下の d = 1 に変換されます。TOML は深さをインデントではなく見出しの中で表現するので、深く構造化された設定は、元の JSON より TOML のほうが短く平坦になることがよくあります。

妥当性ではなく好みの問題としての限界もあります。[build.targets.linux.arm64.flags] のような見出しは合法ですが、誰も読んで楽しくはありません。変換されたファイルに 3、4 段を超える見出しがあるなら、たいていそれは設定を別のファイルや別のツールに分割すべきだというサインで、この変換は既存の問題を目に見えるようにしただけです。

出力にコメントは含まれません。入力側にそれを保つ場所がなかったからです。JSON はコメントを運ばないので、翻訳するものが何もありません。これは変換ツールの欠陥ではなく、そもそも JSON をやめる価値があった理由です。

だからこそ、変換したあとの最初の 5 分がこの作業でいちばん価値のある時間になります。TOML ファイルは、この設定についての組織の知識を保持できるバージョンです。どの値なら安全に変更できるか、どれが別のリポジトリの値と一致していなければならないか、なぜある上限がその値に設定されているか。その知識はいま誰かの頭の中か、コミットメッセージの中にしかなく、それをファイルに書き込むのに何のコストもかからない、まさにこの瞬間です。

TOML はオフセット付き日時を含む 4 種類の日付・時刻型を持ち、それらは文字列ではなく第一級の値です。JSON にはそれがありません。RFC 8259 が与えるのは文字列、数値、真偽値、null、配列、オブジェクトだけで、地球上のすべての JSON ファイルのすべてのタイムスタンプは、慣例として最初の 2 つのどちらかです。

そのため "2024-01-01T00:00:00Z" という JSON の値は、引用符付きの TOML の文字列として書かれます。これは正しくもあり、この形式が表現できたはずのものではありません。ファイルを読むツールが本物の日時を求めているなら、その行の引用符を手作業で外してください。そのあとは日付として解析され、ファイルの他の部分は何も変える必要がありません。

いちばん安上がりな確認は往復です。TOML を JSON に戻し、最初のものと比べてください。null だったキーは欠けているはずで、それ以外は変わっていないはずです。漠然とした不安を、数秒で読める差分に変えられます。

2 つ目の確認はツールそのものです。Cargo や Hugo、ほとんどの Python パッケージングツールは、文書が解析できるか、キーが期待どおりの場所にあるかをすぐに教えてくれます。これは往復確認では捕まえられないもの、つまり正しく変換されたのに、誰もリネームしなかったせいでトップレベルのキーがまだ items のままになっているファイルを見つけてくれます。

このブラウザーのタブの中、あなた自身のプロセッサーの上です。両方とも JavaScript です。JSON のパーサーはブラウザーに組み込まれたもので、TOML のライターは必要に応じて読み込まれる小さなライブラリです。ファイルをどこかへ運ぶリクエストは発生せず、アカウントも待ち行列も 1 日の上限もありません。無料枠は 100 MB までのファイルを受け付け、設定ファイルにとって誰も届かない容量です。

これは、たいていのデータ以上に設定にとって重要です。JSON の設定ファイルは、まさに内部のホスト名やバケット名、サービスアカウント、そしてときには消し忘れた認証情報を持っている種類のものであり、それを Web の変換ツールにアップロードすることこそ、実際に方針違反になる部分です。ここではアップロードするものが何もありません。