TOML

TOML
Name	TOML
Extension	.toml
Mime	text/x-toml
Type	configuration file format
Owner	Tom Preston-Werner
Released	2013
Latest release	1.0.0
Standard	Tom Preston-Werner

TOML is a configuration file format intended to be minimal, readable, and unambiguous, created to provide a clear alternative to formats such as JSON, YAML, and INI. It emphasizes a simple syntax for representing hierarchical configuration data suitable for use with build systems, package managers, and developer tools such as Cargo, Rust, and Go. The format reached a 1.0.0 specification milestone and has been adopted in ecosystems led by projects like GitHub, Mozilla, HashiCorp, and Canonical.

History

TOML was authored by Tom Preston-Werner and first announced in 2013 amid discussions involving contributors associated with GitHub, Ruby tooling, and developers participating in communities around Node.js, Python, and Go. Early adoption occurred in projects such as Cargo for Rust and the Hugo static site generator, prompting wider community engagement from organizations including Mozilla, Canonical, and HashiCorp. The specification evolved through public proposals and implementations maintained by contributors from repositories hosted on GitHub, with formalization culminating in a stable 1.0.0 release after addressing parsing ambiguities raised by implementers working with ecosystems around JavaScript, TypeScript, Python, and Java.

Design and syntax

The design goals prioritized human readability and machine parseability, influenced by prior standards such as JSON, INI, and configuration conventions used in projects like Apache HTTP Server, nginx, and systemd. Syntax features include key/value pairs, dotted keys for hierarchy inspired by Lua table access and Python attribute notation, and bracketed tables reminiscent of INI sections. String syntax draws from conventions seen in JSON and YAML, while date/time representations align with ISO 8601 practices adopted by organizations such as IETF and projects like PostgreSQL, SQLite, and Redis. The format avoids implicit typing and seeks deterministic parsing similar to goals expressed by standards committees at W3C and IETF.

Data types and values

TOML's core scalar types include strings, integers, floats, booleans, datetimes, and arrays; compound types include tables and arrays of tables. These choices reflect types used in languages and systems such as Rust, Go, Python, Java, and C#. Date/time support interoperates with ISO 8601 and implementation libraries used by PostgreSQL, MySQL, and MongoDB clients. Strings support basic and multi-line forms analogous to quoting conventions in JSON and YAML, while arrays and nested tables map to collection types familiar from JavaScript, TypeScript, and Ruby.

Parsing and libraries

Multiple parsing libraries across ecosystems implement the specification for languages such as Rust (crates like serde-based implementations), Go, Python, Java, C#, JavaScript, and TypeScript. Implementations have been developed and reviewed by contributors associated with communities around Cargo, Node.js, Deno, PyPI, and language package registries like crates.io and npm. Parser behavior and edge cases have been the subject of issues and pull requests hosted on GitHub repositories and discussed in forums such as Stack Overflow and language-specific working groups involving maintainers from projects like Hugo, Rust core teams, and Electron contributors.

Use cases and adoption

TOML is used for configuration and metadata in projects including Cargo (Rust package manager), Hugo site configuration, Poetry packaging for Python, and various tools within GitHub workflows and GitLab CI/CD pipelines. Organizations such as Mozilla, Canonical, HashiCorp, and companies building developer platforms like Microsoft, Google, and GitHub have integrated TOML-supporting tooling. It is chosen in contexts where deterministic parsing and clear typing are important, such as build systems, package manifests, editor integrations in Visual Studio Code, JetBrains, and linting tools used by Linters and continuous integration systems managed with Jenkins, CircleCI, and Travis CI.

Criticism and limitations

Critics point to limitations including a relatively small feature set compared with YAML and lack of templating or inheritance primitives found in specialized systems like Ansible or Chef recipes; this has led some projects such as those in Docker and Kubernetes ecosystems to prefer alternatives like YAML or JSON. Ambiguities in early parsing behavior required clarifications similar to issues historically encountered by JSON and XML implementers; these were resolved through specification updates and cross-implementation testing coordinated via GitHub and language community forums. Other concerns include limited expressiveness for complex configuration scenarios compared with domain-specific languages used in HashiCorp tools (e.g., HCL) and the absence of first-class schema validation akin to JSON Schema or validation frameworks used in OpenAPI toolchains.

Category:Configuration file formats