YAML Indentation

Indentation gives a YAML file its shape. Other formats use braces or tags to group data. YAML uses the number of spaces at the start of a line. A line that moves right by two spaces becomes a child of the line above it. Mastering this single idea removes most beginner frustration.

The Core Rules

• Use spaces only. Tab characters cause errors.
• Keep items at the same level aligned in the same column.
• Move children to the right of their parent by at least one space.
• Stay consistent across the whole file. Two spaces per level is the most popular choice.

The parser does not care whether you pick two, three, or four spaces. It cares that siblings line up exactly and children sit deeper than parents.

Seeing Indentation as a Family Tree

Think of a family photo where parents stand in the front row and children stand behind them. Indentation works the same way. The deeper a line sits, the further back in the photo it stands.

server:                 column 0  (parent)
  host: localhost       column 2  (child of server)
  port: 8080            column 2  (sibling of host)
  database:             column 2  (child of server)
    name: shop          column 4  (child of database)
    user: admin         column 4  (sibling of name)

Reading from top to bottom, the file describes one server with a host, a port, and a database. The database holds a name and a user.

Siblings Must Align

Sibling lines share one starting column. A single extra space changes the meaning or breaks the file.

Correct

person:
  name: Asha
  city: Pune

Incorrect

person:
  name: Asha
   city: Pune

The second example pushes city one space too far. The parser reports an error because it cannot decide whether city belongs to name.

Indentation in Lists

List items start with a dash and a space. The dash counts as part of the indentation. Two layouts are valid:

fruits:
- apple
- banana

fruits:
  - apple
  - banana

Both layouts load the same data. The second layout reads more clearly because the dashes sit under the key. Most style guides recommend it.

Lists of Mappings

A list can hold small groups of keys. The first key shares a line with the dash, and the remaining keys align with it:

students:
  - name: Ravi
    marks: 82
  - name: Meena
    marks: 91

The letters name and marks start in the same column, which tells the parser they belong to the same student.

Choosing the Number of Spaces

Spaces per level	Common use
2	Docker Compose, Kubernetes, GitHub Actions
4	Some Python and Ansible projects

Pick one number and apply it everywhere in a file. Mixing two and four spaces in different sections confuses readers even when the parser accepts it.

Measuring Indentation with a Ruler

0123456789
app:
  name: demo
  tags:
    - web
    - api

The numbers on the first line act as a ruler. The key name starts at column 2. The dash before web starts at column 4. Counting columns helps you debug stubborn errors.

Blank Lines and Trailing Spaces

Blank lines carry no meaning, so add them freely to separate groups. Spaces at the end of a line are invisible and usually harmless, yet linting tools flag them. Turn on the whitespace display in the editor to spot them.

Quick Debugging Checklist

• Search the file for tab characters.
• Confirm that siblings start in the same column.
• Verify that every child sits deeper than its parent.
• Check that each colon has a space after it.

Run through these four checks whenever the parser complains about structure. The error line number points to the area, and the checklist finds the cause.