Mastering Proper Spacing in YAML Files: A Simple Guide

YAML (Yet Another Markup Language) is everywhere—from configuring CI/CD pipelines to defining Kubernetes manifests. Despite its simplicity, YAML can be tricky because proper spacing and indentation are critical. A small mistake can break your configs and cause frustrating errors.

In this post, I’ll explain the basics of YAML spacing and share tips on how to avoid common pitfalls.

---

Why Spacing Matters in YAML

YAML uses indentation (spaces, not tabs!) to represent hierarchy. Unlike JSON or XML, YAML doesn’t use brackets or tags. Instead, it relies purely on indentation to show nested structures.

Because of this, even one extra or missing space can change the meaning or make your YAML invalid.

---

Basic Rules for YAML Spacing

1. Use spaces only, never tabs

Tabs are not allowed in YAML and will cause parsing errors. Always configure your editor to insert spaces when you press Tab (usually 2 or 4 spaces per indentation level).

2. Consistent indentation level

Pick a number of spaces per level (2 or 4 is common) and stick to it throughout your file. Mixing indentation sizes causes errors.

Example (2 spaces per level):

yamlCopyEditjob:
  name: build
  steps:
    - uses: actions/checkout@v3
    - name: Run tests
      run: npm test

---

Common Mistakes and How to Fix Them

Mistake 1: Mixing tabs and spaces

Error: Parser complains about unexpected character.
Fix: Replace all tabs with spaces. Most editors have a “Convert Tabs to Spaces” option.

Mistake 2: Incorrect indentation level

Example:

yamlCopyEditjobs:
 build:
  runs-on: ubuntu-latest

Here, build should be indented under jobs, but the indentation is inconsistent.

Corrected:

yamlCopyEditjobs:
  build:
    runs-on: ubuntu-latest

Mistake 3: Missing indentation for sequences (-)

Example:

yamlCopyEditsteps:
- name: Checkout
  uses: actions/checkout@v3

This is valid, but mixing indentation before the dash causes problems:

yamlCopyEditsteps:
 - name: Checkout
   uses: actions/checkout@v3

Make sure the dash aligns correctly with the key:

yamlCopyEditsteps:
  - name: Checkout
    uses: actions/checkout@v3

---

Tools to Help You Avoid YAML Spacing Issues

• VS Code with YAML extensions (like Red Hat’s YAML plugin) highlights errors instantly.

• Online YAML validators (e.g., https://yamlvalidator.com/)

• Prettier or yamllint to auto-format and lint your YAML files.

---

Final Tips

• Always use spaces, not tabs.

• Be consistent with indentation level (2 or 4 spaces).

• Keep your YAML clean and readable—it helps with debugging and teamwork.

• When in doubt, validate your YAML before using it in production.

---

YAML spacing might seem tricky at first, but once you get the hang of it, it becomes second nature. Proper indentation is the foundation for error-free configs and smooth DevOps workflows!