TOML

Tom’s Obvious, Minimal Language

• case-sensitive
• UTF-8 encoded Unicode document

Comment

# Full-line comment
key = "value" # comment at end of line

Key/Value pair

TOML files consist of key/value paris (one per line)

key = "value"
key = # INVALID (value cannot be empty)

Keys

Bare keys (A-Z, a-z, 0-9, _, -). These are interpreted as strings internally. And defining a key multiple times is invalid.

bare_key = "value"
bare-key = "value"
123 = "value"

Quoted key

"127.0.0.1" = "value"
"character encoding" = "value"
'quoted "value"' = "value"
"" = "blank" # discouraged though
'' = "blank" # discouraged though

Dotted keys = sequence of bare or quoted keys joined with a dot (white space around dotted characters is ignored)

name = "Orange"
physical.color = "orange"
site."google.com" = true

Values

String

basic_string = "I'm a string. \"Quote also\"\n."
multi_line_string = """
Roses are red
Violets are blue"""

# When using \ at the end, all whitespace, newlines are ignored
# till non-whitespace character is encountered.
multi_line_string2 = """\
                     Roses are red
                     Violets are brown
                     """

literal_string = 'Escaping characters is not allowed'
literal_multi_line_string = '''
This content if interpreted as-is without modification.
'''

Integer

# 64-bit signed integers are supported
int1 = 99
int2 = +99
int3 = -17
int4 = 53_49_221
int5 = 01 # INVALID. Leading zeros are not allowed (except -0, +0)

hex1 = 0xDEA
hex2 = 0xdead_beef
oct1 = 0o755
bin1 = 0b1101

Float

# IEEE 764 binary64 float
float1 = +1.0
float2 = -0.01
float3 = 5e+22
float4 = 1e06
float5 = -2E-2
float6 = 223_617.445_991_228

# special float values
spec1 = inf # inf/+inf/-inf
spec2 = nan # nan/+nan/-nan

Boolean

bool1 = true
bool2 = false

Date/Time

# RFC 3339 formatted date-time without offset
# Date-time with timezone
odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.999999-07:00

# The T can be replaced with space for readability
odt4 = 1979-05-27 07:32:00Z

# Date-time without timezone
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999

# Date only
ld1 = 1979-05-27

# Time only
lt1 = 07:32:00
lt2 = 00:32:00.999999

Array

• whitespace is ignored
• can be mixed values
• terminating comma (trailing comma) is permitted after the last value

integers = [1, 2, 3]
colors = ['red', 'yellow', "green"]
nested = [[1,2], [3,4,5]]
nested_mixed = [[1,2], ['a', 'b', 'c']]
contributors = [
  "Foo Bar <foo@example.com>",
  { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
]

Table

Also called hash tables are collections of key/value pairs. Defined using headers like [table]. They follow the same naming convention as keys.

[table-1]
key1 = "some string"
key2 = 123

[table-2]
key1 = "another string"
key2 = 456

The following TOML

[dog."tater.man"]
type.name = "pug"

is equivalent to JSON

{ "dog": { "tater.man": { "type": { "name": "pug" } } } }

Inline table

• introduced to reduce verbosity in certain situations
• intended to appear in a single line

name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }
animal = { type.name = "pug" }

The above is equivalent to

[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 2

[animal]
type.name = "pug"

Array of tables

• the first instance defines the array and its first table element
• Each subsequent instance creates and defines a new table element in that array.
• Tables are inserted into the array in the order encountered.

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

[[products]]  # empty table within the array

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

color = "gray"

Is equivalent to the following JSON

{
  "products": [
    { "name": "Hammer", "sku": 738594937 },
    {},
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}

This TOML

[[fruits]]
name = "apple"

[fruits.physical]  # subtable
color = "red"
shape = "round"

[[fruits.varieties]]  # nested array of tables
name = "red delicious"

[[fruits.varieties]]
name = "granny smith"


[[fruits]]
name = "banana"

[[fruits.varieties]]
name = "plantain"

is equivalent to the following JSON

{
  "fruits": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "varieties": [{ "name": "red delicious" }, { "name": "granny smith" }]
    },
    {
      "name": "banana",
      "varieties": [{ "name": "plantain" }]
    }
  ]
}