Skip to content

YAML version compatibility

How ryl handles YAML versions

A reader is the program or library loading your YAML. Two top-level TOML settings distinguish who must read the output from what the input originally meant:

Setting Question it answers Default What it changes
target-version Which readers must the output suit? "1.1" What the rules flag and what ryl format and --fix write
source-version Which version did the author of an undeclared document mean? "1.2" Only the direction of an unsafe fix

ryl parses YAML with its own fork of granit-parser. A document with no %YAML directive uses the YAML 1.2 core schema: the standard rules deciding whether an unquoted value is a string, number, boolean or null. The default target keeps output compatible with 1.1 readers too. See what differs in 1.2.

Migrate undeclared YAML 1.1 files safely

For files written for PyYAML or another 1.1 reader:

  1. Commit or back up the originals. Keep target-version = "1.1", set source-version = "1.1", and enable the migration rules:

    target-version = "1.1"
    source-version = "1.1"
    
    [lint.rules]
    truthy = "enable"
    octal-values = "enable"
    schema-dependent-values = "enable"
    
  2. Preview with ryl check --diff --unsafe-fixes .; review the chosen meanings, then apply with ryl check --fix --unsafe-fixes ..

  3. Resolve every remaining report manually, for example by quoting zone: "08" if the intended value is text. Some 1.1 readers disagree; check your own reader.
  4. Load the original and edited files with your application's reader and compare values and types. Test the application with the intended 1.2 reader too.
  5. Only once every consumer supports the intended 1.2 meanings, set target-version = "1.2" and remove source-version. The compatibility rules then go quiet; unresolved values such as 08 can change meaning without warning.

Do not apply the 1.1 source setting to GitHub Actions workflows: Actions treats on: as text. Use a separate nearest config or the workflow exemption. Files declaring %YAML 1.1 use the directive migration instead.

A %YAML directive states a document's version outright, so no unsafe fix applies to that document and source-version plays no part in it.

target-version is a top-level TOML setting ([tool.ryl] in pyproject.toml); YAML configs cannot set it. It names the oldest YAML version whose readers must load ryl's output to the same values, as ruff's target-version names the oldest Python the code must run on. Under "1.2":

  • quoted-strings and ryl format drop quotes only a 1.1 reader needs ('no' becomes no, '1_000' becomes 1_000).
  • truthy flags only the 1.2 booleans (True, FALSE), not yes or on.
  • schema-dependent-values goes quiet.
  • yaml-directive offers its %YAML 1.2 fix, and reports a %YAML 1.1 document, whose fix migrates it to 1.2.

Some readers called YAML 1.2 still resolve 1.1 types: ruamel.yaml's default loader and go-yaml v3 read 1_000, 0b1010 and 2026-10-10 as non-strings. Keep the default if such a reader loads your files; see which YAML version each reader follows.

Respecting the %YAML version directive

The %YAML directive is part of the YAML specification (1.2.2 §6.8.1), so ryl honours it per document, and it overrides target-version:

Directive ryl behaviour
none Resolved as YAML 1.2; output also kept safe for 1.1 readers unless target-version = "1.2".
%YAML 1.2 Resolved as YAML 1.2, for 1.2 readers only.
%YAML 1.1 (or 1.0) Resolve scalar values as YAML 1.1; parse structure with the YAML 1.2 grammar.
%YAML 1.3+ (higher minor) Processed as YAML 1.2 with a warning, as the spec directs.
%YAML 2.0+ (higher major) Rejected as an error; the spec requires rejecting a higher major version.
two %YAML directives in one document Rejected as an error, even when both name the same version.

YAML 1.2 does not treat Unicode Next Line (NEL), Line Separator (LS), or Paragraph Separator (PS) as line breaks. Using those characters as breaks is a syntax error, even under %YAML 1.1; see unicode-line-breaks.

Under an explicit %YAML 1.1 the value-resolving rules follow 1.1: quoted-strings keeps quotes that are load-bearing under 1.1 and truthy flags the 1.1 boolean words. --fix only makes edits that preserve the value under the document's declared version. The truthy fix only re-cases True/FALSE and the like, which are the same boolean under both versions.

Migrating a %YAML 1.1 document to 1.2

Under target-version = "1.2", yaml-directive reports each document that declares %YAML 1.1 (or 1.0), and --fix migrates it in one edit: every plain scalar whose 1.1 value 1.2 reads differently gets a 1.2 spelling of the same value, keys included, and the directive becomes %YAML 1.2. With the rule's present = false, the fix removes the directive instead, under either target; under "1.1" it skips a document needing 0o777, which PyYAML reads as a string.

%YAML 1.1 %YAML 1.2
yes, No, on, OFF true, false
0777, -0777 0o777, -511
22:22, 1:30.5 1342, 90.5
1_000, 0b1010, -0x1F 1000, 10, -31
!!bool yes !!bool true

The scalars and the directive change together because neither half is safe alone: 0o777 is a string to PyYAML and ruamel.yaml's 1.1 mode, so respelling it before the directive changes would move its value.

The fix leaves the whole document unchanged when the versions or readers cannot agree on a replacement. Resolve the blocking input manually, then rerun:

Input Why migration stops Action
Timestamp such as 2026-10-10 No 1.2 core timestamp type Choose text or an application-specific representation
08, 1e5, -.5, y, 0o777 1.1 readers disagree on the type Quote intended strings or write an unambiguous number/boolean
! 0777 The bare ! tag requests a string in the spec, but some readers ignore it Replace with an explicit string or number
Raw NEL, LS or PS Line breaks in 1.1, content in 1.2 Resolve the line breaks manually

Other values keep PyYAML and ruamel.yaml's 1.1 meanings. go-yaml (used by Kubernetes and Helm) reads 22:22 as text and rejects %YAML 1.2 anyway. Merge keys << stay unchanged.

Unless a document declares %YAML 1.2 or target-version = "1.2" is set, quoted-strings and ryl format keep the quotes on any scalar YAML 1.1 reads as a non-string ('no', 'on', 'yes', '1_000'), so the output means the same to a 1.1 consumer such as PyYAML. The set is PyYAML's 1.1 resolver plus 0o octal, y, Y, n and N, which go-yaml v2 (used by Kubernetes) loads as booleans, and go-yaml's float spellings ('08', '1e5', '-.5', '0_8'), which PyYAML reads as strings.

Unsafe fixes and source-version

Choose the input's meaning before applying unsafe fixes

The default source-version = "1.2" assumes undeclared files were written for 1.2: yes means text and 0777 means decimal 777. For files written for PyYAML, Ansible or another 1.1 reader, set source-version = "1.1" first. Otherwise an unsafe fix can change the values your application loads.

For go-yaml consumers (Kubernetes, Helm, Docker Compose), neither setting matches every value. With "1.2", fix leading-zero octals such as 0777 by hand to decimal 511, and rewrite 1_000 and 0b1010 as decimal integers rather than strings. With "1.1", quote sexagesimal strings such as 22:22 by hand; do not convert them to 1342. go-yaml versions and typed fields also differ on booleans and timestamps: check the reader table and your application's loaded values before fixing. Use lint.unfixable to exclude truthy, octal-values or schema-dependent-values from bulk fixes.

A document with no directive under the default target-version = "1.1" must mean the same to both versions, but a scalar such as yes already does not: a string to 1.2, a boolean to PyYAML. Rewriting it picks one reading, so truthy, octal-values and schema-dependent-values offer an unsafe fix that applies only under --unsafe-fixes, unsafe-fixes = true or lint.extend-safe-fixes. The top-level source-version says which reading the author meant, and the fix writes a spelling both versions read that way:

Scalar source-version = "1.2" (default) source-version = "1.1"
yes, off "yes", "off" true, false
0777, 0o17 777, 15 511, left alone
1_000, 0b1010 "1_000", "0b1010" 1000, 10
22:22, 1:30.5 "22:22", "1:30.5" 1342, 90.5
08 8 left alone
2026-10-10, y "2026-10-10", "y" left alone

Under "1.1" the fix leaves a scalar alone where the migration above declines: YAML 1.1 readers disagree on it (08, 0o17, y), or YAML 1.2 has no type for it (a timestamp). Either way it leaves alone an integer past 64 bits, which go-yaml reads as a float. Quotes follow quoted-strings' quote-type = "single" when that rule is on, and a boolean takes the first spelling truthy's allowed-values permits.

source-version steers only the fix: every rule, the formatter and the value checks still read an undeclared document as YAML 1.2. Like any setting, the nearest config wins, so a PyYAML-era subtree can carry its own source-version = "1.1".

For a plain yes with truthy enabled, target 1.1 plus source 1.2 offers "yes"; target 1.1 plus source 1.1 offers true. Target 1.2 reports neither: yes is already text, and source-version has no effect. Follow the ordered migration recipe before changing the target.

What is different in YAML 1.2

Literal YAML 1.1 YAML 1.2
yes, no, on, off and case variants (Yes, No, ON, ...) Booleans Plain strings
y, Y, n, N Booleans Plain strings
true, True, TRUE, false, False, FALSE Booleans Booleans
null, Null, NULL, ~ Null Null
0755 (leading zero integer) Octal Decimal
08 (leading zero, not octal) String Decimal
22:22 (base-60, or sexagesimal) Integer 1342 Plain string
1_000, 0b1010 Integers Plain strings
2026-10-10 Timestamp Plain string

ryl applies YAML 1.2 semantics to both linted files and configuration files.

Which YAML version each reader follows

Few readers follow one YAML version throughout, and a %YAML directive does not switch most of them. Pick target-version for the oldest reader that loads your files. Each reader below loaded eight undeclared plain scalars (yes, on, 0777, 0o17, 1_000, 0b1010, 22:22, 2026-10-10) into a generic map or object, then the same file under %YAML 1.2 and %YAML 1.1. 1.1 or 1.2 means all eight took that version's value, and "no change" means the directive changed no value. "Version option" names the loader setting that changes which version's values the reader resolves, each run to confirm the change. In Defense of YAML covers why the two versions differ.

Last verified: 2026-11-02.

Reader Version Undeclared %YAML 1.2 %YAML 1.1 Version option Used by
PyYAML safe_load 6.0.3 1.1 No change No change No yamllint, Ansible
ruamel.yaml, default and typ='safe' 0.19.1 1.2, except 1_000, 0b1010 and 2026-10-10 load as non-strings No change 1.1 yaml.version = (1, 1), or via %YAML pre-commit-hooks
py-yaml12 0.2.0 1.2 No change No change No
gopkg.in/yaml.v2, go.yaml.in/yaml/v2 2.4.0, 2.4.4 1.1, except 0o17 is 15 and 22:22 and 2026-10-10 are strings Rejected No change No
sigs.k8s.io/yaml 1.6.0 As go-yaml v2, with numbers as float64 Rejected No change No Kubernetes, Helm
gopkg.in/yaml.v3, go.yaml.in/yaml/v3 3.0.1, 3.0.6 yes, on and 22:22 are strings, but 0777 is 511, 1_000 and 0b1010 integers and 2026-10-10 a time; into a bool field yes is true Rejected No change No
go.yaml.in/yaml/v4 4.0.0-rc.8 (pre-release) As go-yaml v3 Rejected No change No Docker Compose (pins rc.6)
goccy/go-yaml 1.19.2 1.2, except 0777 is 511 and 1_000 and 0b1010 are integers No change No change No
js-yaml 5.5.0 1.2 No change No change schema: YAML11_SCHEMA
js-yaml 4.3.2 1.2, except 0b1010 is 10 and 2026-10-10 a Date No change No change No ESLint (@eslint/eslintrc)
yaml (eemeli) 2.9.1 1.2 No change 1.1 version: '1.1'; a %YAML directive overrides it Prettier
Psych safe_load with permitted_classes: [Date] (Ruby 4.0.9); without it the date is an error 5.3.1 1.1, except 22:22 is 80520 No change No change No
SnakeYAML 2.7 1.1 No change No change No Spring Boot, Jackson 2.x
SnakeYAML Engine 3.2 Every scalar a string, 0777 and 0o17 included No change No change setSchema(new CoreSchema()) gives 1.2; nothing selects 1.1
YamlDotNet 18.1.0 Every scalar a string; into a bool or int field yes is true, 0777 511, 1_000 1000 and 0b1010 10 No change No change WithAttemptingUnquotedStringTypeDeserialization reads 0777 as 777; nothing selects 1.1
serde_yaml (deprecated) 0.9.34 1.2, except 0777 is a string and 0b1010 is 10 No change No change No
serde_yml 0.0.13 1.2 No change No change No
saphyr 0.3.3 1.2 No change No change No

"Rejected" means the reader refuses the whole file (found incompatible YAML document), so Kubernetes, Helm and Docker Compose cannot load a file declaring %YAML 1.2. The go-yaml rejection breaks both specs. YAML 1.2.2 §6.8.1 says a 1.2 processor must accept %YAML 1.2, and YAML 1.1 §7.1.1 says a 1.1 processor should process a higher minor version with a warning. go-yaml accepts exactly 1.1 and rejects every other version, although its README claims most of YAML 1.2.

Implications for the quoted-strings rule

ryl format adds quotes required by an enabled quoted-strings rule only to plain scalars that resolve to strings under the effective version. Explicit %YAML directives override target-version; an undeclared document targeting 1.1 must remain a string under both versions. A plain true, 8080 or null stays typed. Timestamp-shaped text can receive required quotes under explicit YAML 1.2.

With quote-type: double, required: only-when-needed, ryl considers "yes" to need quoting because the bareword would parse as a boolean in 1.1. The safeguard applies unless the document declares %YAML 1.2 or target-version = "1.2" is set, since removing the quotes would change the value for a 1.1 consumer.

Implications for configuration files

ryl parses .yamllint / .yamllint.yaml / .yamllint.yml configs with the same strict YAML 1.2 parser. A yamllint configuration that uses 1.1 booleans like:

rules:
  truthy:
    check-keys: no       # 1.1 boolean false
  empty-values:
    forbid-in-block-mappings: yes

…will fail to parse in ryl. Replace these values with their YAML 1.2 equivalents (false / true) or run the built-in converter to produce a .ryl.toml instead:

ryl --migrate-configs --migrate-write

The migration converter writes TOML, where booleans have an unambiguous syntax independent of YAML version.

Implications for documents being linted

The rules below behave the way they do because ryl reads a directive-less input as YAML 1.2 (an explicit %YAML 1.1 shifts the value-resolving rules to 1.1, as above):

  • truthy — the rule itself still recognises the 1.1 truthy word list as ambiguous and flags barewords like yes or On so authors are warned about consumers that still use 1.1, unless target-version = "1.2" declares there are none.
  • octal-values — 0755 is treated as decimal 755; the rule can still report it for ambiguity reasons.
  • float-values — numeric formats follow the 1.2 spec.
  • schema-dependent-values — flags the other plain scalars the two versions read differently, such as 2026-10-10, 22:22 and 1_000.
  • yaml-directive — requires each document to declare its version. Avoid requiring %YAML 1.2 for Kubernetes, Helm or Compose; see the go-yaml warning.

For documents that need to be portable between 1.1 and 1.2 consumers, the safest pattern is to quote any bareword that 1.1 would coerce. quoted-strings and ryl format keep those quotes for you.