データ形式・構造化データ
JSONをTOMLにすると、nullや日時はどうなる？
使うツール
設定ファイルの形式を変える作業は、拡張子を変えるだけでは終わりません。文字列のtrueと真偽値のtrue、空欄とnull、日付らしい文字列と日時型は、見た目が近くても別の値です。読み込むアプリがどの型を期待しているかによって、同じ表示でも動作が変わります。JSON⇔TOMLで小さな設定を往復させ、どこまで同じ情報を運べるかを確かめましょう。
まず、同じ値を運べる小さな設定から
{"name":"demo","enabled":true,"retries":3,"ports":[8000,8001]}JSON⇔TOMLへ入力して変換し、nameが文字列、enabledが真偽値、retriesが数値、portsが配列として出ているかを見ます。次に出力を入力へ戻して、JSONへ変換します。空白やキーの表示順まで同じである必要はありませんが、値と型が同じであることは必要です。名前がdemo、再試行が3、ポートが8000と8001という条件を先に書いておくと、見た目に引きずられず確認できます。
このツールは入力の先頭を見て変換方向を選びます。JSONのように{または[で始まる入力と、それ以外のTOMLを区別する方式です。そのため、TOMLのテーブル見出しだけから始まる文書など、先頭が[の入力は自動判定と衝突します。本記事のTOML例は最初にキーと値を置きます。実際の文書で判定に失敗した場合は、変換に成功したと扱わず、対応範囲の制約として確認してください。
nullを消すか、空文字にするかは仕様で決める
{"name":"demo","timeout":null}この入力は、nullをTOMLで表す値がないため拒否されます。エラーを避ける目的だけでtimeoutを0や空文字へ置き換えないでください。アプリによっては0が待機なし、無制限、無効な入力など別の意味になり、キーの省略は既定値を使う意味になるかもしれません。どの置換が適切かは変換器では決められません。連携先の設定仕様を調べてから、明示的な値を選びます。
選んだ置換をチームへ伝えるときは、『TOMLへ変換した』ではなく『timeout:nullを省略し、読み込み側の既定値を使う』のように、意味が変わる箇所を記録します。nullが配列の途中にある場合も、単純に削除すれば後ろの要素の位置が変わります。キーと値の集合なのか、順序が意味を持つ配列なのかによって、同じ削除でも影響が違います。
日付らしい文字列と、日時型を往復させる
name = "demo"
created = 2026-01-02T03:04:05Z
label = "2026-01-02T03:04:05Z"初期設定では日時型の変換を拒否します。「TOML日時を文字列へ変換する」を選んでから試してください。createdはTOMLの日時として、labelは文字列として書いています。JSONへ変換すると、どちらも日時を表す文字列に見える出力になります。さらにTOMLへ戻したとき、createdが元の日時型へ自動で戻るとは限りません。文字列の形が似ているだけで、元の型まで復元できるわけではないためです。変換前後の値に加えて、アプリが受け取る型も確認する必要があります。
日時の正規化で小数秒やオフセットの表記が変わることもあります。時点が同じでも、元の表記が必要なログや署名対象の文字列では、その違いが重要です。地域のない日付、地域付き時刻、単なる説明用のラベルを一緒に扱わないでください。変換の途中で時間帯を推測して補うより、日時として使う項目と文字列のまま運ぶ項目を決めておく方が安全です。
コメントが消えても、同じ値とは限らない？
retries = 3 # temporary limit for the test environment
name = "demo"このTOMLをJSONへ変えると、コメントの説明は値として運ばれません。retriesが3のままでも、なぜ3なのかという運用上の理由は失われます。コメントが消えたことを計算値の変更とは扱いませんが、設定の引き継ぎでは無視できない情報です。移行時は、残すべき理由を設計文書へ移すのか、元の設定と一緒に保存するのかを決めてください。
見やすさのための空行やキー順序も、変換後に同じとは限りません。差分画面が大きく変わって見えるときは、見た目の差分と値の差分を分けます。JSONへ戻して構造比較を使えば、少なくとも対象の値が変わったかを確認しやすくなります。ただし、コメントの意味やTOML固有の型までJSON構造比較が保証するわけではありません。確認範囲を小さく分けて組み合わせます。
大きな整数は、形式だけでなく変換器の限界も見る
{"id":9007199254740993}JSON整形で桁を保てる数値でも、このTOML変換はすべてを正確に運べるわけではありません。この例はJSONからTOMLへ正確に変換できる範囲を超えるため拒否されます。TOMLという形式全体の整数上限と、この実装の変換可能範囲は別です。エラーになったからといって下位桁を丸めて通すのではなく、IDなら文字列として扱える契約かを確認します。
変換後に確かめる一覧を作るなら、数値、真偽値、配列、null、日時、コメントを別項目にします。正常な例を一つ通すだけで移行完了とせず、実際の設定に含まれる型ごとに小さな例を用意します。ここで見つけた未対応条件を、設定ファイルの仕様を変える根拠と取り違えないでください。必要な情報を保てないなら、変換方法や形式の選択を見直す判断もあります。