NDJSON を TOML に変換

TOML は JSON が持つものを持てないと思われがちですが、レコードの一覧に関しては誤りです。テーブルの配列は同じ見出しを二重角括弧で繰り返すだけで書けます。[[items]] を三回書けば三件のレコードになり、それぞれのブロックの下に自分のキーが並びます。Cargo が依存関係に、Hugo がメニュー項目に使っている構文です。

元の JSON と比べると冗長になりますが、格段に編集しやすくなります。レコードを一件足すのは括弧の対応やカンマを気にすることなく四行を複製するだけで、一件への変更の差分もそのブロックだけに現れます。人が保守するファイルにとって、これがすべてです。

TOML の文書は最上位でテーブルでなければならず、改行区切りのファイルはそれ自体に名前のないリストです。だからリストには仮の名前が与えられ、出力はソースの各行に対応する [[items]] ブロックの連続になります。

その名前は最初に変えるべきもので、ブロックの見出しに対する置換で済みます。[[dependencies]]、[[authors]]、[[products]] など、読み取る側のツールが期待する名前に。NDJSON ファイルの中には、レコードが何であるかを変換器に伝える手がかりが何もないため、この仮の名前は推測ではなく、意図的に目立つものにしてあります。

これは同じファイルを他の表形式に変換する場合と比べた、TOML の静かな強みです。CSV や Parquet、INSERT 文の並びは、レコードを一つの列集合にそろえる必要があり、何も持たないレコードには空欄を埋めます。テーブルの配列にはその必要がなく、各ブロックはその行が持っていたキーだけを持ちます。

ですから、あとから項目が増えたレコードを含むファイルも、null や空セル、列の拡張なしに変換できます。結果はまばらな表としてではなく、それが実際に何であるか——だいたい似ているレコードの一覧——として表れます。時間をかけて組み上げたフィクスチャ集にとって、これはたいてい正直な表現です。

TOML には null リテラルがなく、書き込み側もそれを発明しません。JSON の値が null だったキーは、レコードの最上位でもその内側でも、ブロックに一切書かれません。

それが問題かどうかは、ファイルを読むツール次第です。多くのツールはキーが欠けている状態と空の値を同じものとして扱い、どちらでも既定値に落ち着くので、そこでは何も失われていません。区別が挙動を左右するところでは、変換は静かにデータを変えたことになります。いちばん安上がりな防御は、変換後の 2 つのファイルを見比べることではなく、変換前にソースを null で検索することです。行が丸ごと消えたことに気づくのは、変わった行に気づくよりずっと難しいからです。

入れ子のオブジェクトを持つレコードは、そのブロックの下にサブテーブルを作ります。レコード内の author オブジェクトは [items.author] という見出しとその下のキーになります。深さは字下げではなく見出しの中で表現されるので、三段になってもページ上は平らなままです。

どんな深さでも合法ですが、二、三段を超えると読みにくくなります。[items.metadata.source.system] のような見出しは有効ですが、誰も好んで読みません。そういう見出しを生むファイルは、たいてい手編集向けのファイルが持つべき以上の構造を抱えているという、データ自体についての合図です。

TOML のテーブル見出しは、次の見出しが来るまで、その下に書かれたすべての行を自分のものとして扱います。ですから、ブロックの下に置いた平のキーは黙ってそのブロックの一部になってしまいます。書き出し側は最上位のスカラー値をすべて、最初の見出しより上に置きます。

この組み合わせでは、入力がリストなので、ほとんどの場合すべてがブロックの中に収まり、あまり問題になりません。あとでファイルを編集するときには意味を持ちます。ファイルの末尾に version キーを足すと、それは最上位ではなく最後のレコードの中に入ってしまい、これは TOML でいちばんよくある間違いです。そうしたキーはファイルの先頭、最初の二重角括弧見出しより上に足してください。

TOML 1.0 にはオフセット付き日時を含む四つの日付・時刻型があり、実際の値としてテキストではなく扱えます。JSON にはそれがなく、あらゆる JSON ファイルのすべてのタイムスタンプは慣習として文字列か数値です。ですから "2024-01-01T00:00:00Z" のような値は引用符付きの TOML 文字列として書かれます。

それは正確であり、フォーマットが表現できたはずのものではありません。読み取り側のツールが本物の日時を欲しがるなら、該当行の引用符を外すだけで直り、ファイルの他の部分は変える必要がありません。ブロックの見出しを付け替えているついでに行う価値のある作業です。

数十件は快適です。数百件は誰も読まないが、ツールなら素早く読めるファイルです。数千のブロックになると設定ファイルは名ばかりで、読みやすい差分や手編集、値の隣に置けるコメントといった TOML の魅力はすべて意味を失います。

止める基準は正直に適用する価値があります。誰もファイルを開くつもりがないなら、設定形式に変換しないでください。CSV のほうが小さくどんなツールでも読め、JSON はデータがもともとそうだった形で、データベースはリストを問い合わせる用途にふさわしいものです。TOML が値を発揮するのは、人がその結果を保守するときだけです。

両方の半分はこのタブの中の JavaScript です。ファイルは行ごとに解析され、必要なときに読み込まれる小さなライブラリが TOML を書き出します。アップロードはなく、アカウントも不要で、無料枠は 100 MB まで受け付けます。この変換にふさわしい大きさのファイルなら、誰もその上限に近づくことはありません。

この規模でもプライバシーの論点は変わりません。フィクスチャ集はしばしば名前をそのまま残した実データで、開発データベースのシード用ファイルは本番データの一部であることが少なくありません。ログファイルほど大きな決断ではありませんが、どこにも送らないことは、それでも正しい既定値です。