.TOML File Format – Syntax and types

Basics

• White space is tab (0x09) or space (0x20); a newline is LF (0x0A) or CR LF (0x0D 0x0A).
• # starts a comment to the end of the line (not inside strings). The prose says control characters other than tab (U+0000 to U+0008, U+000A to U+001F, U+007F) are not permitted in comments; the 1.0.0 ABNF’s non-eol = %x09 / %x20-7F / non-ascii does admit U+007F.
• A key/value pair is key = value; the key, the equals sign and the value must be on the same line (some values can span lines), and a newline or end of file must follow. A key with no value is invalid.

Keys

Defining the same key twice is invalid (a bare key and the same key quoted are equivalent), as is giving a key a value and then using it as a table.

Strings

Escapes: \b, \t, \n, \f, \r, \", \\, \uXXXX and \UXXXXXXXX (the code must be a Unicode scalar value). All other escape sequences are reserved, and TOML should produce an error if one is used. In basic strings the quotation mark, backslash and control characters other than tab must be escaped; multi-line basic strings also allow raw LF and CR.

Numbers and booleans

• Integers: +99, -17, 1_000 (each underscore between digits), 0xDEADBEEF, 0o755, 0b11010110. No leading zeros in decimal; hex, octal and binary are for non-negative values, take no leading +, and may have leading zeros after the prefix. The range −2⁶³ to 2⁶³−1 should be accepted losslessly; an integer that cannot be represented losslessly must be an error.
• Floats should be IEEE 754 binary64: 3.1415, -0.01, 5e+22, 6.626e-34; a decimal point needs digits on both sides. Special values (always lower case) inf, +inf, -inf, nan, +nan, -nan.
• Booleans: true and false, lower case.

Dates and times

Millisecond precision is required for fractional seconds; further precision is implementation-specific, and digits beyond what an implementation supports must be truncated, not rounded.

Arrays and tables

• Arrays: [ 1, 2, 3 ], values of any types mixed, new lines and comments allowed between values, a trailing comma allowed.
• Tables: a header [name] (dotted or quoted keys allowed) followed by its pairs until the next header. A table may be defined only once; defining [a.b] first and [a] later is allowed.
• Inline tables: { x = 1, y = 2 }, intended to appear on one line (no newlines between the braces unless valid within a value), no trailing comma. They are self-contained: keys and sub-tables cannot be added outside the braces.
• Arrays of tables: each [[name]] header adds a new table to the array name; following [name.sub] headers belong to its last element.

[[products]]
name = "Hammer"
sku = 738594937

[[products]]  # empty table within the array

[[products]]
name = "Nail"
sku = 284758393

color = "gray"

That is the specification’s example. Appending with [[name]] to an array defined statically (name = [ … ]) is an error, as is reusing a name as both a table and an array of tables.

Changes in TOML 1.1.0

The changelog lists these changes for 1.1.0 (2025-12-18):

• Inline tables may contain newlines and a trailing comma.
• Basic strings gain \xHH for code points up to 255 and \e for the escape character.
• Seconds are optional in date-time and time values (2010-02-03 14:15, 14:15).
• Clarifications: comments never affect the tables produced; Unicode and UTF-8 references; where and how dotted keys define tables; newline normalisation in multi-line literal strings; sub-millisecond precision is allowed; parsers are free to support any integer or float size.