TOML

TOML

Filename extension	.toml
Internet media type	Not registered
Developed by	Tom Preston-Werner Community
Initial release	23 February 2013 (2013-02-23)
Latest release	v1.0.0 January 11, 2021 (2021-01-11)
Type of format	Data interchange
Free format?	Yes
Website	toml.io

TOML is a file format for configuration files. It is intended to be easy to read and write due to obvious semantics which aim to be "minimal", and is designed to map unambiguously to a dictionary. Its specification is open-source, and receives community contributions. TOML is used in a number of software projects, and is implemented in many programming languages. The name "TOML" is an acronym for "Tom's Obvious, Minimal Language" referring to its creator, Tom Preston-Werner.

Syntax

TOML's syntax primarily consists of key = "value" pairs, [section names], and # comments. TOML's syntax somewhat resembles that of .INI files, but it includes a formal specification, whereas the INI file format suffers from many competing variants.

Its specification includes a list of supported data types: String, Integer, Float, Boolean, Datetime, Array, and Table.

Example

# This is a TOML document.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

Comparison to other formats

The following table draws on the TOML specification to make a comparison to other popular configuration formats (INI, JSON, and YAML). See also BespON as introduced at SciPy 2017, as well as a discussion of using TOML for parametrization of simulation modeling.

Format comparison

Format	Formal standard	Flexible standard	Strongly typed	Easy implementation	Human-readable	Allows comments
JSON	Yes	No	Yes	Yes	Yes	No
YAML	Yes	No	Yes	No	Yes	Yes
TOML	Yes	No	Yes	Yes	Yes	Yes
INI	No	Yes	No	Yes	Yes	Yes

Criticism

Since its first release TOML has received several critiques. The StrictYAML project lists the following points as problematic in TOML:

• TOML is verbose, it is not DRY and it is syntactically noisy
• TOML's hierarchies are difficult to infer from syntax alone
• Overcomplication: Like YAML, TOML has too many features
• In TOML the syntax determines the data types ("syntax typing")

The libconfini project has since released a more extensive critique of TOML from the INI perspective, listing the following points (among others) as problematic:

• TOML lets the configuration file decide about data types (syntax typing), when de facto it is the client application that decides, and any mismatching type will be anyway either ignored or converted to the expected type (depending on the parser)
• TOML re-introduces what human-friendly languages normally try to get rid of: a verbose syntax and the necessity of using quotes for strings
• TOML syntax is always case-sensitive, despite the fact that there are situations where configuration files must be case-insensitive (as, for instance, configuration files that map a FAT32 filesystem or HTML tags)
• TOML uses square brackets for arrays, although square brackets are already reserved for table names; furthermore any special syntax for arrays brings the language back to syntax typing
• A TOML table must be populated in a single step, so merging multiple TOML files is problematic
• TOML arbitrarily introduces a syntax for dates
• TOML allows (but discourages) the empty string as a key
• TOML's rules cannot be inferred from the content, therefore editing a TOML file requires prior knowledge of the language
• TOML is backward-incompatible with INI

See also

• INI File
• JSON
• Recfiles
• YAML

External links

• Official website
• toml on GitHub