Quoting

The decision rule

Three ways to write a string. Pick with this order, top to bottom, first match wins.

1. The value must contain \n, \t, or a \uXXXX escape → double quotes. 2. The value could be read as a number, bool, null, date, or version, or it starts with an indicator character, or it contains : or # → single quotes. 3. Otherwise → plain, no quotes.

plain: api-gateway
needs_single: '*'
needs_single_too: 'no'
needs_double: "line one\nline two"

Plain scalars, and what breaks them

A plain scalar is unquoted. It may contain most characters, but a handful of positions are reserved. These all fail or mis-parse:

Two cases that surprise people by working:

url: http://x.com     # ok, ':' with no space after is fine
hashtag: a#c          # ok, '#' with no space before is fine
negative: -a          # ok, '-' only opens a sequence when followed by a space
question: ?a          # ok, same rule for '?'

So the real triggers are : (colon then space), # (space then hash), and an indicator in first position. Everything else is safe plain.

Single quotes

Inside '...' there is exactly one escape: '' for a literal apostrophe. Backslashes are literal characters.

a: 'it''s fine'          # -> it's fine
b: 'C:\Users\new'        # -> C:\Users\new  (no \n here)
c: 'a #b'                # -> a #b, the hash is inert
d: '*'                   # -> *
e: 'yes'                 # -> the string "yes"

Single quotes are the right default for anything you want taken literally: Windows paths, regexes, glob patterns, Jinja and Helm templates, anything with a {{ }} in it.

Double quotes

"..." is the only form with real escapes. This is the full table.

msg: "tab\there, newline\nthere, caf\u00e9, \x41 = A"

parses to 'tab\there, newline\nthere, café, A = A', so the literal string is:

tab<TAB>here, newline
there, café, A = A

An unknown escape is a hard error, not a passthrough. "a\qb" fails to scan. This is the trap with regexes: "\d+" is invalid YAML, so write '\d+'.

Line continuation folds a long double-quoted value onto one line:

long: "the quick \
  brown fox"

parses to 'the quick brown fox', one space, because the leading indentation of the next line is stripped.

Keys follow the same rules

A key is just a scalar, so it needs quoting for the same reasons, and it hits the type resolver too.

"a b": 1          # keys with spaces work plain too, but quote for clarity
"on": true        # WITHOUT quotes, PyYAML makes this the key True
"1": one          # WITHOUT quotes this is the integer key 1
"null": x         # WITHOUT quotes this is the null key
"off": disabled   # WITHOUT quotes, PyYAML makes this the key False

on: 1 under PyYAML parses to {True: 1}, which is why GitHub Actions workflows read fine in CI (its parser is 1.2) and blow up in a local Python linter. Quote on, off, no, yes, y, n, true, false, null, and any all-digit key.

Quick reference