Skip to content
BENIBIX Learn

Config Files, YAML and TOML

Level 3 · Config and docs files

What a config file is for, and the two formats most of them use. How YAML uses indents, how TOML uses headings, and the traps in each.

Course contentsLesson 5 of 11

After this lesson you can

  • Say what a config file does
  • Read a YAML file and a TOML file
  • Avoid the tab and NO traps

13 mincovers 3 glossary entries

Worth reading first: Serialization and Protobuf

How YAML and TOML hold a program's settings

A config file holds the settings a program reads when it starts, so you can change how it acts without changing its code. Most are written in YAML or TOML. YAML groups settings with indents and spaces. TOML groups them under headings in square brackets. TOML reached version 1.0 in January 2021.

A project often has several config files, one for each tool. The linter has one, the test tool has one, and so does the app itself. Each file is plain text, so it goes into Git and changes with the code.

YAML was built to be easy to read. A name, a colon and a value make one setting. Lines indented under a name belong to it, and a dash starts each item in a list. It allows comments after a # sign, which JSON does not.

The spaces in YAML carry meaning, and that is its main trap. A line indented one space too far joins the wrong group. Tabs are not allowed at all, and a single tab makes the file fail to load. Set your editor to put in spaces.

YAML also guesses types, and the guesses can be wrong. Older YAML readers, built on version 1.1, read a bare NO as false. So a country code for Norway turns into false. They also read 1.10 as the number 1.1. Put quotes around any value that must stay text.

TOML is stricter, so it has fewer surprises. Each line sets one value, like name = "shop". Text must be in quotes, so it is never guessed. Settings sit under a heading in square brackets. Rust projects use it in Cargo.toml, and Python projects in pyproject.toml.

The common mistake in TOML is leaving the quotes off text. The line name = shop is an error, not a setting. The fix is always the same: name = "shop". Many editors check both formats as you type.

yaml
server:
  name: shop
  country: NO
  version: 1.10
Indents put three settings under server. An older reader turns NO into false and 1.10 into 1.1.
toml
[server]
name = "shop"
country = "NO"
version = "1.10"
The same settings in TOML. Text is always quoted, so nothing is guessed.
The same three settings in YAML and TOML. An older YAML reader changes two of them.

Worked example

Lucy's country list loses Norway

Lucy's shop reads its list of 12 shipping countries from a YAML file. Orders to Norway keep failing, while the other 11 work.

She finds the reader turned NO into false. She puts quotes around "NO", and Norway orders go through.

The words for this lesson3

Check yourself

Why does my YAML file fail to load after I indent a line?

Finished this lesson?

Marking it complete also marks its 3 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.