liminfoTOML Reference
Free reference guide: TOML Reference
About TOML Reference
The TOML Reference is a searchable cheat sheet for TOML (Tom's Obvious, Minimal Language), a configuration file format designed to be easy to read due to its clear semantics. It covers the complete TOML specification including basic key-value pairs with bare and quoted keys, dotted keys for nested structures, comments, and the distinction between basic strings with escape sequences and literal strings without them.
This reference organizes over 30 entries across six categories: Basics, Strings, Numbers, Tables, Arrays, and Date/Time. The Strings section details four string types -- basic (""), literal (''), multi-line basic (""""""), and multi-line literal ('''''') -- each with different escape handling. The Numbers section covers integers with underscore separators and hex/octal/binary representations, IEEE 754 floats including inf and nan, and boolean values.
The structured data sections cover tables (sections defined with [brackets]), nested tables using dotted notation like [a.b.c], inline tables for compact one-line representations, arrays including multi-line and mixed-type variants, and the powerful [[array of tables]] syntax for defining repeated structured entries. Date-time types include offset date-times with timezone (RFC 3339), local date-times, local dates, and local times. A practical Cargo.toml example demonstrates real-world TOML usage in Rust project configuration.
Key Features
- Key-value syntax: bare keys, quoted keys for special characters, and dotted keys for nested structures
- Four string types: basic with escapes, literal without escapes, multi-line basic, and multi-line literal
- Number formats: integers with underscore separators, hexadecimal (0x), octal (0o), binary (0b), and IEEE 754 floats
- Table definitions: standard [table], nested [a.b.c] notation, and compact inline tables { key = value }
- Array syntax: single-line arrays, multi-line arrays with trailing commas, and mixed-type arrays
- Array of tables ([[array]]) for defining lists of structured objects like server configurations
- Date-time types: RFC 3339 offset date-time, local date-time, local date, and local time with milliseconds
- Real-world Cargo.toml example showing Rust package configuration with dependencies and features
Frequently Asked Questions
What is the difference between basic and literal strings in TOML?
Basic strings use double quotes ("") and support escape sequences like \n for newline, \t for tab, and \\ for backslash. Literal strings use single quotes ('') and treat everything literally -- no escape sequences are processed. This makes literal strings ideal for regex patterns and Windows file paths where backslashes should not be interpreted as escape characters.
How do tables and nested tables work in TOML?
Tables are defined with [table_name] and contain key-value pairs until the next table header. Nested tables use dotted notation: [server.production] creates a "production" table inside "server". This is equivalent to writing the keys as server.production.host = "value". Inline tables like point = { x = 1, y = 2 } provide a compact single-line alternative for small tables.
What is the [[array of tables]] syntax?
Double brackets [[name]] define an array of tables, creating a new table element each time the header appears. Each [[fruits]] block adds a new entry to the fruits array. This is the TOML way to represent a list of objects, equivalent to a JSON array of objects. It is commonly used for defining multiple similar configurations like server entries, dependencies, or rules.
What number formats does TOML support?
TOML supports integers with optional underscore separators for readability (1_000_000), hexadecimal (0xDEADBEEF), octal (0o755), and binary (0b11010110) representations. Floats follow IEEE 754 and support scientific notation (5e+22), special values inf and nan, and underscore separators (1_000.5). Booleans are lowercase true and false.
How do I represent dates and times in TOML?
TOML has four date-time types: offset date-time with timezone (1979-05-27T07:32:00Z or +09:00), local date-time without timezone (1979-05-27T07:32:00), local date only (1979-05-27), and local time only (07:32:00 or 07:32:00.999 with fractional seconds). The T separator between date and time can optionally be replaced with a space.
What are dotted keys and when should I use them?
Dotted keys like physical.color = "orange" are shorthand for nested table structures. They are equivalent to defining a [physical] table with color = "orange" inside it. Use dotted keys when you only need to set one or two values in a nested structure. For multiple values, a full [table] section is more readable. Bare keys allow alphanumerics, hyphens, and underscores; use quoted keys for anything else.
How is TOML used in Rust projects?
Every Rust project has a Cargo.toml file that defines the package name, version, and edition under [package], and lists dependencies under [dependencies]. Dependencies can be simple version strings or inline tables with version and features keys, like serde = { version = "1.0", features = ["derive"] }. Workspace configurations, build profiles, and target-specific dependencies also use TOML tables and arrays.
What are the differences between TOML, YAML, and JSON for configuration?
TOML is designed specifically for configuration files with unambiguous semantics -- there is exactly one way to represent each value. Unlike YAML, TOML has no indentation-sensitive parsing and no surprising type coercions (like "no" becoming false). Unlike JSON, TOML supports comments, date-time types natively, and multi-line strings. TOML is used by Rust (Cargo), Python (pyproject.toml), and Hugo among others.