Developer tools · Syntax converters
Why TOML has a native date-time type and JSON does not (RFC 3339)
· Background
toml json timestamps
TOML is the only format in this group with first-class dates and times, all defined by RFC 3339. This post explains the four TOML date-time kinds, why JSON deliberately has none, and what a conversion has to do with them.
The date that became a string — a TOML config with a release date, converted to JSON and reduced to text
A TOML local date such as `1979-05-27` becomes the JSON string `"1979-05-27"`. The calendar characters survive, but the native TOML type does not. Converting that JSON back writes a quoted string, not a date token, and ToolAcre warns at the first conversion.
This is an unavoidable boundary in the chosen plain JSON value. Calling the round trip lossless would confuse preserved text with preserved type. The warning names both path and temporal kind so reviewers can decide whether a string is acceptable downstream.
Why JSON has no date type — Crockford's minimalism, the ISO 8601 string convention and the milliseconds-since-epoch convention that compete to fill the gap
JSON parsing here produces null, booleans, numbers, strings, arrays and objects; it does not produce Date objects. The repository proves that implementation fact but does not source historical explanations for JSON’s minimalism or competing industry conventions.
Applications may adopt ISO-like strings or epoch numbers by agreement, but those are conventions layered onto JSON. Syntax converters does not infer one from arbitrary text and does not convert TOML temporal values into epoch arithmetic.
JSON has no native date type in this converter; origin rationale is outside repository evidence
TOML exposes four kinds: offset date-time with a Z or numeric offset, local date-time without a zone, local date, and local time. smol-toml represents them as date-like objects carrying kind metadata; ToolAcre identifies each before normalizing it.
The distinction prevents a serious mistake. A local time is not silently assigned UTC, and a local date-time is not moved between zones. Its absent offset remains absent in the JSON string.
RFC 3339 as the foundation — the profile of ISO 8601 that TOML borrows, including the space-separator allowance
The normalizer calls the parser value’s ISO formatter and removes only a synthetic `.000` fraction. It preserves meaningful fractional seconds and source-oriented local versus offset form. The code describes this as RFC 3339 text, but the article does not invent specification clauses such as separator allowances beyond tested output.
An offset example remains date-time text rather than being converted to a universal Z value by this layer. That avoids changing the written representation and keeps temporal interpretation for the application that owns it.
ToolAcre preserves source-oriented temporal text without asserting full RFC 3339 compliance details
Every temporal value becomes a string, and warnings say that JSON, YAML and XML have no date type in this conversion model. Offsets are not deliberately dropped, and local values do not acquire one. The lost information is the TOML type category itself.
On reverse conversion, the string is quoted because the writer has no marker telling it to restore a datetime. Re-parsing arbitrary date-looking strings as dates would incorrectly type ordinary identifiers or labels and would invent a convention not shared by JSON.
The converter preserves local versus offset spelling, then loses the native TOML type
Use `odt = 1979-05-27T07:32:00Z`, `ldt = 1979-05-27T07:32:00`, `ld = 1979-05-27` and `lt = 07:32:00`. JSON contains four strings with those spellings. The warning lists offset date-time, local date-time, local date and local time paths.
Convert the JSON back to TOML. Each value is quoted. A fractional `00.500Z` remains fractional, while a whole-second value does not gain `.000`. This is the actual supported behaviour and clearly demonstrates preserved text versus lost type.
Worked example: all four TOML temporal kinds become strings and return quoted
Time-zone rule lookup, daylight-saving transitions and epoch conversion are not part of this route. A local date-time without a zone cannot become one unique instant without more information. The Unix timestamp converter addresses known instants under a different contract.
Do not feed every resulting string to JavaScript Date and assume equivalent meaning. Local date, local time and zoneless date-time require application context. Preserve the warning and field semantics through migration.
Takeaway: TOML knows what a date is, JSON only knows what a string is — and how the Syntax converters panel shows that difference in your browser
TOML knows four temporal categories; JSON receives only strings here. ToolAcre preserves spelling carefully and refuses to invent a zone, but the native type is gone and cannot be reconstructed automatically on return.
Review every warned path and define an application convention when temporal semantics must survive. If no such convention exists, keep TOML as the authoritative source rather than treating a quoted round trip as equivalent.
A sound convention also names which strings may be parsed again and under what context. An offset date-time can identify an instant, while a local date-time, date or time cannot do so without additional rules. Store the original kind beside the normalized string when a later stage needs to reconstruct TOML or schedule work. Otherwise accept that JSON is carrying display text and avoid silently promoting it to a universal timestamp.