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¶
- Layout and spacing — whitespace, indentation, line endings, line length
- Document structure — document markers, empty values, anchors, tags, keys
- Comments — comment placement and spacing
- Values — numeric, string, and boolean value formats
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:
Enabling and disabling rules¶
Toggle a rule on or off with a top-level string in the [lint.rules] table:
Enabling a rule without options applies its defaults. To enable every rule,
including the ryl-only ones, use ALL:
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:
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:
Control which rules apply fixes with fixable/unfixable in the [lint] table:
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.