Skip to content

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:

  1. Which quote type is preferred — single, double, either, or consistent with the first checked quoted scalar.
  2. When must a string be quoted — always, only when YAML would otherwise interpret it as a non-string type, or optionally.
  3. Which scalars are in scope — values only, or both values and mapping keys.

Why this matters

  • Avoid accidental retyping. Bareword values like 1.0 or true are 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:

[lint.rules.quoted-strings]
required = false
extra-required-flow = ['\?|^:']

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:

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

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.

  • 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.