What is TOML?

Designed to remove ambiguity

TOML exists because INI files were never specified and YAML was considered too subtle. Its goal is a configuration format that maps unambiguously onto a hash table, with an explicit type for every value and no inference to be surprised by.

The building block is the table, written as a bracketed header. Keys before any header belong to the root table. A repeated double-bracket header declares an array of tables, which is how TOML expresses a list of records.

service = "checkout-api"

[[orders]]
currency = "USD"
id = "ord_101"
status = "paid"
total = 129.5

[[orders]]
currency = "USD"
id = "ord_102"
status = "failed"
total = 42

Types TOML has that JSON does not

TOML distinguishes integers from floats — a genuine difference from JSON's single number type — and it has first-class date, time, and offset date-time values, so a timestamp in a TOML file is a timestamp rather than a string that everyone agrees to parse. It also supports underscores in numeric literals for readability, and both basic and literal string forms.

Converting TOML to JSON therefore loses information: the integer/float distinction collapses, and a date becomes a string. Converting the other way, a JSON string that looks like a date stays a string, because guessing would be worse.

Where it stops being comfortable

TOML is at its best when configuration is broad and shallow, which is exactly the shape of Cargo.toml and pyproject.toml. Deep nesting reads poorly: every level adds a dotted segment to the table header, and a deeply nested structure becomes a wall of long bracketed names.

There is also no null. A JSON document containing null has no direct TOML equivalent, and the usual answer is to omit the key entirely — which is a different statement from 'this key is present and empty'.