.YAML File Format – Block scalars and chomping

YAML Ain’t Markup Language

A block scalar holds text on the lines below a header. It needs no quotes or escapes. It is the usual way to put a script, a paragraph or a certificate in a YAML file.

  1. |Style | literal or > folded1 character
  2. +Chomping - strip, + keep, or nothing to clipoptional
  3. 2Indentation indicator a digit 1 to 9, before or after the chompingoptional
  4. #Comment with white space in front of itoptional
The first line of a block scalar: |+2 # comment

The text starts on the next line. It is indented more than the node that contains it, and it ends at the first non-empty line indented less than the text. A # line indented like the text is text, not a comment.

Literal style

A literal scalar keeps its line breaks. Indentation up to the text’s level is removed.

script: |
  echo one
    echo two
  echo three
Reads echo one\n echo two\necho three\n

Folded style

A folded scalar joins lines with spaces. A blank line becomes a line break. Lines that start with extra white space (more-indented lines) keep their line breaks, so a block of code inside a paragraph is left as it is.

summary: >
  One long
  sentence on two lines.

  A new paragraph.
    keep this line
  After it.
The value has one space where lines were joined, a newline at the blank line, and the indented line kept

Chomping

Chomping decides what happens to the line break at the end of the text, and to any blank lines after it.

IndicatorNameFinal line breakBlank lines after it
noneClipKept (one)Dropped
-StripDroppedDropped
+KeepKeptKept, each as a line break
 
clip: |
  text

strip: |-
  text

keep: |+
  text

next: value
The values are "text\n", "text" and "text\n\n"

A file that ends without a final line break gives a value with no final break, whichever chomping is used.

The indentation indicator

Normally the text’s indentation is found from its first non-empty line. A digit in the header states it instead, counted from the indentation of the parent node. It is needed when the text itself starts with spaces, or with blank lines that could be misread:

- |1
   two spaces kept
- |2
    the text starts with two spaces
The digit is the number of columns beyond the parent’s indentation

When the digit is absent, a blank line before the first line of text cannot have more spaces than that first line. That is an error.

Text at the top level of a document can have no indentation at all: a --- or ... line ends it.

Specification

These rules are in section 8.1 of YAML 1.2.2.