YAML indentation: spaces, tabs, and common errors

Short answer

YAML uses spaces to define the structure of block mappings and sequences. Align sibling keys and list markers, and indent nested mappings farther than their parent. Tabs cannot provide that indentation. A sequence used as a mapping value may also align its dashes with the parent key; that valid style is shown below.

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. This exact document is invalid; the converter reports the problem at line 4, column 4. Add one space before that dash so both markers start in column 5:

service:
  ports:
    - 8080
    - 8443

The resulting service.ports array must contain the two numbers 8080 and 8443, not a string or a second property.

Valid YAML can still have the wrong parent

This document parses, but timeout belongs to health, not service:

service:
  health:
    path: /health
    timeout: 30

If the application expects service.timeout, move timeout two spaces left, aligning it with health. The corrected JSON is:

{
  "service": {
    "health": { "path": "/health" },
    "timeout": 30
  }
}

A valid list without extra indentation

YAML permits a sequence used as a mapping value to align with its key:

ports:
- 8080
- 8443

This still means {"ports":[8080,8443]}. Indenting both dashes two spaces is also valid. Choose one style for readability; do not mark the aligned version as a syntax error just because it looks different.

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.