What is TOML?
TOML is a configuration file format designed to be easy to read due to its obvious semantics, mapping unambiguously to a hash table while remaining simple to parse.
Quick Facts
| Full Name | Tom's Obvious Minimal Language |
|---|---|
| Created | 2013 by Tom Preston-Werner |
| Specification | Official Specification |
How It Works
TOML was created by Tom Preston-Werner (GitHub co-founder) in 2013 as a configuration format that prioritizes human readability and simplicity. Unlike YAML which can be complex and error-prone with its significant whitespace, TOML uses explicit syntax with clear delimiters. It maps directly to hash tables, making it ideal for configuration files. TOML supports strings, integers, floats, booleans, datetimes, arrays, and tables (sections). Comments begin with #. The format gained popularity in the Rust ecosystem (Cargo.toml), Python packaging (pyproject.toml), and various other tools. TOML strikes a balance between JSON's strictness and YAML's flexibility, avoiding YAML's gotchas like the 'Norway Problem' (NO being interpreted as false). Its explicit datetime support and clear table syntax make it particularly suitable for application configuration.
Key Characteristics
- Human-readable with obvious, minimal syntax
- Maps directly to hash tables/dictionaries
- Explicit datetime support (ISO 8601 format)
- Supports tables (sections) and nested tables
- Comments with # (unlike JSON)
- No significant whitespace issues (unlike YAML)
Common Use Cases
- Rust project configuration (Cargo.toml)
- Python packaging (pyproject.toml)
- Application configuration files
- Static site generators (Hugo, Zola)
- Development tool configuration
Example
Loading code...Frequently Asked Questions
What is the difference between TOML, YAML, and JSON for configuration files?
TOML prioritizes human readability with explicit syntax and no whitespace significance. YAML uses indentation-based structure, which can be error-prone. JSON is strict and widely supported but doesn't allow comments. TOML is ideal for configuration files where humans edit directly; JSON for data interchange; YAML when you need complex structures.
How do I define nested tables (sections) in TOML?
Use dot notation in table headers for nested structures: [servers.alpha] creates a table 'alpha' inside 'servers'. Alternatively, use inline tables for simple cases: server = { ip = '10.0.0.1', port = 8080 }. For arrays of tables, use double brackets: [[products]] creates an array entry.
Why was TOML created when YAML already existed?
TOML was created to address YAML's complexity and error-prone whitespace sensitivity. YAML's implicit typing can cause issues (like the 'Norway Problem' where 'NO' becomes false). TOML offers explicit syntax, simpler parsing, and maps directly to hash tables, making it less ambiguous and easier to use correctly.
Which programming languages support TOML?
TOML has parser libraries for virtually all major languages including Python (tomli, tomlkit), JavaScript (toml, @iarna/toml), Rust (toml crate - native support), Go (BurntSushi/toml), Java, C#, Ruby, and more. Rust's Cargo and Python's pyproject.toml have made TOML mainstream.
How do I specify dates and times in TOML?
TOML has native datetime support using ISO 8601 format. Examples: date = 2024-01-15, time = 14:30:00, datetime = 2024-01-15T14:30:00Z, local-datetime = 2024-01-15T14:30:00. Timezone offsets are supported: 2024-01-15T14:30:00-05:00. This is a key advantage over JSON which lacks native date types.