TOML stands for Tom’s Obvious, Minimal Language. It is a data serialisation language designed to be a minimal configuration file format that’s easy to read due to obvious semantics.
It is an alternative to YAML and JSON. It aims to be more human friendly than JSON and simpler that YAML. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.
This document follows TOML v1.0.0. Future changes are expected to be minor and backwards-compatible.
1# Comments in TOML look like this.
2
3################
4# SCALAR TYPES #
5################
6
7# Our root object (which continues for the entire document) will be a map,
8# which is equivalent to a dictionary, hash or object in other languages.
9
10# The key, equals sign, and value must be on the same line
11# (though some values can be broken over multiple lines).
12key = "value"
13string = "hello"
14number = 42
15float = 3.14
16boolean = true
17dateTime = 1979-05-27T07:32:00-08:00
18scientificNotation = 1e+12
19"key can be quoted" = true # Both " and ' are fine
20"unquoted key may contain" = "letters, numbers, underscores, and dashes"
21other_kêys = "are permitted by spec but most implementations don't actually permit them"
22
23# A bare key must be non-empty, but an empty quoted key is allowed
24"" = "blank" # VALID but discouraged
25'' = 'blank' # VALID but discouraged
26
27##########
28# String #
29##########
30
31# All strings must contain only valid UTF-8 characters.
32# We can escape characters and some of them have a compact escape sequence.
33# For example, \t add a tabulation. Refers to the spec to get all of them.
34basicString = "are surrounded by quotation marks. \"I'm quotable\". Name\tJos"
35
36multiLineString = """
37are surrounded by three quotation marks
38on each side and allow newlines."""
39
40literalString = 'are surrounded by single quotes. Escaping are not allowed.'
41
42multiLineLiteralString = '''
43are surrounded by three single quotes on each side
44and allow newlines. Still no escaping.
45The first newline is trimmed in raw strings.
46 All other whitespace
47 is preserved. #! are preserved?
48'''
49
50# For binary data it is recommended that you use Base64, another ASCII or UTF8
51# encoding. The handling of that encoding will be application specific.
52
53###########
54# Integer #
55###########
56
57## Integers can start with a +, a - or nothing.
58## Leading zeros are not allowed.
59## Hex, octal, and binary forms are allowed.
60## Values that cannot be expressed as a series of digits are not allowed.
61int1 = +42
62int2 = 0
63int3 = -21
64int4 = 0xdeadbeef
65int5 = 0o755
66int6 = 0b11011100
67integerRange = 64
68
69## You can use underscores to enhance readability. Each
70## underscore must be surrounded by at least one digit.
71int4 = 5_349_221
72int5 = 1_2_3_4_5 # VALID but discouraged
73
74#########
75# Float #
76#########
77
78# Floats are an integer followed by a fractional and/or an exponent part.
79flt1 = 3.1415
80flt2 = -5e6
81flt3 = 6.626E-34
82
83###########
84# Boolean #
85###########
86
87bool1 = true
88bool2 = false
89boolMustBeLowercase = true
90
91############
92# Datetime #
93############
94
95date1 = 1979-05-27T07:32:00Z # UTC time, following RFC 3339/ISO 8601 spec
96date2 = 1979-05-26T15:32:00+08:00 # with RFC 3339/ISO 8601 offset
97date3 = 1979-05-27T07:32:00 # without offset
98date4 = 1979-05-27 # without offset or time
99
100####################
101# COLLECTION TYPES #
102####################
103
104#########
105# Array #
106#########
107
108array1 = [ 1, 2, 3 ]
109array2 = [ "Commas", "are", "delimiters" ]
110array3 = [ "Don't mix", "different", "types" ]
111array4 = [ [ 1.2, 2.4 ], ["all", 'strings', """are the same""", '''type'''] ]
112array5 = [
113 "Whitespace", "is", "ignored"
114]
115
116#########
117# Table #
118#########
119
120# Tables (or hash tables or dictionaries) are collections of key/value
121# pairs. They appear in square brackets on a line by themselves.
122# Empty tables are allowed and simply have no key/value pairs within them.
123[table]
124
125# Under that, and until the next table or EOF are the key/values of that table.
126# Key/value pairs within tables are not guaranteed to be in any specific order.
127[table-1]
128key1 = "some string"
129key2 = 123
130
131[table-2]
132key1 = "another string"
133key2 = 456
134
135# Dots are prohibited in bare keys because dots are used to signify nested tables.
136# Naming rules for each dot separated part are the same as for keys.
137[dog."tater.man"]
138type = "pug"
139
140# In JSON land, that would give you the following structure:
141# { "dog": { "tater.man": { "type": "pug" } } }
142
143# Whitespace around dot-separated parts is ignored, however, best practice is to
144# not use any extraneous whitespace.
145[a.b.c] # this is best practice
146[ d.e.f ] # same as [d.e.f]
147[ j . "ʞ" . 'l' ] # same as [j."ʞ".'l']
148
149# You don't need to specify all the super-tables if you don't want to. TOML knows
150# how to do it for you.
151# [x] you
152# [x.y] don't
153# [x.y.z] need these
154[x.y.z.w] # for this to work
155
156# As long as a super-table hasn't been directly defined and hasn't defined a
157# specific key, you may still write to it.
158[a.b]
159c = 1
160
161[a]
162d = 2
163
164# Will generate the following in JSON:
165# { "a": {"b": {"c": 1}, "d": 2 } }
166
167# You cannot define any key or table more than once. Doing so is invalid.
168
169# DO NOT DO THIS
170[a]
171b = 1
172
173[a]
174c = 2
175
176# DO NOT DO THIS EITHER
177[a]
178b = 1
179
180[a.b]
181c = 2
182
183# All table names must be non-empty.
184[] # INVALID
185[a.] # INVALID
186[a..b] # INVALID
187[.b] # INVALID
188[.] # INVALID
189
190################
191# Inline table #
192################
193
194inlineTables = { areEnclosedWith = "{ and }", a = { b = { c = { d = 1 } } } }
195point = { x = 1, y = 2 }
196usingMultiple = {
197 lines = "discouraged!",
198 instead = "use normal TOML tables",
199}
200
201###################
202# Array of Tables #
203###################
204
205# An array of tables can be expressed by using a table name in double brackets.
206# Each table with the same double bracketed name will be an item in the array.
207# The tables are inserted in the order encountered.
208
209[[products]]
210name = "array of table"
211sku = 738594937
212emptyTableAreAllowed = true
213
214[[products]]
215
216[[products]]
217name = "Nail"
218sku = 284758393
219color = "gray"
The equivalent in JSON would be:
1{
2 "products": [
3 {
4 "name": "array of table",
5 "sku": 7385594937,
6 "emptyTableAreAllowed": true
7 },
8 {},
9 {
10 "name": "Nail",
11 "sku": 284758393,
12 "color": "gray"
13 }
14 ]
15}
1# You can create nested arrays of tables as well. Each double-bracketed
2# sub-table will belong to the nearest table element above it.
3
4[[fruit]]
5 name = "apple" # I am a property in fruit table/map
6
7 [fruit.geometry]
8 shape = "round"
9 note = "I am a property in geometry table/map"
10
11 [[fruit.color]]
12 name = "red"
13 note = "I am an array item in apple fruit's table/map"
14
15 [[fruit.color]]
16 name = "green"
17 note = "I am in the same array as red"
18
19[[fruit]]
20 name = "banana"
21
22 [[fruit.color]]
23 name = "yellow"
24 note = "I am an array item in banana fruit's table/map"
The equivalent in JSON would be:
{
"fruit": [
{
"name": "apple",
"geometry": { "shape": "round", "note": "..."},
"color": [
{ "name": "red", "note": "..." },
{ "name": "green", "note": "..." }
]
},
{
"name": "banana",
"color": [
{ "name": "yellow", "note": "..." }
]
}
]
}