YAML Ain't Markup Language (YAML™) 1.0

3.1.1 Character Set

YAML streams use a subset of the Unicode character set. A YAML parser must accept all printable ASCII characters, the space, tab, line break, and all Unicode characters beyond 0x9F. A YAML emitter must only produce those characters accepted by the parser, but should also escape all non-printable Unicode characters if a character table is readily available.

c-printable ::=
    #x9 | #xA | #xD
  | [#x20-#x7E] | #x85
  | [#xA0-#xD7FF]
  | [#xE000-#xFFFD]
  | [#x10000-#x10FFFF] 

The range above explicitly excludes the surrogate block [#xD800-#xDFFF], DEL 0x7F, the C0 control block [#x0-#x1F], the C1 control block [#x80-#x9F], #xFFFE and #xFFFF. Note that in UTF-16, characters above #xFFFF are represented with a surrogate pair. DEL and characters in the C0 and C1 control block may be represented in a YAML stream using escape sequences.

3.1.2 Encoding

A YAML parser is required to support the UTF-32, UTF-16 and UTF-8 character encodings. If an input stream does not begin with a byte order mark, the encoding shall be UTF-8. Otherwise the encoding shall be UTF-32 (LE or BE), UTF-16 (LE or BE) or UTF-8, as signaled by the byte order mark. Note that as YAML files may only contain printable characters, this does not raise any ambiguities. For more information about the byte order mark and the Unicode character encoding schemes see the Unicode FAQ.

c-byte-order-mark ::= #xFEFF 

3.1.3 Indicators

Indicators are special characters that are used to describe the structure of a YAML document.

c-sequence-entry ::= '-' 

c-mapping-entry ::= ':' 

c-sequence-start ::= '[' 

c-sequence-end ::= ']' 

c-mapping-start ::= '{' 

c-mapping-end ::= '}' 

c-collect-entry ::= ',' 

c-top-key ::= '?' 

c-alias ::= '*' 

c-anchor ::= '&' 

c-transfer ::= '!' 

c-literal ::= '|' 

c-folded ::= '>' 

c-single-quote ::= ''' 

c-double-quote ::= '"' 

c-throwaway ::= '#' 

c-directive ::= '%' 

c-reserved ::= '@' | '`' 

3.1.4 Line Breaks

The Unicode standard defines several line break characters. These line breaks can be grouped into two categories. Specific line breaks have well-defined semantics for breaking text into lines and paragraphs. The semantics of generic line break characters is not defined beyond "ending a line".

b-line-feed ::= #xA 

b-carriage-return ::= #xD 

b-next-line ::= #x85 

b-line-separator ::= #x2028 

b-paragraph-separator ::= #x2029 

b-char ::=
    b-line-feed
  | b-carriage-return
  | b-next-line
  | b-line-separator
  | b-paragraph-separator 

b-generic ::=
    ( b-carriage-return
      b-line-feed )greedy
  | b-carriage-return
  | b-line-feed
  | b-next-line 

b-specific ::=
    b-line-separator
  | b-paragraph-separator 

b-any ::=
  b-generic | b-specific 

Outside scalar text content, YAML allows any line break to be used to terminate lines, and in most cases also allows such line breaks to be preceded by trailing comment characters. On output, a YAML emitter is free to emit such line breaks using whatever convention is most appropriate. An emitter should avoid emitting trailing line spaces.

3.1.5 Miscellaneous

This section includes several common character range definitions.

nb-char ::= c-printable - b-char 

s-char ::= #x9 | #x20 

ns-char ::= nb-char - s-char 

ns-ascii-letter ::=
  [#x41-#x5A] | [#x61-#x7A] 

ns-decimal-digit ::= [#x30-#x39] 

ns-hex-digit ::=
    ns-decimal-digit
  | [#x41-#x46] | [#x61-#x66] 

ns-word-char ::=
    ns-decimal-digit
  | ns-ascii-letter | '-' 

3.2.1 Indentation

In a YAML text representation, structure is determined from indentation, where indentation is defined as a line break character followed by zero or more space characters.

Tab characters are not allowed in indentation. Since different systems treat tabs differently, portability problems are a concern. Therefore, YAML's tab policy is conservative; they are not allowed. Note that most modern editors may be configured so that pressing the tab key results in the insertion of an appropriate number of spaces.

With one notable exception, a node must be more indented than its parent node. All sibling nodes must use the exact same indentation level. However the content of each such node may be indented independently.

The indentation level is used exclusively to delineate structure. Indentation characters are otherwise ignored. In particular, they are never taken to be a part of the the serialized text.

i-spaces(n) ::= #x20 x n 

i-spaces(<n) ::= i-spaces(m) 

i-spaces(<=n) ::= i-spaces(m) 

Since the YAML stream depends upon indentation level to delineate blocks, additional productions are a function of an integer, based on the i-spaces(n), i-spaces(<n) and i-spaces(<=n) productions above. In some cases the notation production(any) is used; it is a shorthand for "production(n) for some specific of n such that n >= 0".

The '-' sequence entry indicator is perceived by people to be part of the indentation. Hence the indentation rules are slightly more flexible when dealing with this indicator. First, a block sequence need not be indented relative to its parent node, unless that node is a block sequence entry. For example:

a key in a mapping at indentation level 0:
# The value for this key is a block sequence.
- This sequence is also at indentation level 0.
-   Another entry in the sequence.
- # The value of this entry is a nested sequence.
 - This nested sequence must be
  indented at least to level 1.
 - Another entry in the nested sequence.
- Last entry in block sequence at indentation level 0.
second key in mapping: at indentation level 0. 

In addition, in the special case when the value of a sequence entry is a block collection, and neither the nested block collection nor its first entry have any properties specified (type family or anchor), then this first entry may be specified in the same line as the '-' indicator of the containing sequence entry. In this case both the '-' and any following spaces are counted as part of the indentation. For example:

- This sequence is not indented.
-   map-in-seq: further indented by four.
    this key: is also further indented by four.
-  - seq-in-seq; further indented by three.
   -    second entry in nested sequence.
- Last entry in top sequence. 

3.2.2 Throwaway comments

Throwaway comments have no effect whatsoever on the data serialized in the stream. Their usual purpose is to communicate between the human maintainers of the file. A typical example is comments in a configuration file.

A throwaway comment always spans to the end of a line. It consists of white spaces, optionally followed by a '#' indicator and arbitrary comment characters to the end of the line.

Outside text content, empty lines or lines containing only white space are taken to be implicit throwaway comment lines. Lines containing indentation followed by '#' and comment characters are taken to be explicit throwaway comment lines.

A throwaway comment may appear before a document node or following any node. It may not appear inside a scalar node, but may precede or follow it.

c-nb-throwaway-comment ::=
  c-throwaway nb-char* 

l-comment(n) ::=
    l-empty-comment(n)
  | l-text-comment(n) 

l-empty-comment(n) ::=
  i-spaces(<=n) b-any 

l-text-comment(n) ::=
  i-spaces(<n)
  c-nb-throwaway-comment
  b-any 

s-b-trailing-comment ::=
  ( s-char+
    c-nb-throwaway-comment? )?
  b-any 

###The first tree lines of this stream

## are comments (the second one is empty).
this: |   # Comments may trail block indicators.
    contains three lines of text.
    The third one starts with a
    # character. This isn't a comment.

# The last three lines of this stream
# are comments (the first line is empty). 

3.3.1 Document

A YAML stream may contain several independent YAML documents. A document header line is used to start a new document. This line must start with a document separator: '---' followed by a line break or a sequence of space characters. If no explicit header line is specified at the start of the stream, the parser should behave as if a header line containing an unadorned '---' was specified.

When YAML is used as the format for a communication stream, it is useful to be able to indicate the end of a document independent of starting the next one. Without such a marker, the YAML processor reading the stream would be forced to wait for the header of the next document (that may be long time in coming) in order to detect the end of the previous document.

To support this scenario, a YAML document may be terminated by a '...' line. Nothing but throwaway comments may appear between this line and the (mandatory) header line of the following document.

ns-ns-document-header ::=
  ns-ns-document-start
  ( s-char+ c-ns-directive )* 

ns-ns-document-start ::= '-' '-' '-' 

l-l-after-document ::=
  ns-ns-document-end b-any
  l-comment(any)* 

ns-ns-document-end ::= '.' '.' '.' 

--- >
This YAML stream contains a single text value.
The next stream is a log file - a sequence of
log entries. Adding an entry to the log is a
simple matter of appending it at the end. 

---
at: 2001-08-12 09:25:00.00 Z
type: GET
HTTP: '1.0'
url: '/index.html'
---
at: 2001-08-12 09:25:10.00 Z
type: GET
HTTP: '1.0'
url: '/toc.html' 

# This stream is an example of a top-level mapping.
invoice : 34843
date    : 2001-01-23
total   : 4443.52 

# A one-line alternative syntax for the above document.
[ invoice: 34843, date: 2001-01-23, total: 4443.52 ] 

# The following is a stream of three documents. The first is an empty
# mapping, the second an empty sequence, and the last an empty string.
--- {}
--- [ ]
--- '' 

# A communication channel based on a YAML stream.
---
sent at: 2002-06-06 11:46:25.10 Z
payload: Whatever
# Receiver can process this as soon as the following is sent:
...
# Even if the next message is sent long after:
---
sent at: 2002-06-06 12:05:53.47 Z
payload: Whatever
... 

3.3.2 Directive

Directives are instructions to the YAML parser. Like throwaway comments, directives are not reflected in the data serialized in the stream. Directives apply to a single document. It is an error for the same directive to be specified more than once for the same document.

c-ns-directive ::=
  c-directive ns-ns-directive-name
  c-mapping-entry ns-ns-directive-value 

ns-ns-directive-name ::=
  ( ns-char - c-mapping-entry )+ 

ns-ns-directive-value ::= ns-char+ 

This version of YAML defines a single directive, %YAML. Additional directives may be added in future versions of YAML. A parser should ignore unknown directives with an appropriate warning. There is no provision for specifying private directives. This is intentional.

The %YAML directive specifies the version of YAML the document adheres to. This specification defines version 1.0.

A version 1.0 parser should accept documents with an explicit %YAML:1.0 directive, as well as documents lacking a %YAML directive. Documents with a directive specifying a higher minor version (e.g. %YAML:1.1) should be processed with an appropriate warning. Documents with a directive specifying a higher major version (e.g. %YAML:2.0) should be rejected with an appropriate error message.

3.3.3 Text Node

A text node begins at a particular level of indentation, n, and its content is indented at some level >n. A text node can be a collection (mapping or sequence), a scalar (block or flow) or an alias.

A YAML document is a normal node. However a document can't be an alias (there is nothing it may refer to). Also if the header line is omitted the first document must be a collection.

s-l-top-value-node(n) ::=
    s-l-top-alias-node
  | s-l-top-collect-node(n)
  | s-l-top-scalar-node(n) 

ns-ns-flow-value-node(n) ::=
    ns-ns-alias
  | c-c-flow-collect-node(n)
  | ns-ns-flow-scalar-value-node(n) 

ns-s-top-key-node(n) ::=
    ( c-top-key s-l-top-value-node(>n)
      i-spaces(n) )
  | ( ns-ns-flow-key-node(n) s-char* ) 

ns-ns-flow-key-node(n) ::=
    ns-ns-alias
  | c-c-flow-collect-node(n)
  | ns-ns-flow-scalar-key-node(n) 

s-l-top-alias-node ::=
  s-char ns-ns-alias
  s-b-trailing-comment
  l-comment(any)* 

l-l-top-flow-collect-node(n) ::=
  i-spaces(n)
  c-c-flow-collect-node(n)
  s-b-trailing-comment
  l-comment(any)* 

s-l-top-collect-node(n) ::=
    s-l-blk-collect-node(n)
  | ( s-s-required(n)
      c-c-flow-collect-node(n)
      s-b-trailing-comment
      l-comment(any)* ) 

s-l-blk-collect-node(n) ::=
  ( s-char+ c-ns-collect-properties )?
  s-b-trailing-comment
  l-comment(any)*
  l-l-blk-collection(n) 

c-c-flow-collect-node(n) ::=
  ( c-ns-collect-properties s-char+ )?
  c-c-flow-collection(n) 

s-l-top-scalar-node(n) ::=
    s-l-blk-scalar-node(n)
  | ( s-s-required(n)
      ns-ns-top-scalar-value-node(n)
      s-b-trailing-comment
      l-comment(any)* ) 

s-l-blk-scalar-node(n) ::=
  ( s-char+ c-ns-scalar-properties )?
  s-char+ c-l-blk-scalar(n) 

ns-ns-top-scalar-value-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-top-scalar-value(n) 

ns-ns-flow-scalar-value-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-flow-scalar-value(n) 

ns-ns-flow-scalar-key-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-flow-scalar-key(n) 

3.3.4 Node Property

Each text node may have anchor and transfer method properties. These properties are specified in a properties list appearing before the node value itself. For a top-level node (a document), the properties appear in the document header line, following the directives (if any). It is an error for the same property to be specified more than once for the same node.

c-ns-collect-properties ::=
    ( c-ns-collect-transfer
      ( s-char+ c-ns-anchor-property )? )
  | ( c-ns-anchor-property
      ( s-char+ c-ns-collect-transfer )? ) 

c-ns-scalar-properties ::=
    ( c-ns-scalar-transfer
      ( s-char+ c-ns-anchor-property )? )
  | ( c-ns-anchor-property
      ( s-char+ c-ns-scalar-transfer )? ) 

3.3.5 Transfer Method

The transfer method property specifies how to load the associated node. It includes the type family for the node and, for global scalar type families, an optional specific format used, separated by a '#' character.

Like throwaway comments and directives, formats are not reflected in the data serialized in the stream. In contrast, the type family is considered to be part of this data.

implicit integer type family: 12
also implicit integer family: ! "12"
explicit integer, implicit format: !int 12
also implicit format: !int# 0x12
explicit format: !int#dec 0x12 

# The following values have the same type family.
- !domain.tld,2002/type\x30 value
- !domain.tld,2002/type0 value 

# The following are different as far as YAML is concerned.
- !domain.tld,2002/type%30 value
- !domain.tld,2002/type0 value 

# 'taguri:domain.tld,2002:invoice' is some type family.
invoice: !domain.tld,2002/^invoice
  # 'seq' is shorthand for 'taguri:yaml.org,2002:seq'.
  # This does not effect '^customer' below
  # because it is does not specify a prefix.
  customers: !seq
    # '^customer' is shorthand for the full notation
    # '!domain.tld,2002/customer' that stands for the
    # URI 'taguri:domain.tld,2002:customer'.
    - !^customer
      given : Chris
      family : Dumars 

c-prefix ::= '^' 

c-format ::= '#' 

ns-transfer-char ::=
    ns-esc-sequence
  | ( ns-char - c-escape - c-format ) 

ns-mundane-transfer-char ::=
  ns-transfer-char - ':' - '/' 

c-ns-collect-transfer ::=
  c-transfer
  ( /* empty (implicit) */
  | ns-ns-transfer-family
  | ( prefix-of-above?
      c-prefix
      suffix-of-above ) ) 

c-ns-scalar-transfer ::=
  c-transfer
  ( /* empty (implicit) */
  | ns-ns-transfer-family
  | ns-ns-transfer-format
  | ( prefix-of-above?
      c-prefix
      suffix-of-above ) ) 

ns-ns-transfer-family ::=
  c-ns-private-family
  ns-ns-global-family 

ns-ns-transfer-format ::=
  ns-ns-transfer-family
  c-format ns-ns-format 

c-ns-private-family ::=
  c-transfer ns-transfer-char+ 

ns-ns-global-family ::=
    ns-ns-core-family
  | ns-ns-vocabulary-family
  | ns-ns-domain-family 

ns-ns-format ::= ns-transfer-char* 

ns-ns-core-family ::=
  ( ns-mundane-transfer-char
  - c-transfer )
  ns-mundane-transfer-char* 

ns-ns-vocabulary-family ::=
  ns-word-char+ '/' ns-transfer-char* 

ns-ns-domain-family ::=
  ns-word-char+
  ( '.' ns-word-char )
  ',' ns-ns-domain-year
  ( '-' ns-ns-domain-day-month
    ( '-' ns-ns-domain-day-month )? )?
  '/' ns-transfer-char* 

ns-ns-domain-year ::=
  ns-decimal-digit x 4 

ns-ns-domain-day-month ::=
  ns-decimal-digit x 2 

3.3.6 Anchor

An anchor is a property that can be used to mark a node for future reference. An alias node can then be used to indicate additional inclusions of an anchored node by specifying the node's anchor.

c-ns-anchor-property ::=
  c-anchor ns-ns-anchor-name 

ns-ns-anchor-name ::= ns-char+ 

3.5.1 Sequence

A sequence node is the simplest node kind. It is a an ordered collection of sub-nodes at a higher indentation level. A flow style is available for short, simple sequences. Also, if a sub-sequence node has no properties, and its first entry is specified without any properties, the sub-sequence node may immediately follow the sequence entry indicator.

l-l-blk-sequence(n) ::=
  ( i-spaces(n[-1])
    c-l-blk-seq-entry(n[-1]) )+ 

c-l-blk-seq-entry(n) ::=
  c-sequence-entry
  ( s-l-top-value-node(>n)
  | i-l-seq-in-seq(n)
  | i-l-map-in-seq(n) ) 

i-l-seq-in-seq(n) ::=
  i-spaces(m)
  c-l-blk-seq-entry(n+m+1)
  l-l-blk-sequence(n+m+1)? 

c-c-flow-sequence(n) ::=
  c-sequence-start
  s-s-optional(n)
  ( ns-ns-flow-value-node(n)
    s-s-optional(n)
    ( c-collect-entry
      s-s-required(n)
      ns-ns-flow-value-node(n)
      s-s-optional(n) )* )?
  c-sequence-end 

empty: []
flow: [ one, two, three # May span lines,
         , four,        # indentation is
           five ]       # mostly ignored.
block:
- Note indicator is not indented.
-
 - Subordinate sequence entry (note must be indented).
 - Another entry in subordinate sequence
- - Another way to write a sub-sequence
  - Another entry in sub-sequence
- >
 A folded sequence entry (fifth entry) 

3.5.2 Mapping

A mapping node is an unordered association of unique keys with values. It is an error for two equal key entries to appear in the same mapping node. In such a case the processor may continue, ignoring the second key and issuing an appropriate warning. This strategy preserves a consistent information model for streaming and random access applications.

A flow form is available for short, simple mapping nodes. Also, if a mapping node has no properties, and its first key is specified as a flow scalar without any properties, this first key may immediately follow the sequence entry indicator.

l-l-blk-mapping(n) ::=
  ( i-spaces(n)
    ns-l-blk-map-entry(n) )+ 

i-l-map-in-seq(n) ::=
  i-spaces(m)
  ns-ns-flow-scalar-key(n+m+1)
  s-char*
  c-mapping-entry
  s-l-top-value-node(>n+m+1)
  l-l-blk-mapping(n+m+1)? 

ns-l-blk-map-entry(n) ::=
  ns-s-top-key-node(n)
  c-mapping-entry
  s-l-top-value-node(>n) 

c-c-flow-mapping(n) ::=
  c-mapping-start
  s-s-optional(n)
  ( ns-ns-flow-map-entry(n)
    s-s-optional(n)
    ( c-collect-entry
      s-s-required(n)
      ns-ns-flow-map-entry(n)
      s-s-optional(n) )* )?
  c-mapping-end 

ns-ns-flow-map-entry(n) ::=
  ns-ns-flow-key-node(n)
  s-char*
  c-mapping-entry
  s-s-required(n)
  ns-ns-flow-value-node(n) 

empty: {}
flow: { one: 1, two: 2 }
spanning: { one: 1,
   two: 2 }
block:
 key : value
 nested mapping:
  key: Subordinate mapping
 nested sequence:
  - Subordinate sequence
!float 12 : This key is a float.
"\a" : This key had to be escaped.
? '?'
: This key had to be quoted.
? >
 This is a multi
 line folded key
: Whose value is
  also multi-line.
? this also works as a key
: with a value at the next line.
?
 - This key
 - is a sequence
:
 - With a sequence value.
?
 This: key
 is a: mapping
:
 with a: mapping value.
---
- A key: value pair in a sequence.
  A second: key:value pair.
- The previous entry is equal to the following one.
-
 A key:
     value pair in a sequence.
 A second:
     key:value pair. 

3.6.1 End Of line Normalization

Inside all scalar nodes, a compliant YAML parser must translate the two-character combination CR LF, any CR that is not followed by an LF, and any NEL into a single LF (this does not apply to escaped characters). LS and PS characters are preserved. These rules are compatible with Unicode's newline guidelines.

Normalization functionality is indicated by the use of the b-as-line-feed production defined below.

b-as-line-feed ::= b-generic 

b-normalized ::=
  b-as-line-feed | b-specific 

On output, a YAML emitter is free to serialize end of line markers using whatever convention is most appropriate, though again LS and PS must be preserved.

3.6.2 Block Modifiers

Each block scalar may have explicit indentation and chomping modifiers. These modifiers are specified following the block style indicator. It is an error for the same modifier to be specified more than once for the same node.

ns-ns-blk-modifiers ::=
    ( ns-explicit-indent
      c-chomp-control? )
  | ( c-chomp-control
      ns-explicit-indent? ) 

3.6.3 Explicit Indentation

Typically the indentation level of a block scalar node is detected from its first non-empty content line. This detection fails when this first non-empty line contains leading white space characters. Note that content lines, including the first non-empty content line, may begin with a '#' character.

When the first non-empty content line begins with spaces, YAML requires that the indentation level for the scalar node text content be given explicitly. This level is specified as the integer number of the additional indentation spaces used for the text content.

If the block scalar begins with lines containing only spaces, and no explicit indentation is given, the parser assumes such lines are empty lines. It is an error for any such leading empty line to contain more spaces than the indentation level that is deduced from the first non-empty content line.

The indentation level is always non-zero, except for the top level node of each document. This node is commonly indented by zero spaces (not indented). Note that in this case, all lines up to the next document seperator are assumed to be content lines, even if they begin with a '#' character.

It is always valid to specify an explicit indentation level, though emitters should not do so in cases where detection succeeds. It is an error for detection to fail when there is no explicit indentation specified.

ns-explicit-indent ::= ns-decimal-digit 

# Explicit indentation must be given
# in both the following cases.
leading spaces: |2
      This value starts with four spaces.

leading spaces after empty lines: |2

      This value starts with four spaces.

# The following is valid:
leading comment indicator: |

  # Content line starts with a '#'
  character, and follows empty lines.

# This is a comment because it is not
# more indented than the base level.
# Since blocks may not contain comments,
# this ends the block and the following
# empty line is not a content line.

# Explicit indentation may
# also be given when it is
# not required.
redundant: |2
  This value is indented 2 spaces.

# Indentation applies to top level nodes.
--- |
Usually top level nodes are not indented.
--- |
  This text is indented two spaces.
  It contains no leading spaces.
--- |0
  This text contains two leading spaces.
---
This text is not indented, so
# this is a content line and
--- |
  However, this is indented two spaces
# So this is a comment ending the block. 

3.6.4 Chomping

Typically the final line break of a block scalar is considered to be a part of its value, and any trailing empty lines are taken to be comment lines. This default "clip" chomping behavior can be overriden by specifying a chomp control modifier.

c-chomp-control ::=
    c-strip-chomp
  | c-keep-chomp 

c-strip-chomp ::= '-' 

c-keep-chomp ::= '+' 

strip ('-')

The '-' chomp control specifies that the final line break character of the block scalar should be stripped from its value.

keep ('+')

The '+' chomp control specifies that any trailing empty lines following the block scalar should be considered to be a part of its value. If this modifier is not specified, such lines are considered to be empty throwaway comment lines and are ignored.

When this functionality is implied, the l-l-empty-trailing(n) production will be used.

l-l-empty-trailing(n) ::=
    l-empty-comment(n)+
  | l-blk-empty-line-feed(n)+ 

l-blk-empty-line-feed(n) ::=
  i-spaces(<=n) b-as-line-feed 

clipped: |
    This has one newline.

same as "clipped" above: "This has one newline.\n"

stripped: |-
    This has no newline.

same as "stripped" above: "This has no newline."

kept: |+
    This has two newlines.

same as "kept" above: "This has two newlines.\n\n" 

3.6.5 Literal

A literal scalar is the simplest scalar form. No processing is performed on literal scalar characters aside from end of line normalization and stripping away the indentation. Indentation is detected from the first content line. Explicit indentation must be specified in case this yields the wrong result.

This restricts literal scalars to printable characters only. Also, long lines can't be broken. In exchange for these restrictions, a literal scalar may use any printable character, including line breaks. This makes literal scalars the most readable format for source code or other text values with significant use of indicators, quotes, escape sequences, and line breaks.

c-l-literal(n) ::=
  c-literal
  ns-ns-blk-modifiers?
  s-b-trailing-comment
  l-l-literal-value(n)?
  l-l-empty-trailing(n)?
  ( l-text-comment(<n)
    l-comment(any)* )? 

l-l-literal-value(n) ::=
  l-l-literal-chunk(n)+ 

l-l-literal-chunk(n) ::=
  l-blk-empty-line-feed(n)*
  ( l-literal-text(n)
  | l-blk-empty-specific(n) ) 

l-blk-empty-specific(n) ::=
  i-spaces(<=n) b-specific 

l-literal-text(n) ::=
  i-spaces(n) nb-char+ b-normalized 

empty: |

literal: |
 The \ ' " characters may be
 freely used. Leading white
    space is significant.

 Line breaks are significant. Thus this value
 contains one empty line and ends with a single
 line break, but does not start with one.

is equal to: "The \\ ' \" characters may \
 be\nfreely used. Leading white\n   space \
 is significant.\n\nLine breaks are \
 significant. Thus this value\ncontains \
 one empty line and ends with a single\nline \
 break, but does not start with one.\n"

# Comments may follow a block scalar value.
# They must be less indented.

# Modifiers may be combined in any order.
indented and chomped: |2-
    This has no newline.

also written as: |-2
    This has no newline.

both are equal to: "  This has no newline." 

3.6.6 Folding

When folding is done, a single normalized line feed is converted to a single space (#x20). When two or more consecutive (possibly indented) normalized line feeds are encountered, the parser does not convert them into spaces. Instead, the parser ignores the first of the line feeds and preserves the rest. Thus a single line feed can be serialized as two, two line feeds can be serialized as three, etc.

When folding is done, specific line breaks are preserved and may be safely used to convey text structure.

b-as-space ::= b-generic 

b-ignored ::= b-generic 

b-l-blk-trimmed(n) ::=
  b-ignored
  l-blk-empty-line-feed(n)+ 

i-s-ignored-leading(n) ::=
  i-spaces(n) s-char+ 

s-s-ignored-trailing ::= s-char+ 

l-flow-empty-specific(n) ::=
  ( i-spaces(<=n)
  | i-s-ignored-leading(n) )
  b-specific 

l-flow-empty-line-feed(n) ::=
  ( i-spaces(<=n)
  | i-s-ignored-leading(n) )
  b-as-line-feed 

b-l-flow-trimmed(n) ::=
  b-ignored
  l-flow-empty-line-feed(n)+ 

s-l-end-flow-line(n) ::=
  s-s-ignored-trailing
  ( b-as-space
  | b-l-flow-trimmed(n)
  | b-specific ) 

3.6.7 Folded

A folded scalar is similar to a literal scalar. However, unlike a literal scalar, a folded scalar is subject to (block) line folding. This allows long lines to be broken anywhere a space character (#x20) appears, at the cost of requiring an empty line to represent each line feed character.