Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 39 ยท TOML, CSV and Other Formats

TOML in Depth

Learn TOML, the explicit configuration format - key/value pairs, strings, numbers, dates, arrays, tables, inline tables and arrays of tables - with a runnable subset parser in Node.

TOML ("Tom's Obvious, Minimal Language") is a configuration format designed to be unambiguous. Where YAML guesses types from plain text (see YAML Gotchas), TOML makes the type visible in the syntax: strings are always quoted, numbers never are, and dates have their own literal form. It maps cleanly to a hash table, and a file means the same thing in every parser. You will see it in pyproject.toml, Cargo.toml, Hugo and Netlify settings, and many tools' config files.

The runner here has no TOML library. The TryIt blocks use a small stand-in parser for the subset shown in this lesson (no multi-line strings, no dotted keys with quotes). For real projects use tomllib (in the Python 3.11+ standard library), smol-toml or @iarna/toml in JavaScript, the toml crate in Rust, or BurntSushi/toml in Go.

Key/value pairs

A TOML file is a list of key = value lines. Whitespace around = is optional, comments start with #, and keys are case-sensitive.

TOML
title = "Shop API"        # a comment
port = 8080
ratio = 0.75
debug = false

Bare keys may contain letters, digits, dashes and underscores. Anything else needs quotes: "site name" = "x". Dotted keys create nested tables: server.port = 80 is the same as a [server] table holding port.

Strings

TOML has four string forms:

TOML
basic = "tab\there, unicode \u00e9"        # escapes allowed
literal = 'C:\Users\nodejs\templates'      # no escapes at all
multi = """
Roses are red
Violets are blue"""                        # first newline trimmed
raw_multi = '''
No \escapes here
'''

Basic strings use \n, \t, \", \\ and \uXXXX escapes. Literal strings (single quotes) are taken exactly as written, which is ideal for Windows paths and regular expressions. In multi-line basic strings, a trailing backslash trims the following whitespace.

Numbers, booleans and dates

TOML
int = 42
big = 1_000_000          # underscores for readability
hex = 0xDEADBEEF
float = 3.14
sci = 6.02e23
inf = inf
nan = nan
yes = true               # only true and false; never yes/no

Dates and times are first-class values (RFC 3339):

TOML
released = 2025-03-14                  # local date
at = 07:32:00                          # local time
created = 1979-05-27T07:32:00Z         # offset date-time (UTC)
local = 1979-05-27T07:32:00-08:00

Because dates are real values, a parser returns a date object instead of a string. If you need text, quote it.

Arrays

Arrays use brackets and may span lines; a trailing comma is allowed. Since TOML 1.0 an array may mix types.

TOML
ports = [80, 443, 8080]
names = [
  "alpha",
  "beta",
]
matrix = [[1, 2], [3, 4]]

Tables

A table is a named group of keys, introduced by a header in square brackets. The header applies to all following keys until the next header.

TOML
[server]
host = "localhost"
port = 8080

[server.tls]            # a nested table: server -> tls
enabled = true
cert = "cert.pem"

This produces the same data as the JSON {"server": {"host": "localhost", "port": 8080, "tls": {"enabled": true, "cert": "cert.pem"}}}. Defining the same table twice is an error, and so is a key that clashes with a table of the same name.

Inline tables put a small table on one line, in braces: point = { x = 1, y = 2 }. They must stay on one line and cannot be extended later.

Arrays of tables

A double-bracket header adds one more item to an array of tables, which is how TOML writes a list of records:

TOML
[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"

The data is {"servers": [{"name": "alpha", "ip": "10.0.0.1"}, {"name": "beta", "ip": "10.0.0.2"}]}. Each [[servers]] starts a new element, and sub-tables such as [servers.limits] attach to the latest element.

Node.js Parse a TOML subset (stand-in parser)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The dotted header [server.tls] became a nested object, and the two [[servers]] headers became an array with two objects.

TOML versus YAML versus JSON

flowchart LR
  J["JSON: strict, no comments, machine-friendly"] --- T["TOML: explicit types, flat tables, config-friendly"]
  T --- Y["YAML: flexible, deep nesting, guesses types"]

TOML sits between the strictness of JSON and the flexibility of YAML.

TOML's strengths are clarity and safety. Its weakness is deep nesting: a structure several levels deep needs long headers like [a.b.c.d] or many inline tables, so TOML is rarely the best fit for large, deeply nested documents. For a settings file with sections and a few lists of records, it is excellent.

Node.js Convert parsed TOML data into the equivalent JSON and back to TOML text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

JSON's string, number and flat-array syntax is also valid TOML, which makes this tiny writer possible. Real writers also handle special keys, dates and nested arrays.

Common mistakes

  • Redefining a table. [server] twice is an error; keep each table's keys together.
  • Using yes/no. TOML booleans are only true and false.
  • Mixing a key and a table of the same name. a = 1 followed by [a] is invalid.
  • Multi-line inline tables. Inline tables must fit on one line (TOML 1.0).
  • Unquoted values. name = alpha is invalid: strings need quotes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you write a string in TOML?

    TOML strings are always quoted. Double quotes allow escapes; single quotes are literal.
  2. 2. What does [[servers]] define?

    A double-bracket header appends one table to an array. Repeating it adds more elements.
  3. 3. Which value is a valid TOML date?

    TOML has a local date literal in RFC 3339 form, written without quotes.
  4. 4. Why is TOML considered safer than YAML for config?

    Strings must be quoted and booleans are only true/false, so there is no Norway problem.

Summary

  • TOML is key = value plus [tables], with explicit types: quoted strings, bare numbers, booleans, RFC 3339 dates.
  • Dotted keys and headers nest; [[name]] builds arrays of tables; inline tables fit on one line.
  • Literal strings (single quotes) are ideal for paths and patterns.
  • It is great for flat-to-moderate settings and awkward for deep nesting.
  • The parser here is a stand-in; use a real library in production.

Next: CSV Parsing and Its Pitfalls