Convert TOML to JSON

TOML has been the standard for Python and Rust packaging for years, and the tooling around a repository often has not caught up. A CI step with jq available and nothing else, a Node script that has to read the version out of a Cargo.toml, a dashboard counting dependencies across two hundred repositories — all of them can read JSON and none of them can read TOML without a new dependency.

That is the case this conversion serves, and it works cleanly because the two data models overlap almost entirely. TOML is a table of key-value pairs with nesting and arrays, which is a JSON object with nesting and arrays. The interesting parts are the four places where TOML knows something JSON does not.

A bracketed header becomes a nested object, and a dotted header becomes nesting several levels deep — a header written for a tool and then a linter under it produces an object inside an object, so the JSON path matches the header exactly. Nothing about the structure needs interpreting.

A double-bracket header is the array of tables, and it becomes a JSON array of objects with one entry per occurrence. That is what holds the authors of a Python package, the binaries of a Rust crate and the targets of a build, and it is the construct people worry about most and need to worry about least. Order is preserved.

TOML is the only format in this family with genuine temporal types: offset datetimes, local datetimes, local dates and local times are in the specification, and a parser returns them as dates. JSON has no date type at all, so each one becomes a string.

The values survive with one wrinkle. An offset datetime keeps its offset rather than being normalised to UTC, which is better behaviour than several other conversions on this site. A local date comes across exactly as written. A local time picks up a millisecond component it did not have — a time written as eight in the morning arrives with a fractional part attached. If something downstream compares those strings rather than parsing them, that extra suffix is the thing that will break the comparison.

TOML 1.0 requires an implementation to handle 64-bit signed integers. JSON numbers are IEEE doubles and are exact only to about nine quadrillion. A TOML file holding an integer above that range is entirely legal, and the parser here stops with an error saying the integer cannot be represented losslessly rather than producing JSON with a wrong number in it.

Refusing is the right call and it is worth understanding rather than working around blindly. A silently rounded identifier is a bug that surfaces weeks later in a join that matches nothing. If your TOML holds a value of that size — a snowflake ID, a large serial, a nanosecond timestamp as an integer — quote it as a string in the source. It was never a quantity, and quoting it makes every downstream consumer correct at once.

TOML floats include inf and nan as literal values. JSON has neither, and the serialiser writes null for both. That is the standard JavaScript behaviour and it is lossy in a way nothing reports — a configured upper bound of infinity and an unset upper bound become the same thing in the JSON.

The subtler loss is typing. TOML distinguishes an integer from a float, so 1 and 1.0 are different values with different types, and a schema or an application can rely on that. JSON has one number type, and 1.0 is serialised as 1. If a consumer of the JSON needs to know that a value was declared as a float, that information has to travel some other way, because it is not in the file any more.

Tables and keys come out in the order the TOML declared them, which keeps a converted file readable and keeps a diff between two conversions meaningful. The output is indented two spaces and ends with a newline.

The exception is numeric keys. A quoted TOML key that is a number — which appears in configs that index things by year or by port — is reordered ahead of every other key in its object and sorted ascending, because that is how JavaScript objects order integer-like keys. It is the only place where the JSON does not read in the same sequence as the source.

The output is ordinary JSON, so jq reads it with no flags: pulling a project version, listing dependency names or checking whether a tool section exists are all one-line expressions. That is usually the whole reason for the trip, and it turns a shell script that was going to grep a TOML file into one that queries it properly.

It also opens up validation. JSON Schema is mature and widely implemented, and TOML has no schema language in its specification, so converting and then validating is a genuine way to enforce house rules across many repositories — every package must declare a licence, every crate must pin its edition — that cannot be checked against the TOML directly.

TOML supports comments and uses them heavily: the reason a dependency is pinned, the ticket number next to a workaround, the block explaining which environment a setting applies to. JSON has no comment syntax under RFC 8259, so none of it arrives.

That settles the direction of the relationship. The TOML is the file people edit and review, and the JSON is generated from it whenever something needs to read it. Checking the JSON into the repository alongside the TOML creates two versions of the truth that will drift; generating it in the build step does not.

If the reading happens inside an application rather than in a build step, use a parser. Every major language has one — Python has had tomllib in its standard library for several versions, and Rust, Go and JavaScript all have well-maintained options. Reading the file directly keeps the temporal types and the integer-float distinction that this conversion flattens.

The converter earns its place at the boundary: a one-off inspection, a CI step where adding a dependency is more trouble than it is worth, or a pipeline whose next stage speaks nothing but JSON. Everything runs in your browser, so a private config with credentials in it is safe to drop here, and the free ceiling of 100 MB is far beyond any configuration file.