Indentation — Spaces Only, Always

The single most important YAML rule

YAML uses indentation to denote nesting. Indentation must be spaces only — tabs are forbidden. Most parsers reject any tab character used for indentation outright with a clear error; a few tolerate it and silently break alignment.

How much indentation

The spec is permissive: any consistent number of spaces works, as long as you use the same count throughout a block. Convention is 2 spaces. Some tools (older Ansible roles, certain Kubernetes manifest examples) use 4. Pick one per file and stick with it.

Indent past the parent's name

Children must be indented further than the parent's name, not just its colon. foo:\n bar: 1 works because bar sits past the start of foo. Misalign by even one space and the parser either rejects or reads the data shape differently.

The 'tab vs space' trap: editors often auto-convert tabs depending on filetype detection. If your YAML file detects as 'plain text', the editor inserts tabs, the YAML parser dies, and the error usually says 'expected mapping value, got X' — pointing at the indented line, not the offending tab. Configure your editor: YAML files always insert spaces.

Code

Standard 2-space indentation·yaml

server:
  host: localhost
  port: 8000
  database:
    name: pippa
    pool_size: 5
logging:
  level: info
  format: json

Same data, 4-space indentation (also valid)·yaml

server:
    host: localhost
    port: 8000
    database:
        name: pippa
        pool_size: 5

Broken — mixed tabs and spaces·text

server:
  host: localhost     ← spaces
	port: 8000          ← TAB → parser dies
  database:           ← spaces
      name: pippa     ← inconsistent indent depth

Configure your editor (VS Code)·json

// .vscode/settings.json
{
  "[yaml]": {
    "editor.tabSize": 2,
    "editor.insertSpaces": true,
    "editor.detectIndentation": false
  }
}

Exercise

Take a real YAML file (a docker-compose.yaml, a workflow file, anything). Run cat -A file.yaml (Linux) or cat -te file.yaml (macOS) — ^I markers in the output reveal any tab characters. Configure your editor to expand tabs to spaces in YAML files. Edit the file and re-check. Save the editor config to your dotfiles.

Indentation — Spaces Only, Always

The single most important YAML rule

How much indentation

Indent past the parent's name

Code

External links

Exercise

Progress

Comments 0