TOML
By Tom Preston-Werner
TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy for humans to read and write while mapping unambiguously onto a data structure that programs can parse reliably. It uses simple key-value pairs,…
Definition
TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to be easy for humans to read and write while mapping unambiguously onto a data structure that programs can parse reliably. It uses simple key-value pairs, sections denoted by bracketed headers, and native support for common data types like strings, integers, dates, and arrays, without relying on significant whitespace.
Overview
Software projects need a way to store configuration — settings, dependency lists, build parameters — in a file that both a person editing it by hand and a program parsing it automatically can handle without ambiguity. Older formats used for this purpose each have drawbacks: INI files lack a formal standard and vary between implementations, while YAML's flexible, whitespace-sensitive syntax has produced well-documented parsing surprises for developers. TOML was created explicitly to occupy the gap between those options, favoring an unambiguous grammar over YAML's expressive but error-prone one. A TOML document is organized as key-value pairs grouped under bracketed table headers, similar in appearance to classic INI files, but with a formal specification defining exact rules for strings, numbers, booleans, arrays, inline tables, and datetimes, so a compliant parser in any language produces the same data structure from the same file every time, regardless of implementation language. This precision is TOML's core mechanical distinction: rather than inferring types loosely from context the way some INI dialects do, every value has an explicit, specified type that a parser can rely on. Among configuration formats, TOML sits between the minimalism of INI and the full expressiveness of YAML or JSON: it is more structured and typed than INI, but intentionally less powerful than YAML, deliberately omitting features like anchors and complex nested flow syntax that make YAML both flexible and prone to misconfiguration. Unlike JSON, TOML is designed to be comfortably hand-edited, with support for comments that JSON lacks entirely, which matters for files developers touch directly and often. In practice, TOML has become the standard configuration format for several major programming ecosystems, most notably Rust's Cargo package manager and Python's packaging metadata file, where project dependencies, build settings, and metadata are declared in TOML syntax. It is commonly chosen for project-level configuration files that developers edit directly and check into version control alongside their source code, since it stays legible even after many contributors have modified it. TOML's minimalism, while reducing footguns, also means it is less suited to deeply nested or highly dynamic configuration structures where YAML's compactness or JSON's universal tooling support may be preferable for large data payloads exchanged between services. It also lacks YAML's ability to reference and reuse values via anchors, so highly repetitive configurations can require more verbose TOML than the equivalent YAML file would, a trade-off most projects accept for the readability gained in return over time.
Specification
- Uses key-value pairs grouped under bracketed table headers
- Defines a formal, unambiguous grammar with explicit value types
- Supports native strings, integers, floats, booleans, and datetimes
- Allows comments, unlike JSON
- Designed to be comfortably hand-edited by developers
- Adopted as the standard format for Rust Cargo and Python packaging metadata