Convert JSON to TOML

JSON has no comments. That is stated in the specification rather than being an oversight, and it is the single reason most configuration written in JSON is unpleasant to maintain: the reason a timeout is 45 seconds cannot live next to the 45. TOML, which took eight years of 0.x releases to reach 1.0 in January 2021 and is now the config format for Cargo, pyproject.toml and Hugo, has comments, and that is usually the whole motivation for this conversion.

The second reason is flatness. A JSON config three levels deep is three levels of braces and a great deal of indentation; the same thing in TOML is a header line reading [server.tls.client] and a short list of keys under it. Nothing about the data changed, but the diff a reviewer sees when one value moves is one line instead of a reindented block.

A TOML document is a table. It cannot begin with an array the way a JSON document can, so a file whose outermost character is a square bracket has nothing to map onto. The conversion handles this rather than failing: a value that is not an object is wrapped under a key named items, and the output starts with [[items]].

That keeps the file valid, and it is a placeholder rather than an answer. No converter can know whether the tool reading the file expects that list to be called dependencies, servers or plugins. Rename the key in the first line and the rest of the file is already correct — it is a one-word edit, and it is deliberately obvious rather than hidden.

This is the failure worth checking for every time. TOML has no null literal, and the writer does not invent one: a key whose JSON value was null is simply not written. Convert {"a": null} and the output is an empty file. Convert a table with one real key and one null key and only the real key appears.

Whether that matters depends entirely on the tool reading the result. Many config parsers treat an absent key and a null key the same way — both fall back to a default — and for those, nothing was lost. Others distinguish them, and there the conversion has quietly changed the configuration. The defence is to search the JSON for null before converting rather than to compare the two files afterwards, because an absent line is much harder to notice than a changed one.

This is the part that usually surprises people who expect TOML to be a weaker format than JSON. A list of records is expressed as the same table header repeated: [[servers]] three times gives you three servers, each with its own keys beneath it. It is more verbose than a JSON array and considerably easier to edit, because adding a fourth server means copying five lines rather than balancing brackets.

The members do not have to match. An array where the first object has an id and a name and the second adds a region converts without complaint, and the TOML stays valid — each block carries the keys it has. That is a real advantage over the tabular targets on this site, where a heterogeneous array has to be reconciled into one set of columns before anything can be written.

A TOML table header owns everything written below it until the next header. That means a plain key placed after [server] belongs to server, whatever the author intended. So the writer hoists every top-level scalar above the first table header: {"server": {"host": "localhost"}, "debug": true} comes out as debug = true, a blank line, then [server] and host.

The output is therefore not in the order your JSON was in, and it cannot be. This is the one reordering that preserves meaning, and any other would change which table a key belongs to. If the original grouping mattered for readability, restore it by moving whole table blocks around — that is safe — rather than by moving individual keys above or below a header.

Four levels of JSON nesting become a single header line: {"a":{"b":{"c":{"d":1}}}} converts to [a.b.c] with d = 1 under it. TOML expresses depth in the header rather than in the indentation, which is why a deeply structured config is often shorter and flatter in TOML than in the JSON it came from.

It also has a limit that is a matter of taste rather than validity. A header like [build.targets.linux.arm64.flags] is legal and nobody enjoys reading it. If the converted file has headers past three or four segments, that is usually a sign the configuration wants splitting into separate files or separate tools, and the conversion has just made an existing problem visible.

The output has no comments in it, because the input had nowhere to keep any. JSON does not carry them, so there is nothing to translate — this is not a shortcoming of the converter but the reason the JSON was worth leaving in the first place.

Which makes the first five minutes after converting the most valuable part of the exercise. The TOML file is the version of this configuration that can hold the institutional knowledge about it: which values are safe to change, which one must match a value in another repository, why a limit is set where it is. That knowledge exists in somebody’s head or in a commit message today, and this is the one moment when writing it into the file costs nothing.

TOML has four date and time types, including an offset date-time that is a first-class value rather than a string. JSON has none: RFC 8259 gives you strings, numbers, booleans, null, arrays and objects, and every timestamp in every JSON file on earth is one of the first two by convention.

So a JSON value of "2024-01-01T00:00:00Z" is written as a quoted TOML string, which is correct and is not what the format could express. If the tool reading the file wants a real date-time, remove the quotation marks by hand on those lines. It parses as a date afterwards, and nothing else in the file has to change.

The cheapest check is a round trip: convert the TOML back to JSON and compare it with what you started from. Keys that held null will be missing and nothing else should differ, which turns a vague worry into a diff you can read in a few seconds.

The second check is the tool itself. Cargo, Hugo and most Python packaging tools will tell you immediately whether the document parses and whether the keys are where they expect them, and that catches the one thing a round trip cannot: a correctly converted file whose top-level key is still called items because nobody renamed it.

In this browser tab, on your own processor. Both halves are JavaScript — the JSON parser is the one built into the browser, and the TOML writer is a small library loaded on demand — so no request carries the file anywhere, and there is no account, no queue and no daily allowance. The free tier accepts files up to 100 MB, which for configuration is not a limit anyone reaches.

That matters more for config than for most data. A JSON configuration file is exactly the kind of thing that holds internal hostnames, bucket names, service accounts and occasionally a credential somebody meant to remove, and uploading it to a web converter is the part that would actually be against policy. Here there is nothing to upload.