資料格式與結構化資料

JSON 轉 TOML 時 null 與日期會怎樣？

使用工具

改設定格式不只是改副檔名。字串 true 與布林 true、null 與空值、日期字串與日期型別都不同。先用小設定往返 JSON/TOML，再核對應用預期型別。

初始 JSON 輸入

{"name":"demo","enabled":true,"retries":3,"ports":[8000,8001]}

轉換後確認 name 為字串、enabled 為布林、retries 為數字、ports 為陣列，再把結果轉回 JSON。空白與鍵顯示順序可不同，但值與型別應相同。先獨立寫下 demo、3、8000/8001 等預期。

方向由首字元推斷：{ 或 [ 被當作 JSON。因此以表頭開頭的 TOML 會與判定衝突。本文 TOML 範例先寫鍵值行，遇到判定失敗應視為工具限制。

會被拒絕的 null 範例

{"name":"demo","timeout":null}

TOML 無 null 值，因此轉換拒絕。不要僅為消除錯誤改成 0 或空字串：0 可能表示不等待、無限等待或非法，省略鍵可能啟用預設值。轉換器不能決定應用語意。

應明確記錄語意修改，例如省略 timeout:null 以使用接收端預設值。刪掉陣列中的 null 會移動後續位置，與刪除物件屬性不同，審查時必須區分。

比較日期有無引號的 TOML

name = "demo"
created = 2026-01-02T03:04:05Z
label = "2026-01-02T03:04:05Z"

預設拒絕日期型別，請先選擇將TOML日期轉為字串。created 是 TOML 日期時間，label 是字串。JSON 中兩者可能都像日期字串，轉回時 created 不一定恢復原型別。外形相似不證明型別保留，應檢查應用實際收到的型別。

正規化可能改變小數秒或偏移寫法。時刻相同也不代表日誌或簽章所需原文相同。應區分本地日期、帶偏移時刻與標籤，並決定哪些欄位必須保持字串，不要推測時區。

帶理由註解的 TOML

retries = 3 # temporary limit for the test environment
name = "demo"

註解不會作為 JSON 值保留。retries 仍為 3，但選擇 3 的維運理由可能遺失。這不是數值變化，卻影響維護，應決定把理由放入文件還是保留原設定。

空行和鍵順序也可能變化。應分開看外觀差異與值差異，必要時轉 JSON 做結構比較。但這仍不保證註解或 TOML 特有型別等價，應組合多個明確範圍的檢查。

JSON 轉 TOML 被拒絕的整數

{"id":9007199254740993}

JSON 整形能保留的數字不代表 TOML 轉換也支援。此輸入超出精確轉換範圍而被拒絕。格式的整數範圍與實作的轉換範圍不同，不要捨入 ID 來通過，應確認契約是否允許字串。

按數字、布林、陣列、null、日期、註解列檢查表。單例通過不等於遷移完成，應逐類測試實際資料。轉換器限制不授權改變設定契約；若必要資訊無法保留，應重新選擇方法或格式。