YAML text is Unicode. A file may be UTF-8, UTF-16 or UTF-32. The specification recommends UTF-8, and most tools expect it.
Detecting the encoding
A reader looks at the first bytes of the stream. Either they are a byte order mark, or the first character must be ASCII, so its pattern of zero bytes gives the encoding away.
| First bytes | Encoding | By |
|---|---|---|
00 00 FE FF | UTF-32 big-endian | Byte order mark |
00 00 00 xx | UTF-32 big-endian | ASCII first character |
FF FE 00 00 | UTF-32 little-endian | Byte order mark |
xx 00 00 00 | UTF-32 little-endian | ASCII first character |
FE FF | UTF-16 big-endian | Byte order mark |
00 xx | UTF-16 big-endian | ASCII first character |
FF FE | UTF-16 little-endian | Byte order mark |
xx 00 | UTF-16 little-endian | ASCII first character |
EF BB BF | UTF-8 | Byte order mark |
| Anything else | UTF-8 | The default |
Every document in a stream must use the same encoding.
Byte order marks
A byte order mark, U+FEFF, may start the stream and may appear before each
document. It is not allowed inside a document.
Allowed characters
| Range | Characters |
|---|---|
U+0009 U+000A U+000D | Tab, line feed and carriage return |
U+0020 to U+007E | Printable ASCII |
U+0085 | Next line (NEL) |
U+00A0 to U+D7FF | The Basic Multilingual Plane, without the surrogates |
U+E000 to U+FFFD | The rest of that plane, without U+FFFE and U+FFFF |
U+10000 to U+10FFFF | The other planes |
The other control characters, such as U+0000 and U+007F, can
be written only as escapes in double-quoted text. See
Escape sequences.
Line breaks
A line break is a line feed (LF, U+000A), a carriage return
(CR, U+000D) or a CR and LF together. Inside a
scalar a line break is read as a single line feed.
Since YAML 1.2, NEL (U+0085), line separator (U+2028) and
paragraph separator (U+2029) are ordinary characters and do not break a
line. In YAML 1.1 they were line breaks.
White space
A space and a tab are white space. Indentation uses spaces only. A tab can separate tokens on a line, and it can stand in a scalar, where a tab inside text is content. A plain scalar’s line can have tabs at its ends, which are not part of the value.
key: value valid: a tab separates the colon and the value
key: value invalid: a tab cannot be indentationSpecification
These rules are in chapter 5 of YAML 1.2.2.