YAML Explained — and How It Compares to JSON

If you've edited a config file for a modern tool — Docker Compose, GitHub Actions, Kubernetes — you've written YAML. It's designed to be the most human-readable data format, but that readability comes with a few sharp edges. This guide explains how YAML works, the traps to watch for, and how it compares to JSON.

What YAML is

YAML (“YAML Ain't Markup Language”) is a data format for representing the same things JSON does — key/value pairs, lists, and nested structures — but with a syntax tuned for people to read and write by hand. It's the go-to for configuration files precisely because it's easy to scan.

name: RunWebTools
active: true
tags:
  - json
  - free
address:
  city: London
  postcode: null

How the syntax works

Three ideas cover most of YAML:

• Indentation shows structure. Nesting is expressed with spaces, not braces. Items at the same indent level are siblings.
• Key/value pairs use key: value (the space after the colon is required).
• Lists use a leading - for each item.

The gotchas

Spaces, never tabs

YAML forbids tab characters for indentation — they cause a parse error. Configure your editor to insert spaces, because the two look identical on screen but only one is valid.

The “Norway problem”

YAML tries to guess types, which occasionally backfires. Unquoted no, yes, on, and off become booleans — famously, the country code NO for Norway can turn into false. When you mean a literal string, quote it: "NO".

Indentation mistakes are silent

Because whitespace carries meaning, a single misaligned line can change the structure without any error — the file just parses into something you didn't intend. Running it through a YAML validator that re-emits the parsed result is the fastest way to see what YAML actually understood.

YAML vs. JSON

They can represent the same data — in fact, all valid JSON is also valid YAML. The trade-offs:

• Readability: YAML wins for humans — no braces or quotes, and it supports comments (#), which JSON does not.
• Strictness: JSON wins for machines — its rigid syntax leaves little room for the type-guessing and indentation surprises YAML allows.
• Use case: reach for YAML for files people edit (config), and JSON for data programs exchange (APIs).

Need to move between them? Format and check either with the YAML formatter and JSON formatter. If YAML feels finicky, our guide to JSON and its common errors is a good companion read.