TOML Format Specification & Minimal Config Guide

TOML (Tom's Obvious, Minimal Language) 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 hash table.

Introduction

TOML is designed to be a better configuration format than INI, JSON, or YAML. It is widely used in the Rust community (Cargo) and Python community (pyproject.toml).

Key Features

Obvious Semantics: Easy to read and understand.
Unambiguous: Maps directly to a hash table.
Strong Typing: Supports strings, integers, floats, booleans, dates, and arrays.
Minimal: No unnecessary syntax.

Syntax

TOML consists of key-value pairs, sections (tables), and arrays.

Key-Value Pairs

key = "value"
number = 42

Tables

Tables are defined by headers in square brackets.

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

Arrays

ports = [ 8001, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]

Example

# This is a TOML document

title = "TOML Example"

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

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

[servers]

  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

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

Use Cases

Project Configuration: Cargo.toml (Rust), pyproject.toml (Python), poetry.lock.
Application Configuration: Used by Hugo (static site generator) and many other tools.