The Complete Guide to Converting Between JSON and TOML
Learn why TOML pairs nicely with JSON for configuration files, how to handle TOML's stricter type rules, and the surprising cases that break round-trips.
1. What JSON Lacks That TOML Adds
JSON is a data interchange format designed for machines, not humans. Comments are illegal, strings must always be quoted, trailing commas are forbidden, and dates can only be expressed as ISO-8601 strings. TOML (Tom's Obvious, Minimal Language) was designed for configuration files that humans actually write. It supports comments, key-value pairs without quoting, multi-line strings, tables, and native date and time types.
Converting JSON to TOML trades the universal wire format for something readable, ideal for committing a config that started life as data export. Converting TOML back to JSON is what you do when your toolchain consumes JSON but your author wrote TOML.
2. How Tables and Arrays of Tables Translate
A flat JSON object converts cleanly to a flat TOML file: each key becomes a key=value line. The interesting case is nesting. A JSON object that contains another object becomes a TOML table denoted by a header in square brackets, and arrays of objects become arrays-of-tables denoted by double-square bracket headers. The nested header rules emit a clean, indented-looking file even though TOML technically does not require indentation.
The conversion is mechanically one-to-one for any JSON document, because every JSON value is either a primitive, an array, or an object, and TOML supports exactly those three constructs plus a parse-time syntax for dates.
3. The Edge Cases That Bite Round-Trips
TOML's type system is stricter than JSON's in three narrow cases. First, NaN and Infinity (legal JSON numbers via some encoders) are not legal TOML numbers; the converter must transform them to null or a string. Second, extremely large integer values that fit in JSON's number type may exceed TOML's 64-bit signed integer limit and require treatment as strings or big integers. Third, mixed-type arrays are not allowed: a TOML array must hold all the same element type, so a JSON array mixing strings and numbers must be split or coerced.
Our converter reports cases where round-trip fidelity is not guaranteed so you can review the output and adjust accordingly. When the JSON document follows the strict subset that TOML supports, the round-trip is lossless; otherwise you will see exactly which keys were normalized.
4. Date and Time Handling
TOML has native datetime, date, and time types written in ISO-8601 without quotes. When the converter sees a JSON string that matches the ISO-8601 pattern exactly, it emits an unquoted TOML datetime. If your input encodes dates any other way (Unix timestamps, custom formats) the converter keeps them as strings since guessing the format is unsafe. The reverse direction quotes every TOML datetime back into a JSON string, preserving the original format.
Well-Typed In, Clean TOML Out
JSON-to-TOML conversion is mechanical for well-typed inputs but turns lossy for the edges of the JSON type system. ToolWise Free Online JSON to TOML Converter handles all three edge groups explicitly, supports the reverse direction identically, and runs entirely in your browser so the configuration files never leave your machine. Paste the JSON, configure, copy the TOML.