TOML is small enough to learn in one sitting, but a few rules are not obvious, and most parse errors come from them. This guide covers the constructs you will use and the mistakes to avoid. It follows TOML 1.0.
Keys and values
A key and value are separated by =, with the value on the same line:
name = "docento"
Bare keys may contain letters, digits, underscores and dashes. Quote a key to use spaces or other characters: "my key" = 1. Dots in a key create nested tables: site.name = "x" is the same as a name key inside a site table. A key cannot be defined twice.
Strings
- Basic:
"line\nwith escapes" - Multi-line basic: triple double quotes. A backslash at the end of a line trims the newline and following whitespace.
- Literal:
'C:\Users\Ada'. No escapes, so Windows paths are easy. - Multi-line literal: triple single quotes.
A leading newline right after the opening triple quote is trimmed.
Numbers and booleans
count = 1_000
pi = 3.14
mask = 0xFF
big = 1e6
ok = true
Integers cannot have leading zeros, and + signs are allowed. inf and nan are valid floats. Booleans must be lowercase.
Dates and times
TOML has four date-time types, all RFC 3339 style:
offset = 2025-04-03T07:30:00Z
local_dt = 2025-04-03T07:30:00
local_date = 2025-04-03
local_time = 07:30:00
These are not strings, so there are no quotes. A parser returns real date objects, depending on the language.
Arrays
ports = [80, 443]
names = [
"alpha",
"beta", # trailing comma allowed
]
Arrays can span lines, may contain comments and allow trailing commas. In TOML 1.0, arrays may contain mixed types.
Tables
A table groups keys under a heading in square brackets:
[server]
host = "localhost"
[server.tls]
enabled = true
Everything after a header belongs to that table until the next header. A table can be defined only once, so defining [server] twice is an error. Also remember that a key written after a table header belongs to that table, so top-level keys must come before the first header.
Inline tables
For a small mapping on one line:
point = { x = 1, y = 2 }
Inline tables must be written on a single line (TOML 1.0), cannot have trailing commas and are fully defined where written, so you cannot add keys to them later. For anything bigger, use a regular table.
Arrays of tables
Double brackets add an item to a list of tables:
[[products]]
name = "Hammer"
sku = 738594937
[[products]]
name = "Nail"
sku = 284758393
This produces a products array with two tables, and is the TOML way to write a list of records.
Comments and whitespace
Comments start with # and run to the end of the line. Indentation and blank lines are ignored, so use them freely for readability.
Common errors
- Duplicate keys or tables. Always an error.
- Unquoted strings:
name = docentois invalid; it must be"docento". - Capitalised booleans such as
True. - Leading zeros on integers.
- A top-level key placed after a table header. It is not a syntax error, but the key silently belongs to that table. Put top-level keys before the first header.
- Multi-line inline tables or trailing commas in them.
- Mixing a table and a dotted key for the same name.
- Unclosed strings or brackets.
Checking a file
A TOML parser reports the first problem and stops. Docento's Text & Markdown Editor parses .toml files in the browser as you type and shows an error with the line number where it can. If you are choosing a format, see what is a TOML file and TOML vs YAML vs JSON.
Takeaway
TOML is key/value pairs, tables in square brackets, arrays of tables in double brackets, and native dates. Quote strings, keep keys unique, put top-level keys first and validate as you edit.
