JSON to TOML

TOML is what Cargo, pyproject.toml, and a growing number of tools read. Its design goal is being unambiguous where YAML is subtle: every type has one spelling, whitespace carries no meaning, and there are no traps of the NO-means-false kind. The cost of that clarity is a narrower type system than JSON's.

Structure maps cleanly. A nested object becomes a [table] header, an array of objects becomes a sequence of [[table]] blocks, and scalars and arrays of scalars are written inline under whichever table they belong to. Key order is preserved, so converting the same JSON twice gives the same file and a diff means something.

The one thing that cannot map is null. TOML has no such value — the way TOML says "absent" is to leave the key out — so a null-valued key is emitted as a comment recording what was dropped, rather than written as "". An empty string is a different value, and a config reader cannot tell the two apart.

Why is a top-level array rejected?

A TOML document is itself a table — a set of key/value pairs — so a bare array has nowhere to live. Wrap it under a key first: {"items": [...]} converts to a run of [[items]] blocks.

What happened to my null?

It is commented out, with the key preserved: # deletedAt = null # omitted: TOML has no null. Writing deletedAt = "" instead would compile and be wrong — the file would read back as an empty string, and anything checking whether the field was set would get the wrong answer.

And a null inside an array?

That one becomes "", because a list has no key to omit and dropping the element would change the length. It is the one lossy case, and it is visible in the output rather than silent.

Do I get comments?

Only the ones marking dropped nulls — there are none in the JSON to carry over. TOML supports # comments freely, so a generated file is a reasonable starting point for one you then document by hand.