# Config Files, YAML and TOML

> 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:** [JSON, YAML and File Formats](https://learn.benibix.com/learn/development-formats)  
**Time:** 13 min

**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

## 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.

![Two panels show the same settings. On the left, config.yaml has server, and under it, indented, name shop, country NO and version 1.10. A note says indents make the groups. On the right, config.toml has the heading server in square brackets, then name, country and version, each value in quotes. Below, a lit box says an older YAML reader gets country false and version 1.1. A second box says a TOML reader gets country NO and version 1.10, as text.](https://learn.benibix.com/diagrams/dev-config-formats.svg)

### 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.

**Words in this lesson:** [Configuration File](https://learn.benibix.com/term/development/config-file), [YAML Ain't Markup Language (YAML)](https://learn.benibix.com/term/development/yaml), [Tom's Obvious Minimal Language (TOML)](https://learn.benibix.com/term/development/toml)

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

**Answer:** The line was indented with a tab, and YAML only allows spaces. YAML does not allow tabs for indents. Set your editor to put in spaces, and the file loads again.

---

Source: https://learn.benibix.com/learn/development-formats/config-files-yaml-and-toml
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
