quoted-strings¶

What this rule does¶

Enforces a consistent quoting style for string scalars and controls when quotes are required.

The rule answers three questions:

Which quote type is preferred — single, double, or either.
When must a string be quoted — always, only when YAML would otherwise interpret it as a non-string type, or never.
Which scalars are in scope — values only, or both values and mapping keys.

Why this matters¶

Avoid accidental retyping. Bareword values like yes or 1.0 are silently parsed as booleans or floats. Quoting prevents this.
Consistent diffs. Mixing 'foo' and "foo" in the same file causes noisy diffs whenever an editor or formatter normalises the style.
Escapes and interpolation. Single-quoted YAML scalars do not process escape sequences; double-quoted ones do. Picking the right type per project avoids surprises with \n, \t, and Unicode escapes.

Examples¶

The examples below assume quote-type = "double" and required = "only-when-needed" (the recommended starting point).

Allowed¶

title: A plain bareword string
flag: "yes"            # quoted because yes would parse as a boolean
escape: "line1\nline2" # quoted because it uses an escape sequence

Reported¶

flag: yes              # unintentional boolean
title: 'A plain string'  # single-quoted when double is configured

After `ryl --fix`¶

flag: "yes"
title: "A plain string"

Configuration¶

[rules.quoted-strings]
level = "warning"
quote-type = "any"
required = true
extra-required = []
extra-allowed = []
allow-quoted-quotes = false
allow-double-quotes-for-escaping = false  # ryl-only
check-keys = false

Option	Default	Description
`quote-type`	`"any"`	`"single"`, `"double"`, or `"any"`. The quote style required when the rule decides a string must be quoted.
`required`	`true`	`true` — every string scalar must be quoted. `false` — no string scalar may be quoted. `"only-when-needed"` — require quotes only when leaving the scalar bare would change its YAML type.
`extra-required`	`[]`	Regular expressions; values matching any pattern must be quoted regardless of `required`.
`extra-allowed`	`[]`	Regular expressions; values matching any pattern may be quoted even when `required = false`.
`allow-quoted-quotes`	`false`	Permit single quotes inside a single-quoted string (and analogously for doubles) instead of forcing a switch to the other quote type.
`allow-double-quotes-for-escaping`	`false`	ryl-only. When `quote-type = "single"` and `required = "only-when-needed"`, allow double quotes specifically for strings that need an escape sequence.
`check-keys`	`false`	Also apply the rule to mapping keys, not only values.

Automatic fixing¶

ryl --fix rewrites string scalars to use the configured quote-type and adds or removes quotes to satisfy required. The fix is conservative: it only changes scalars where the corrected form parses to the same value as the original.

Disable the fix for this rule by adding it to [fix].unfixable:

[fix]
fixable = ["ALL"]
unfixable = ["quoted-strings"]

YAML 1.2 caveat with `required = "only-when-needed"`¶

ryl applies YAML 1.2 implicit-type resolution when deciding whether a quoted scalar is redundantly quoted. Under YAML 1.2 the barewords yes, no, on, off, True, False, and their case variants parse as plain strings (only lowercase true / false are booleans). yamllint uses YAML 1.1 semantics, where the longer list is boolean.

The practical consequence is that "yes" (with required: "only-when-needed", quote-type: "double") is flagged by ryl as redundantly quoted but accepted by yamllint. To match yamllint's behaviour, set required = true so all string scalars are quoted regardless of type, or rely on the truthy rule to flag ambiguous barewords and keep quoted-strings off. See YAML version compatibility for more context.

truthy — complements quoted-strings by reporting bareword booleans that would otherwise need quoting.
empty-values — controls how missing values are written, which interacts with whether nulls should be quoted.