A scalar is a single value. YAML has five ways of writing one: plain, single-quoted and double-quoted, which are covered here, and the literal and folded block styles, which are on Block scalars and chomping.
| Style | Written | Escapes | Spans lines |
|---|---|---|---|
| Plain | hello world | None | Yes, folded |
| Single-quoted | 'it''s' | Only '' | Yes, folded |
| Double-quoted | "a\tb" | Backslash escapes | Yes, folded |
| Literal | | | None | Yes, line breaks kept |
| Folded | > | None | Yes, folded |
Plain scalars
A plain scalar has no quotes. It is the shortest style, and the only one that can be read as a number, boolean or null, because a plain scalar’s type is decided from what it looks like (see Tags and schemas).
How a plain scalar can start
It cannot start with white space or with an indicator:
- ? : , [
] { } # &
* ! | > '
" % @ `.
The indicators -, ? and : can start one when
the next character is not white space (or a flow indicator, inside a flow
collection), so -1, ?x and :x are plain.
@ and ` are reserved and cannot start one at all.
What a plain scalar cannot contain
:(a colon followed by white space) ends it, and so does a colon at the end of a line.#(a hash after white space) starts a comment, so it ends it too.- Inside a flow collection, a plain scalar also ends at the flow indicators
,[]{}, and at a colon before one. - Leading and trailing white space is not part of it.
Otherwise the characters are free: a:b, c#d and
http://example.com/ are all plain scalars.
Quoted scalars
Single-quoted
Text between ' characters. The only special form is '', which
is one quote character. A backslash is an ordinary character.
a: 'it''s' # it's
b: 'C:\no\escape' # the backslashes are keptDouble-quoted
Text between " characters, with backslash escapes. It is the only style
that can represent every character, including ones that are not allowed in a YAML
file. JSON strings are double-quoted scalars.
Escape sequences
| Escape | Character |
|---|---|
\0 | Null (U+0000) |
\a | Bell (U+0007) |
\b | Backspace (U+0008) |
\t or backslash + tab | Horizontal tab (U+0009) |
\n | Line feed (U+000A) |
\v | Vertical tab (U+000B) |
\f | Form feed (U+000C) |
\r | Carriage return (U+000D) |
\e | Escape (U+001B) |
\ (backslash + space) | Space (U+0020) |
\" | Double quote (U+0022) |
\/ | Slash (U+002F) |
\\ | Backslash (U+005C) |
\N | Next line (U+0085) |
\_ | Non-breaking space (U+00A0) |
\L | Line separator (U+2028) |
\P | Paragraph separator (U+2029) |
\xXX | 8-bit: two hexadecimal digits |
\uXXXX | 16-bit: four hexadecimal digits |
\UXXXXXXXX | 32-bit: eight hexadecimal digits |
Any other character after a backslash is an error. A backslash at the end of a line joins the line to the next one, with no space, and drops the next line’s leading white space.
Line folding
Plain and quoted scalars can span lines. When they do, their line breaks are folded:
- A single line break becomes a space.
- A run of n line breaks (blank lines) gives n − 1 newlines.
- White space around a line break is dropped.
plain: first line
second line
fourth line
quoted: "first
second"plain reads first line second line, a newline, then fourth lineContinuation lines of a plain scalar, or of a quoted one, must be indented at least as far as the block collection around them requires, and cannot start with a document marker. In a multi-line double-quoted scalar a backslash protects a space at the end of a line from being dropped.
Which style a writer should choose
These values need quoting, or a block style, to stay strings: ones that start with an
indicator, ones that contain : or #, ones that look like
numbers, booleans or null, and ones with significant spaces at either end.
Specification
These rules are in section 7.3 of YAML 1.2.2, and escape sequences in section 5.7, and folding in section 6.5.