開發者工具·語法轉換器

為什么 TOML 具有本机日期時間類型而 JSON 没有 (RFC 3339)

2026年6月27日 · 背景

toml json 時間戳

TOML 是本組中唯一具有一流日期和時間的格式，所有格式均由 RFC 3339 定義。這篇文章解釋了四種 TOML 日期時間類型，為什麼 JSON 故意沒有，以及轉換與它們有什麼關係。

成為字串的日期 — 具有發佈日期的 TOML 配置，轉換為 JSON 並簡化為文字

TOML 本地日期（例如 `1979-05-27`）將成為 JSON 字串 `"1979-05-27"`。日曆字元會保留下來，但本機 TOML 類型不會。將 JSON 轉換回會寫入引號的字串，而不是日期標記，並 ToolAcre 在第一次轉換時會發出警告。

這是所選普通 JSON 值中不可避免的邊界。稱往返為無損會將保留的文字與保留的類型混淆。此警告命名了路徑和時間類型，以便審閱者可以決定字串是否可以被下游接受。

JSON 解析此處產生 null、布林值、數字、字串、陣列和物件；它不會產生 Date 物件。該存儲庫證明了這一實現事實，但沒有為 JSON 的極簡主義或競爭行業慣例提供歷史解釋。

應用程式可以根據協定採用類似 ISO 的字串或紀元號，但這些約定是分層到 JSON 上的。語法轉換器不會從任意文字推斷出一個值，也不會將 TOML 時間值轉換為紀元算術。

TOML 揭露四種類型：帶有 Z 或數位偏移量的偏移日期時間、不含區域的本地日期時間、本地日期和本地時間。 smol-toml 將它們表示為攜帶類型元資料的類似日期的物件； ToolAcre 在對其進行標準化之前對其進行識別。

這種差異可以防止出現嚴重錯誤。本地時間不會自動分配 UTC，且本地日期時間不會在區域之間移動。其缺失的偏移量在 JSON 字串中仍然不存在。

規範化器呼叫解析器值的 ISO 格式化程式並僅刪除合成的 `.000` 分數。它保留了有意義的小數秒和麵向來源的本地與偏移形式。該程式碼將其描述為 RFC 3339 文字，但本文並未發明規範條款，例如超出測試輸出的分隔符餘裕。

偏移範例保留日期時間文字，而不是透過該層轉換為通用 Z 值。這避免了更改書面表示並保留擁有它的應用程式的時間解釋。

每個時間值都會變成字串，並警告指出 JSON、YAML 和 XML 在此轉換模型中沒有日期類型。偏移量不會被故意丟棄，本地值也不會獲得偏移量。遺失的資訊是 TOML 類型類別本身。

在反向轉換時，字串被引用，因為編寫器沒有標記告訴它恢復日期時間。將任意看起來像日期的字串重新解析為日期會錯誤地鍵入普通識別碼或標籤，並會發明 JSON 不共享的約定。

使用 `odt = 1979-05-27T07:32:00Z`、`ldt = 1979-05-27T07:32:00`、`ld = 1979-05-27` 和 `lt = 07:32:00`。 JSON 包含四個具有這些拼字的字串。此警告列出了偏移日期時間、本地日期時間、本地日期和本地時間路徑。

將 JSON 轉換回 TOML。每個值都被引用。小數 `00.500Z` 仍為小數，而整秒值不會獲得 `.000`。這是實際支持的行為，清楚地展示了保留的文字與丟失的類型。

時區規則查找、夏令時轉換和紀元轉換不是此路線的一部分。如果沒有更多消息，沒有區域的本地日期時間無法成為一個唯一的時刻。 Unix 時間戳轉換器處理不同合約下的已知時刻。

不要將每個結果字串提供給 JavaScript Date 並假定相同的意義。本地日期、本地時間和無區日期時間需要應用程式上下文。透過遷移保留警告和欄位語義。

TOML 知道四個時間類別； JSON 這裡僅接收字串。 ToolAcre 小心地保留拼字並拒絕發明區域，但本機類型已消失並無法在返回時自動重建。

檢查每個警告路徑並在時間語意必須生存時定義應用程式約定。如果不存在這樣的約定，請將 TOML 保留為權威來源，而不是將引用的往返視為等效的。

健全的約定也指定了可以再次解析哪些字串以及在什麼上下文中。偏移日期時間可以識別瞬間，而本地日期時間、日期或時間在沒有附加規則的情況下不能這樣做。當後續階段需要重建 TOML 或排程工作時，將原始類型儲存在規範化字串旁邊。否則，請接受 JSON 攜帶顯示文字，並避免默默地將其提升為通用時間戳。