TOML → JSON / boundary guide
Pass TOML dates, integers, and empty values with their meaning
Before converting similar-looking values, check the time basis, integer precision, and what an empty or missing value means.
Fix the boundary first
A TOML date/time does not acquire a timezone merely by moving into JSON. Large integers can lose precision in JavaScript's ordinary number type, while an empty string or an omitted key is not JSON null.
date = 2026-10-01
datetime = 2026-10-01T12:30:00
offset_datetime = 2026-10-01T12:30:00+09:00
account_id = "9007199254740993"
label = ""
# TOML has no null value literal| TOML example | Check before handoff |
|---|---|
2026-10-01 | Local date only. Do not add a time or timezone. |
2026-10-01T12:30:00 | Local datetime. Do not invent the consumer's timezone. |
...+09:00 | Offset datetime. Keep the explicit offset; do not silently convert regions. |
9007199254740993 | Beyond JavaScript Number's safe integer range; keep an identifier as a string. |
"" / omitted key | An empty string is a string and omission is unspecified; neither is JSON null. |
TOML has no null literal
If the JSON contract needs null, do not substitute an empty string, false, or zero in TOML. Decide whether the key is omitted or whether the receiving contract needs an explicit string such as "null".
The existing converter handles supported TOML values locally. It does not assign date meaning or convert timezones.
Review cases
| case | outcome | check |
|---|---|---|
ordinary-values | convert | Verify booleans, ordinary integers, and arrays with the existing converter. |
date-time | review | Document the original TOML type and the consumer's time basis. |
large-integer | attention | Do not assume an ordinary JavaScript number preserves every integer. |
empty-vs-null | clarify / reject | Do not treat an empty string, omission, or string null as JSON null. |
Run the conversion
Use the existing TOML→JSON converter when you need to inspect values locally. This guide supplies the date, precision, and empty-value decisions around that conversion.