How YAML Indentation Works (and Why It Matters)

Indentation is significant in YAML

This is the one thing that makes YAML different from almost every other data format. In JSON, you can put the whole document on one line; in XML, the whitespace between tags is ignored. In YAML, the number of leading spaces on a line determines what that line belongs to. Indentation is how YAML expresses nesting — there are no braces or tags to fall back on.

Consider two documents that differ only in the indentation of one line:

server:
  host: localhost
  port: 8080
debug: true

server:
  host: localhost
  port: 8080
  debug: true

On the left, debug is a top-level key. On the right — indented two spaces — it's a key inside server. Same characters except for two spaces, completely different data. No other common format behaves this way.

The rules that actually matter

• Spaces only — never tabs. The YAML spec forbids tab characters for indentation. A tab where a space is expected is an immediate error. This is the number-one cause of "my YAML won't parse," and it's invisible in most editors.
• Be consistent within a block. YAML doesn't mandate a specific indent size, but every sibling in the same block must line up at the same column. Mixing 2 and 4 spaces within one mapping breaks it.
• Deeper means nested. More indentation than the line above means "child of." Less means "back out to" an enclosing level — and it must line up exactly with an existing level, or the parser errors.
• The colon plus space matters. A mapping is key: value with a space after the colon. key:value is parsed as a single scalar string.

Two spaces per level is the near-universal convention and the default in virtually every tool, but the spec only requires consistency, not a specific number.

Lists, maps, and the indentation that confuses people

Block sequences (lists) use a leading - . A common point of confusion is whether the dash counts toward indentation. Both of these are valid and equivalent:

roles:
  - admin
  - editor

roles:
- admin
- editor

Both attach the list to roles. Where it gets subtle is a list of maps — each item's keys must align under the first key after the dash:

users:
  - name: Alice
    role: admin
  - name: Bob
    role: editor

Here role lines up under name, not under the dash. Misaligning that single key is one of the most frequent real-world YAML mistakes.

Block scalars: where indentation is stripped

Multi-line strings use | (literal, keeps newlines) or > (folded, joins lines with spaces). The indentation of the block establishes a baseline that YAML strips off — so the leading spaces you add for readability are not part of the string value, but any indentation beyond the baseline is preserved.

script: |
  echo "line one"
  echo "line two"

The value of script is the two echo lines with their newline — the two-space block indent is removed. This is how YAML lets you embed shell scripts and config blobs without escaping.

How a YAML formatter re-indents

A formatter parses the document into its underlying data — maps, sequences, and scalars — then re-emits it with consistent indentation. Because indentation is structural, the formatter isn't "adding whitespace" the way a JSON formatter does; it's normalizing the existing structure to a uniform indent size and converting any stray tabs to spaces. The parsed data is unchanged; only the layout is regularized.

Fix your YAML indentation instantly

Paste your YAML and re-indent it to a consistent 2 or 4 spaces — tabs converted automatically, errors flagged as you type. Runs in your browser.

Frequently Asked Questions