TOML: What the toml-lang/toml Specification Repository Actually Contains

What the toml-lang/toml Repository Is, and What It Is Not

This repository contains the in-development version of the TOML specification. The README says so directly, and points readers to https://toml.io for released versions. That distinction matters more than it first appears. If you arrived here looking for a library to add to your dependency list, there is nothing to install. The top-level entries are .gitattributes, .pre-commit-config.yaml, .prettierrc.toml, CHANGELOG.md, LICENSE, README.md, docs/, logos/, scripts/, toml.abnf and toml.md. The specification itself lives in toml.md, and toml.abnf is an ABNF grammar for it. The scripts/ directory supports the repository's own tooling, not a consumer-facing API.

The audience is therefore narrow and specific. You are in the right place if you are implementing a TOML parser or encoder and need the normative text and the grammar. You are also in the right place if you are writing documentation that must quote the specification accurately. You are in the wrong place if you want to read a config file today. The project wiki catalogs implementations, validators, a language-agnostic test suite for decoders and encoders, editor support, encoders and converters. That wiki is where a normal user should be looking.

The licence is MIT. For a specification repository that is a permissive choice, and it means you can quote the text and reuse the ABNF grammar in your own project without a licensing conversation. It does not grant you anything about third-party implementations, which carry their own licences.

The Design Objective: Unambiguous Mapping to a Hash Table

The README states the objective plainly: TOML aims to be a minimal configuration file format that is easy to read due to obvious semantics, and is designed to map unambiguously to a hash table. That second clause is the one that drives every other decision in the format. A TOML document always has a hash table at the top level. Keys nest inside it. There is no ambiguity about what a given construct resolves to.

The README's own example shows the shape of the data flow. A bare key-value line such as title = "TOML Example" sets a top-level entry. A table header in square brackets opens a nested hash table, so [owner] followed by name = "Tom Preston-Werner" produces a hash table at the key owner with a name entry inside it. Dotted headers go deeper: [servers.alpha] and [servers.beta] both live under servers. Arrays can hold mixed nesting, as in data = [ ["gamma", "delta"], [1, 2] ], and the README notes that line breaks are allowed inside arrays, which lets long lists wrap across lines without a continuation character.

Dates are a first-class type. The example writes dob = 1979-05-27T07:32:00-08:00 and annotates it as "First class dates". That is a meaningful difference from formats where a date is just a string you have to parse yourself and hope the other side agrees on the format. Comments use the hash character, so a line can carry an explanation next to the value it describes. The README also notes that indentation with tabs, spaces, or neither is allowed but not required, which removes a class of arguments that plague whitespace-significant formats.

A TOML Example You Can Read Before Choosing a Parser

The README's example is the fastest way to judge whether the syntax suits your configuration. It is reproduced here because it is the canonical illustration the project itself uses, and because reading it takes less time than installing anything.

# 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

Three things are worth noticing. The ports array holds integers, not strings, so a parser that hands you back quoted values is doing something wrong. The enabled key is a boolean, not the string "true". And the comment after the date sits on the same line as the value, which is the style the format encourages: explanation adjacent to the thing explained.

What you should see when you read this is a file where every line has exactly one plausible interpretation. There is no implicit type coercion based on surrounding context, no anchor or alias mechanism, and no indentation rule that changes meaning. That is the whole point of the format, and the example is designed to demonstrate it in about a dozen lines. The README does not document a command-line validator or a reference parser, so there is no install step to give you here. To run this file, pick a decoder from the implementations list in the project wiki.

Where TOML Stops Working: Serialization and Streaming

The README is unusually candid about the format's boundaries, and it is worth taking at face value. TOML is explicitly intended as a configuration file format. Parsing it is easy, but it is not intended for serializing arbitrary data structures. Because every document must have a hash table at the top level, you cannot represent a bare top-level array or a bare top-level float. If your data does not naturally sit under named keys, TOML will force you to invent a wrapper key, and that wrapper will be visible to every consumer of the file.

The second boundary is streaming. The README states there is no standard identifying the start or end of a TOML file, which complicates sending it through a stream. Those details, it says, must be negotiated on the application layer. If you are building a protocol that sends documents over a socket and needs to know where one ends and the next begins, TOML gives you no help. You will end up inventing a length prefix or a delimiter, and at that point you should ask whether a format with built-in framing would serve you better.

There is a third case worth naming even though the README frames it as a comparison rather than a limitation. INI files are frequently compared to TOML because of their similar syntax and use as configuration files, but the README notes that there is no standardized format for INI and that INI does not gracefully handle more than one or two levels of nesting. If your configuration is genuinely flat and you already have an INI parser wired in, TOML's nesting support is a capability you would be paying for without using.

TOML vs YAML and TOML vs JSON: The Trade the README Describes

The README positions TOML against both formats without declaring a winner, and the framing is useful. TOML and JSON are described as both simple and using ubiquitous data types, which makes them easy to code for or parse with machines. TOML and YAML are described as both emphasizing human readability features, like comments that make it easier to understand the purpose of a given line. TOML's claim is that it combines these: it allows comments, unlike JSON, while preserving simplicity, unlike YAML.

That is the actual difference in approach, and it is a real one. If you have ever needed to annotate a JSON configuration file and found yourself writing a parallel document to explain it, the comment gap is the thing TOML closes. If you have ever debugged a YAML file where a value's type depended on how it was quoted, the simplicity claim is the thing TOML is reaching for. The README does not claim TOML is more expressive than YAML. It claims TOML is simpler, and it accepts the expressiveness cost.

The README links out to the YAML specification at yaml.org, the JSON specification at the IETF, and a Wikipedia article on INI files for readers who want to compare in depth. Note what is absent: there is no benchmark, no parsing-speed comparison, and no claim about which format is faster. Anyone telling you TOML is faster than YAML is not getting that from this repository.

Maintenance, Releases and the Upgrade Cost of a Specification

The repository is not archived, and its last push was on 2026-09-15. The release history is short and spaced out: 1.0.0-rc.3 on 2020-10-07, 1.0.0 on 2021-01-12, and 1.1.0 on 2025-12-24. That cadence tells you something practical. TOML is a settled format with occasional revisions, not a moving target. A parser written against 1.0.0 in 2021 was not chasing a spec that changed underneath it for roughly five years.

The upgrade cost of adopting TOML is therefore mostly borne by your parser, not by your configuration files. Because this repository holds the in-development version, the text in toml.md may describe behaviour ahead of the released specification at toml.io. That is a real trap for implementers: if you build against the in-development text and your users run a decoder built against 1.0.0, you can produce files that the released spec does not cover. The README's own pointer to toml.io for released versions is the mitigation, and it is worth following.

On licensing, the repository is MIT, which permits reuse and modification with the licence and copyright notice retained. That applies to the specification text and the ABNF grammar. It says nothing about the many implementations the wiki lists, each of which carries its own terms. Check those separately, and treat any statement about the combined licence position of a spec plus a parser as something to verify with your own counsel rather than infer from this repository.

Editorial conclusion

Adopt TOML when you are writing configuration that a human will edit and a machine will parse, and get your parser from the implementations list in the project wiki rather than from this repository, which contains no code. Do not adopt it if you need to serialize arbitrary data structures or stream documents without an application-layer framing convention, because the README states TOML does not permit top-level arrays or floats and has no standard start or end marker. Before committing, verify three things against the released specification at toml.io rather than the in-development files here: the exact version your parser claims to support, whether it handles the date and time types shown in the README example, and how it reports a duplicate key. The last push to this repository was on 2026-09-15.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. toml-lang/toml on GitHub