Skip to content

indentation

What this rule does

Enforces consistent indentation throughout the document. Specifically:

  • The indent width used by block mappings and block sequences.
  • Whether block sequence items are indented under their parent key or start at the same column.
  • Optionally, the indentation of content inside multi-line block scalars.

Why this matters

  • Mixed indents cause parse surprises. YAML's whitespace sensitivity means inconsistent indents can change which key a value belongs to.
  • Cross-tool diffing. Editors with different default tab widths can silently introduce mixed indentation; the rule catches drift early.
  • Convention. Most projects settle on either 2- or 4-space indents; pinning the width prevents new files from drifting.

Configuration

[lint.rules.indentation]
level = "error"
spaces = "consistent"
indent-sequences = true
check-multi-line-strings = false
Option Default Description
spaces top-level indent-width if set, else "consistent" An integer such as 2 for a fixed indent width, or "consistent" to lock the rest of the file to the first indent seen.
indent-sequences true true, false, "whatever", or "consistent". Whether block sequence items are indented under the parent key.
check-multi-line-strings false When true, apply indent checks inside block scalars and multi-line flow strings.

Examples

✅ Allowed (with spaces: 2, indent-sequences: true)

parent:
  list:
    - item one
    - item two

❌ Reported (with spaces: 2, indent-sequences: true)

parent:
  list:
  - item one
  - item two

✅ Allowed (with indent-sequences: false)

parent:
  list:
  - item one
  - item two

❌ Reported (with spaces: 2)

parent:
   over-indented: value

Automatic fixing

ryl check --fix does not fix this rule; indentation changes can shift values into different parents.

ryl format re-indents each block level to the top-level indent-width, or without it to width 2 (see Configuration), with block sequences indented past their key unless [format] indent-sequences = false. Block scalar bodies, continuation lines and comments move with the line they belong to, and lines inside a flow collection go where this rule expects them. A document is left as it is, and reported, when a tab indents it or when re-indenting it would change what it parses to; an inline disable for this rule leaves it unreported.

  • hyphens — spacing between - and the sequence item value.
  • comments-indentation — standalone comments must follow the same indent as the next line.