TOML

Working with TOML

If you have opened a Cargo.toml or a pyproject.toml, you have already read TOML. It is worth knowing why those two ecosystems chose it.

TOML was designed as a reaction to the two formats either side of it. JSON has no comments, which makes it a poor config format. YAML guesses at types, which makes it an unpredictable one. TOML v1.0.0 takes the opposite position on both: comments are part of the format, and nothing is coerced — a string is a string because it is quoted, and the parser never decides otherwise on your behalf.

Rust adopted it for Cargo manifests and Python standardised on it in PEP 621 for pyproject.toml, which between them means most developers now read TOML weekly whether or not they ever chose it.

The strictness has a sharp edge that is genuinely useful to know about. TOML is the only one of the three whose specification pins integers to signed 64-bit. Hand JSON a 19-digit identifier and JavaScript rounds it without comment; hand YAML the same and you get the same rounding; hand it to TOML and a conforming parser either holds it exactly or refuses the document. Refusing is the better failure, and it is the sort of difference that only shows up under a value nobody thought to test.

What TOML does not have is null. There is no way to express "this key exists and has no value", so a conversion from YAML or JSON that contains one has to drop the key or fail. Comments are the other thing to watch: they are the reason people choose TOML, and any tool that reformats by parsing and re-printing throws every one of them away. Taplo is the command-line formatter that gets this right, and it is the bar a web formatter has to meet.

TOML articles

TOML tools on this site

All categories