TOML Date-Time Types and JSON Strings

TOML is one of the few configuration languages with first-class date-time support. Unlike JSON, which represents all dates as plain strings, TOML has four distinct date-time types that are part of the language specification.

TOML date-time types:

# Offset Date-Time (full timestamp with timezone)
created = 2024-01-15T10:30:00Z
updated = 2024-06-20T14:45:00+09:00

# Local Date-Time (no timezone)
meeting = 2024-03-15T09:00:00

# Local Date (date only)
birthday = 1990-05-20

# Local Time (time only)
alarm = 07:30:00

Converts to JSON (as strings):

{
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-06-20T14:45:00+09:00",
  "meeting": "2024-03-15T09:00:00",
  "birthday": "1990-05-20",
  "alarm": "07:30:00"
}

Key points about TOML date-time conversion:

1. No type information in JSON. JSON has no date type, so all TOML date-times become strings. The semantic distinction between an offset date-time and a local date-time is lost.
2. ISO 8601 format is preserved. The string representation follows the ISO 8601 standard, making it parseable by date libraries in most languages.
3. TOML validates date-time syntax. Unlike JSON (where any string is valid), TOML parsers reject malformed dates like 2024-13-40. This validation is lost in JSON.

TOML date-time separators:

# Both are valid TOML:
dt1 = 2024-01-15T10:30:00Z
dt2 = 2024-01-15 10:30:00Z   # space separator allowed

Both produce the same JSON string. The T separator is standard in JSON/ISO 8601.

Converting JSON dates back to TOML:

When converting JSON to TOML, date-like strings can be converted to native TOML date-time values:

• "2024-01-15T10:30:00Z" becomes 2024-01-15T10:30:00Z (unquoted, native date-time)
• "2024-01-15" becomes 2024-01-15 (unquoted, native local date)
• "not-a-date" stays as "not-a-date" (quoted string)

A smart converter detects ISO 8601 patterns and uses native TOML types, improving type safety in the resulting TOML file.