TOML Format Specification

Structure

TOML organizes configuration into tables and key-value pairs. A table header in square brackets introduces a namespace, and dotted keys create nested tables implicitly. Tables must be defined before their keys, and redefining a table is an error. The root table contains keys before any header. This explicit structure makes TOML more predictable than INI while remaining human-readable.

table

Section header in square brackets

[server]

array of tables

Double brackets, repeated entries

[[products]]

dotted key

Nested key path

a.b.c = 1

inline table

Single-line table in curly braces

point = {x=1, y=2}

Value Types

TOML supports strings, integers, floats, booleans, datetimes, arrays, and tables. Strings have basic (single-quote), literal (single-quote single-quote), and multiline variants. Integers may use underscores as digit separators and leading plus signs. Datetimes are RFC 3339 compliant and can be offset, local, or date-only. The type system is richer than JSON, making TOML suitable for configuration where types matter.

Comparison with JSON and YAML

TOML occupies a middle ground between JSON and YAML for configuration files. Unlike JSON, it supports comments and avoids the quoting noise of string-heavy configs. Unlike YAML, it has a strict grammar that prevents accidental type coercion and security issues. The trade-off is that TOML is less compact for deeply nested data. For application configuration, TOML's explicitness is usually an advantage.