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, either, or consistent with the first checked quoted scalar.
- When must a string be quoted — always, only when YAML would otherwise interpret it as a non-string type, or optionally.
- Which scalars are in scope — values only, or both values and mapping keys.
Why this matters¶
- Avoid accidental retyping. Bareword values like
1.0ortrueare silently parsed as floats or booleans. Quoting keeps them strings. - 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 # needs no quotes, so left bare
version: "1.0" # quoted because bare 1.0 would parse as a float
escape: "line1\nline2" # double-quoted to use an escape sequence
Reported¶
name: "plain" # redundantly quoted: a plain string needs no quotes
version: '1.0' # needs quoting, but single-quoted where double is required
After ryl check --fix¶
name: plain # redundantly quoted: a plain string needs no quotes
version: "1.0" # needs quoting, but single-quoted where double is required
Configuration¶
[lint.rules.quoted-strings]
level = "warning"
quote-type = "any"
required = true
extra-required = []
extra-required-flow = [] # ryl-only
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", "any", or "consistent". Consistent uses the first checked quoted scalar's style for subsequent checked scalars across the stream. |
required |
true |
true — every string scalar must be quoted. false — quotes are optional; configured quote style and extra-required still apply. "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-required-flow |
[] |
ryl-only, TOML-only. Regular expressions requiring quotes on matching strings inside flow collections, including mapping keys regardless of check-keys. Allowed with every required mode. |
extra-allowed |
[] |
Regular expressions; matching strings may retain otherwise redundant quotes under required = "only-when-needed". |
allow-quoted-quotes |
false |
Allow the other outer quote style when the string contains the configured quote character, avoiding escapes. |
allow-double-quotes-for-escaping |
false |
ryl-only. Allow double-quoted strings containing escapes despite the configured quote preference. |
check-keys |
false |
Also apply the rule to mapping keys, not only values. |
Automatic fixing¶
Some YAML readers reject ? or : in plain strings only inside flow collections.
Use extra-required-flow to quote those strings while leaving block-context
expressions plain and preserving their existing line breaks:
Patterns match decoded string values. Lint and check --fix use the existing
collection context; ryl format uses the final context, including collections
converted from block to flow. Flow patterns also apply to explicitly tagged strings
(!!str); other core tags remain exempt. Collection width includes the required
quotes before choosing flow style. Literal and folded block scalars remain unchanged.
Empty explicitly tagged scalars are exempt from flow patterns, including with anchors.
Both rewrite commands leave already-plain flow strings and keys unchanged when
extra-required or extra-required-flow would add compatibility quotes. Lint still
reports the missing quotes. For example, [?x] stays [?x]: legacy readers may
load a mapping before quoting and a string afterward. Strings converted from block
to flow still gain the required quotes.
ryl check --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 lint.unfixable:
ryl format imports the enabled rule's quote-presence requirements, including
extra-required, extra-required-flow, extra-allowed and check-keys. The formatter's
quote style chooses the quote character and preserves
wrapped plain scalar lines when adding quotes. quote-style = "preserve" freezes
quoting; keep-quotes = true retains optional quotes even when lint forbids them.
Conflicting lint rules explains warnings
and remedies. Quote additions inside implicit collection keys, or past an implicit
scalar key's length limit, are refused with a notice.
Scalars inside implicit collection keys never gain quotes.
YAML 1.1 values with required = "only-when-needed"¶
Unless the document declares %YAML 1.2 or
target-version = "1.2" is set,
a quoted scalar that YAML 1.1 reads as a non-string is not redundantly quoted: 'no',
'on', 'yes' and their case variants, 1.1 integers, floats, sexagesimals
and timestamps keep their quotes, and --fix leaves them in place, since
stripping them would change the value for a 1.1 consumer such as PyYAML.
'y', 'Y', 'n' and 'N' keep their quotes too, since
go-yaml v2, used by Kubernetes, loads them as booleans, and so do go-yaml's float
spellings ('08', '1e5', '-.5'). Quotes a YAML 1.2 reader needs are kept
under every version. ryl format keeps the same quotes. See
YAML version compatibility for more context.
Related rules¶
truthy— complementsquoted-stringsby reporting bareword booleans that would otherwise need quoting.empty-values— controls how missing values are written, which interacts with whether nulls should be quoted.