YAML indentation: spaces, tabs, and common errors

Short answer

YAML uses indentation spaces to show which values belong to each mapping or sequence. Sibling items must start in the same column, while a child must be indented farther than its parent. A tab character cannot replace the spaces that establish this structure.

A correctly indented example

This document uses two spaces per level:

service:
  name: api
  ports:
    - 8080
    - 8443
  health:
    path: /health

name, ports, and health are sibling properties. The two numbers belong to one sequence, while path belongs to the health mapping. YAML does not require exactly two spaces, but it does require a coherent hierarchy.

Use the YAML to JSON converter to inspect the resolved structure. If a block appears under the wrong property, compare the starting columns in the original text before converting it again.

One space can change the tree

This fragment does not align the two list markers:

service:
  ports:
    - 8080
   - 8443

The second dash starts one column earlier. Depending on its context, a parser will report an error or produce a structure different from the intended one. The problem is not cosmetic: the column is part of the syntax.

Why tabs cannot provide indentation

The YAML 1.2.2 indentation section excludes tabs from indentation characters because editors can display them at different widths. Configure the editor to insert spaces when Tab is pressed, and enable visible whitespace while diagnosing a file.

A tab can still be data inside a quoted string or certain block-scalar content after the required indentation. The important rule is that it must not decide the structural level.

A diagnostic checklist

1. Make spaces and tabs visible in the editor.
2. Inspect the reported line and the line immediately before it.
3. Compare the starting column of every sibling item.
4. Confirm that each - in one sequence is aligned.
5. Replace indentation tabs, not tabs that belong to string data.
6. Convert again and inspect the JSON hierarchy, not merely the lack of an error.

Common errors

• Aligning text by appearance without checking its actual columns.
• Mixing two- and four-space levels within one sibling set.
• Accidentally putting a property under the last item in a sequence.
• Editing only the reported line when its parent block is misaligned.
• Reindenting a document automatically without reviewing multiline strings.

A file that parses is not necessarily arranged as intended. Compare the resulting keys, mappings, and arrays with the expected data model.