开发者工具·语法转换器

为什么 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 携带显示文本，并避免默默地将其提升为通用时间戳。