Skip to content

ryl Rules Reference

A comprehensive reference of all YAML linting rules

Introduction

ryl implements 30 rules for checking YAML files. This page is a categorised index of every rule with a brief description and a link to its detailed documentation. Each rule page covers what the rule does, why it matters, configuration options, and (where applicable) automatic fix behaviour.

For configuration discovery, presets, and file selection, see Configuration presets.

Rule categories

Rules that auto-fix are marked with 🔧 in the Fix column, and rules with an unsafe fix with ⚠. Most layout rules are also enforced by ryl format; the Formatter page lists which, and the options that conflict with it.

Layout and spacing

Rule Description Fix
block-scalar-chomping Explicit chomping indicator (-/+) on block scalars.
braces Spaces inside flow mapping braces ({...}). 🔧
brackets Spaces inside flow sequence brackets ([...]). 🔧
colons Spaces around mapping colons. 🔧
commas Spaces around flow collection commas. 🔧
empty-lines Number of consecutive empty lines. 🔧
hyphens Spaces after sequence hyphens. 🔧
indentation Block indentation, sequence indentation, multi-line strings.
line-length Maximum line length.
new-line-at-end-of-file A trailing newline at end of file. 🔧
new-lines Consistent line endings (LF vs CRLF). 🔧
trailing-spaces Trailing whitespace at end of lines. 🔧
unicode-line-breaks Raw NEL / LS / PS characters (not YAML 1.2 line breaks).

Document structure

Rule Description Fix
anchors Anchor and alias declarations and usage.
document-end Document end marker .... 🔧
document-start Document start marker ---. 🔧
empty-values Empty values in mappings and sequences.
key-duplicates Duplicate keys in mappings.
key-ordering Alphabetical or configured ordering of mapping keys. 🔧
merge-keys The << merge key (a YAML 1.1 feature removed in 1.2).
tags Unsafe and non-portable YAML tags.
schema Validate against user-supplied local JSON Schemas.
yaml-directive A %YAML version directive on every document. 🔧

Comments

Rule Description Fix
comments Spaces after # and before inline comments. 🔧
comments-indentation Comment alignment with surrounding content. 🔧

Values

Rule Description Fix
float-values Float value formats.
octal-values Octal value formats. âš 
quoted-strings Quoted string styles and when to require quotes. 🔧
schema-dependent-values Plain values YAML 1.1 and 1.2 read differently (2026-10-10, 22:22, 1_000). âš 
truthy Truthy values like yes, no, on, off. 🔧 ⚠

Severity levels

Warnings return exit code 0 unless strict mode is enabled with --strict or TOML [lint] strict = true. Use --no-strict to override a configured strict mode for one run.

Every rule can be configured to report at either error (the default for most rules) or warning. Errors cause ryl to exit non-zero; warnings are printed and fail the run only under strict mode.

Configure the severity inline with the rule:

[lint.rules.line-length]
level = "warning"
max = 120

Enabling and disabling rules

Toggle a rule on or off with a top-level string in the [lint.rules] table:

[lint.rules]
truthy = "disable"
key-ordering = "enable"

Enabling a rule without options applies its defaults. To enable every rule, including the ryl-only ones, use ALL:

[lint.rules]
ALL = "enable"
truthy = "disable"

[lint.rules.line-length]
max = 120

Each rule then runs with its own defaults at level error. An explicit entry for a rule wins over ALL wherever it appears in the table. ALL is TOML-only; yamllint-compatible YAML config rejects it.

ALL can grow when you upgrade ryl

ALL, in config or as --enable ALL, turns on every rule the installed ryl has, including any added after you wrote the config. An upgrade that adds a rule can then fail a check that passed before. Pin the ryl version, or list the rules you want.

ryl check --enable <RULES> picks the rules from the command line instead: comma-separated rule IDs or ALL, and the flag can be repeated. It replaces the config's selection, so only the listed rules run. A listed rule keeps the options and level the config gives it, and runs at its defaults if the config disables it or does not mention it. --disable <RULES> then subtracts comma-separated rule IDs or ALL from the selection; pass --disable once per command. ignore, per-file-ignores and inline directives still apply. The flag works without any config file:

ryl check --enable ALL .
ryl check --enable truthy,line-length .

The built-in default and relaxed presets cover the common starting points (the empty preset is YAML-extends: only, with no usable TOML form); see Configuration presets.

To switch rules off for part of a file with # ryl disable / # yamllint disable comments, see Inline directives.

Automatic fixing

The --fix flag applies safe fixes for rules marked with 🔧 above:

ryl check --fix .

Control which rules apply fixes with fixable/unfixable in the [lint] table:

[lint]
fixable = ["ALL"]
unfixable = ["comments"]

Unsafe fixes

A safe fix never changes what a value means. An unsafe fix may: it picks one meaning where readers disagree, so it applies only when you opt in, as with ruff. truthy, octal-values and schema-dependent-values offer one for a plain scalar that YAML 1.1 and 1.2 readers load differently (see YAML version compatibility).

Check the source version first

Unsafe fixes default to YAML 1.2 meanings for undeclared files. For files written for PyYAML, Ansible or another YAML 1.1 reader, set source-version = "1.1" before applying them. Follow the migration recipe.

ryl check counts the fixes it left out:

$ cat config.yaml
enabled: yes
$ ryl check config.yaml
config.yaml
  1:10      error    truthy value should be one of [false, true]  (truthy)

1 unsafe fix available with `--fix --unsafe-fixes`.
Control Effect
--unsafe-fixes or top-level unsafe-fixes = true Permit unsafe fixes with --fix; preview with --diff --unsafe-fixes
[lint] extend-safe-fixes = ["octal-values"] Let plain --fix apply that rule's unsafe fixes; use sparingly
--no-unsafe-fixes Override the configured unsafe-fix setting
Top-level unsafe-fixes = false Disable unsafe fixes and silence the count
[lint] unfixable = ["truthy"] Block the rule's safe and unsafe fixes

Once enabled, an unsafe fix's message names the old and new spelling (; unsafe fix: yes -> "yes"). ryl format never applies unsafe fixes. In an editor, ryl server offers each rule's unsafe fixes as a quick fix, kept out of "Fix all" until the config applies them.