Why Convert JSON to TOML?
JSON is everywhere as a data-interchange format, but it was never designed to be edited by hand. It has no comments, is strict about trailing commas, and nests deeply with braces that are hard to scan. TOML (Tom's Obvious Minimal Language) targets exactly the human-edited config use case: it reads like an INI file, supports comments, and maps cleanly onto a hash table. Converting a JSON config to TOML is a common step when adopting tools like Cargo, Hugo, or any project that standardizes on *.toml.
How the Structures Map
The core idea: a JSON object becomes a TOML table, and keys become key = value pairs. Here is a side-by-side:
{
"title": "My App",
"owner": {
"name": "Ada",
"active": true
},
"ports": [8000, 8001]
}
Becomes:
title = "My App"
ports = [8000, 8001]
[owner]
name = "Ada"
active = true
Notice that top-level scalars come first, and the nested owner object becomes a [owner] table header. TOML requires scalar keys to appear before any table headers at the same level — a converter handles this ordering for you, but it explains why the output is reordered relative to the JSON.
Arrays and Arrays of Tables
A JSON array of objects maps to a TOML array of tables, written with double brackets:
{ "servers": [
{ "host": "alpha", "port": 8000 },
{ "host": "beta", "port": 8001 }
]}
[[servers]]
host = "alpha"
port = 8000
[[servers]]
host = "beta"
port = 8001
Each [[servers]] block is one element of the array. This is one of TOML's most distinctive features and the part people most often hand-write incorrectly — letting a converter generate it removes the guesswork.
The Pitfalls
Two JSON things have no TOML equivalent, and a good conversion has to decide what to do:
null— TOML has no null type. Most converters drop null keys entirely; be aware a key can silently disappear. If the key is meaningful, replace it with a sentinel or omit it deliberately.- Mixed-type arrays — JSON allows
[1, "two", true]. TOML arrays should be homogeneous; mixed arrays are technically allowed in TOML 1.0 but many parsers reject them. Normalize the data first.
Also watch deeply nested objects: TOML expresses depth with dotted table headers like [a.b.c], which stays readable up to a point but becomes awkward past three or four levels. If your JSON is deeply nested, TOML may not be the right target at all.
When TOML Is the Right Choice
TOML shines for static, human-edited configuration — tool settings, build manifests, app config. It is a poor fit for large data payloads, anything with lots of nulls, or machine-to-machine messaging where JSON's ubiquity wins. Use the converter to move a config into TOML once, then maintain it by hand with comments.
Frequently Asked Questions
Does JSON-to-TOML preserve key order? Not exactly. TOML requires scalar keys before nested tables, so top-level values are emitted first and tables follow. The data is identical; only presentation order changes.
What happens to null values? TOML has no null. Keys with null values are typically dropped during conversion. Decide explicitly whether to omit them or substitute a placeholder.
Can every JSON file become valid TOML? No. Mixed-type arrays and null values have no clean TOML representation, and extremely deep nesting becomes unwieldy. Flat-to-moderately-nested configs convert cleanly.
Paste your JSON into the converter above to get formatted TOML instantly, including correct array-of-tables output for nested object lists.