YAML Indentation Rules

Indentation is one of the most important parts of YAML syntax. Unlike JSON, which uses braces and brackets to explicitly define nested structures, YAML uses whitespace indentation to show relationships between mappings, sequences and their values. A small indentation mistake can therefore change the structure of a document or cause the YAML parser to reject it.

Understanding YAML indentation rules is essential when writing configuration files, deployment manifests, CI definitions and structured data. YAML does not require one universal indentation width, but indentation must be consistent within the structures being represented.

How YAML Uses Indentation

YAML uses indentation to represent hierarchy. A line that is indented farther than its parent belongs to the nested structure underneath that parent. A line returning to the parent's indentation level ends that nested structure.

server:
  host: example.com
  port: 443

In this example, host and port are nested inside server because both lines are indented farther than the server key. The indentation therefore represents the relationship between the parent mapping and its child properties.

Spaces Instead of Tabs

YAML indentation should use spaces rather than tab characters. Tabs can cause parsing errors or inconsistent behavior between YAML implementations and editors. Using spaces makes the indentation level explicit and portable.

How Many Spaces Should You Use?

YAML does not require every document to use exactly two or four spaces for indentation. Two spaces are extremely common, especially in configuration files, while four spaces are also valid. The important requirement is that indentation consistently represents the intended hierarchy.

Nested Mappings

Mappings can contain other mappings at deeper indentation levels. Each additional level moves the child properties farther to the right.

application:
  server:
    host: example.com
    port: 443
  logging:
    level: info
    enabled: true

Here, server and logging belong to application. The host and port properties belong to server, while level and enabled belong to logging. Each relationship is expressed entirely through indentation.

Indentation and Sequences

YAML sequences use a hyphen followed by a space. When a sequence appears inside a mapping, its indentation indicates which key owns the list.

servers:
  - web-1
  - web-2
  - web-3

The servers key contains a sequence because all three list items are indented beneath it. The hyphen marks each item in the sequence.

Nested Sequences

A sequence can contain mappings or other sequences. Correct indentation makes these nested relationships clear.

services:
  - name: api
    ports:
      - 8080
      - 8443
  - name: web
    ports:
      - 80
      - 443

Each service is a sequence item containing its own mapping. The ports key is nested inside the service mapping, and the individual port values are nested inside the ports sequence.

Indentation of Mapping Properties Inside Lists

One common source of confusion is the indentation of properties belonging to a sequence item. When a list item begins with a mapping key, subsequent properties belonging to that same item must align appropriately with the first property.

users:
  - name: Alice
    role: admin
    active: true
  - name: Bob
    role: editor
    active: true

The name, role and active properties belong to each individual user because they are aligned at the same mapping level inside each list item.

Changing Indentation Changes Structure

Indentation is not merely visual formatting in YAML. Moving a line to another indentation level can change which object or sequence contains that value.

server:
  host: example.com
  database:
    host: db.example.com

In this example, the database mapping belongs to server, and the database host belongs to database. If database were moved to the same indentation level as server, it would become a separate top-level mapping instead.

Consistent Indentation Levels

Sibling properties should normally use the same indentation level. If two keys belong to the same mapping, they should align horizontally in the YAML source.

database:
  host: localhost
  port: 5432
  name: application

The three database properties are siblings because they use the same indentation. This visual alignment also makes the structure easier for developers to inspect and maintain.

Incorrect Indentation

Accidental indentation can create parser errors or an unintended data structure. For example, a property that should belong to database may accidentally be moved outside it.

database:
  host: localhost
    port: 5432

The port property is indented farther than host without introducing another nested structure. This is invalid because the indentation does not correspond to a valid YAML relationship.

Mixed Indentation Widths

Different indentation widths can appear at different nesting levels as long as the resulting structure is unambiguous, but mixing styles unnecessarily makes YAML harder to read and maintain. A consistent indentation policy is therefore strongly recommended.

application:
  server:
    host: example.com
    port: 443
  logging:
    level: info

Using two spaces for each nesting level creates a predictable visual structure. Developers can quickly determine the depth of each property without having to parse the content manually.

Indentation in Block Scalars

Multiline strings use indentation to determine which lines belong to the scalar value. YAML supports literal blocks with the pipe character and folded blocks with the greater-than character.

description: |
  This is a multiline value.
  Each indented line belongs
  to the description.

The lines following the pipe are indented relative to the description key. Their indentation indicates that they belong to the multiline scalar rather than being separate YAML properties.

Indentation and Empty Lines

Empty lines do not normally carry the same structural meaning as non-empty lines, but whitespace inside empty lines can still create problems in some tooling or make a document harder to maintain. Keeping empty lines clean is a useful formatting practice.

Indentation Around Comments

Comments can appear at different indentation levels. When a comment is placed inside a nested structure, matching the surrounding indentation makes it clear which section the comment describes.

server:
  # Public server configuration
  host: example.com
  port: 443

The comment is aligned with the properties it describes. Although comments do not become data values, consistent indentation improves readability and reduces confusion when editing complex configuration files.

Indentation With Flow Syntax

YAML also supports flow-style mappings and sequences using braces and brackets. These structures reduce the amount of indentation required because delimiters explicitly describe the boundaries of the collection.

server: { host: example.com, port: 443 }
ports: [80, 443]

Flow syntax can be useful for short structures, but block-style YAML is often easier to read for larger configuration sections. Indentation remains especially important when using block collections.

Indentation and Document Markers

YAML documents can use document start and end markers such as three hyphens and three periods. These markers define document boundaries and are not indentation levels themselves.

---
server:
  host: example.com
  port: 443
...
---
server:
  host: backup.example.com
  port: 443

Each document begins its own top-level structure. Indentation inside one document does not continue as a hierarchy into another document.

Indentation and Anchors

Anchors and aliases do not remove the need for correct indentation. The anchored node must still be placed at the intended structural level, and aliases must appear where the referenced value is expected.

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

The values under defaults are indented because they belong to the anchored mapping. The production mapping then uses the alias at its own indentation level.

Indentation and YAML Parsers

A YAML parser interprets indentation as part of the document structure. If indentation is invalid, the parser may report an error instead of producing a data structure. Different parser implementations can also provide different error messages, so the reported location may not always be exactly where the original mistake occurred.

When debugging an indentation error, inspect the surrounding structure rather than changing only the line identified by the error message. An incorrect indentation level earlier in the document can cause a later line to appear invalid.

Common Indentation Mistakes

• Using tabs instead of spaces.
• Accidentally adding or removing spaces from a nested property.
• Aligning sibling properties at different indentation levels.
• Indenting a sequence item incorrectly.
• Forgetting that indentation defines hierarchy.
• Mixing indentation styles unnecessarily.
• Breaking multiline strings with incorrect indentation.
• Assuming indentation is only cosmetic.

How to Debug Indentation Errors

Start by identifying the parent structure and then inspect each nested level from top to bottom. Check whether sibling keys are aligned, whether sequence markers use the expected indentation and whether any tab characters are present.

• Check for tab characters.
• Identify the intended parent key.
• Compare indentation of sibling properties.
• Check sequence markers and nested list items.
• Inspect multiline scalar indentation.
• Validate the complete document after making corrections.

Editor Configuration

A properly configured editor can prevent many YAML indentation problems. Most modern editors can automatically insert spaces, preserve the chosen indentation width and provide YAML syntax highlighting or validation.

• Configure YAML files to use spaces.
• Choose a consistent indentation width.
• Enable automatic indentation when appropriate.
• Use syntax highlighting for YAML.
• Run a YAML validator before deployment.

Formatting YAML Automatically

A YAML formatter can normalize indentation and improve consistency across a document. Automatic formatting is particularly useful for large configuration files where manually checking every indentation level is difficult.

Formatting should not replace validation. A formatter may change the presentation of valid YAML, but a parser or validator is still needed to determine whether the document is syntactically valid and represents the intended structure.

Best Practices

• Use spaces instead of tabs.
• Choose a consistent indentation width.
• Use two spaces per level when following a common YAML style.
• Align sibling properties consistently.
• Keep nested structures visually clear.
• Pay special attention to indentation inside sequences.
• Preserve correct indentation in multiline strings.
• Use an editor configured specifically for YAML.
• Format YAML consistently across a project.
• Validate YAML before using it in production.

Frequently Asked Questions

Helpful YAML Tools

A YAML Validator checks YAML syntax and helps identify indentation errors, a YAML Formatter can normalize indentation and improve readability, a Whitespace Visualizer makes spaces and tabs easier to distinguish, a YAML Tree Viewer shows the resulting nested structure, and a Text Cleaner can help remove unwanted whitespace when preparing YAML or other text for further processing.

Conclusion

YAML indentation is a fundamental part of the language because whitespace defines the hierarchy of mappings and sequences. YAML generally uses spaces rather than tabs, and although the language does not require one universal indentation width, consistent formatting is essential for readable and maintainable configuration files. Correct indentation is especially important for nested mappings, sequences, multiline strings and complex configuration structures. Using a consistent editor configuration, formatter and validator can prevent many common mistakes. Once indentation is understood as part of YAML's syntax rather than simple visual formatting, writing and debugging YAML becomes significantly easier.