YAML Multiline Strings Explained

Block scalars: the header line

A block scalar starts with an indicator at the end of the key line, followed by the text indented on the following lines. The header has up to three parts:

1. Style: | (literal) keeps line breaks; > (folded) turns most line breaks into spaces.
2. Chomping (optional): nothing means clip, - means strip, + means keep. It controls the newlines at the end.
3. Indentation indicator (optional): a digit 1–9 giving the content indentation explicitly, needed only when the first line of text starts with spaces.

Chomping and indentation indicators can appear in either order, so |2- and |-2 mean the same thing. Inside a block scalar nothing is special: # is text, not a comment, quotes need no escaping, and backslash sequences such as \t are kept literally rather than interpreted.

Literal style: |

Every line break is kept exactly as written. The indentation of the first non-empty line is removed from every line.

literal: |
  line one
  line two

  line four

Result: "line one\nline two\n\nline four\n"

Use the literal style for anything where line breaks carry meaning: shell scripts in CI steps, SQL, PEM certificates, embedded config files, Markdown. It is the right default when in doubt.

Folded style: >

Folding joins adjacent lines with a single space, which lets you wrap a long sentence across lines in the source. Three rules govern it:

• a line break between two non-empty lines at the base indentation becomes a space
• an empty line becomes one \n (so a blank line separates paragraphs)
• lines indented more than the base are not folded: they and the line breaks around them are kept as written

folded: >
  This paragraph
  becomes one line.

  New paragraph.
    indented line kept
  last line

Result: "This paragraph becomes one line.\nNew paragraph.\n indented line kept\nlast line\n"

Folded style suits long descriptions, help text and messages. Avoid it for anything whitespace-sensitive: the more-indented rule surprises people who indent a code sample inside folded text.

Chomping: clip, strip and keep

Chomping decides what happens to the final line break and any trailing empty lines. Using the same text followed by one blank line each time:

clip: |
  text

strip: |-
  text

keep: |+
  text

end: here

Results: clip is "text\n" (exactly one newline, the default), strip is "text" (no trailing newline), and keep is "text\n\n" (the final line break plus every trailing empty line).

The same indicators work with folded style: >- is the common choice for a long single-line value such as a description, because it folds the source lines and leaves no trailing newline. |- is popular for values compared byte-for-byte, like a token or a hash, where a stray \n would break the comparison.

Indentation indicators

YAML normally detects the content indentation from the first non-empty line. That fails when the text itself should begin with spaces, because the parser cannot tell content spaces from indentation. An explicit digit fixes it; the number is counted from the indentation of the parent node:

code: |2
    indented first line
  normal line

Result: " indented first line\nnormal line\n" — the key is at column 0, so the indicator 2 marks the first two spaces as indentation and the other two as content.

Combined with chomping: a: |-2 followed by a line x gives " x", and b: >2- followed by y and z gives " y\n z". In the second case both lines are more indented than the declared base, so folding does not apply and the break is kept.

Flow scalars that span lines

Plain, single-quoted and double-quoted strings may also continue onto following lines. All three use line folding: a single line break becomes a space and an empty line becomes \n. Leading indentation on continuation lines is discarded.

plain: a plain
  multi-line value

  with a break
sq: 'it''s
  folded'
dq: "first line
  continues here\n\
  joined without space"

Results: plain is "a plain multi-line value\nwith a break", sq is "it's folded", and dq is "first line continues here\njoined without space".

The differences: plain scalars cannot contain : or # and are subject to type resolution (a plain yes may become a boolean). Single-quoted strings process no escapes except '' for a quote. Double-quoted strings support escapes such as \n, \t and \u00e9, and a backslash at the end of a line joins it to the next with no space — the only way to break a long string without inserting one. None of the flow styles produce a trailing newline.

Mistakes that break block scalars

• Tabs in the indentation. YAML forbids tabs for indentation, and a tab at the start of a content line is a syntax error.
• A line indented less than the first line. The first non-empty line sets the indentation; a later line with fewer spaces ends the scalar, and the parser then tries to read it as a new key, usually reporting a mapping error.
• Templating that loses indentation. When a Helm or Jinja template inserts multi-line text under |, every inserted line must carry the block’s indentation. Helm’s nindent function exists for exactly this.
• Trailing spaces. They are part of the content in literal style, so a certificate or key can fail to verify because of invisible whitespace. A formatter that strips trailing whitespace outside scalars will not touch them, so check with a visible-whitespace editor.

A comment is allowed on the header line itself (key: | # note), but not on the content lines below it.

Choosing a style

• Scripts, certificates, SQL, code: |
• Same, without a trailing newline: |-
• Long prose wrapped for readability: > or >-
• Short strings with special characters: double quotes with escapes
• Text that must keep trailing blank lines: |+

When converting YAML to JSON, the result is just a string, so you can check what a parser produced. Paste the document into the YAML to JSON converter and the \n characters become visible; the YAML formatter keeps your block style when it re-indents a file.

Related

• yaml formatter
• yaml to json
• json to yaml
• json vs yaml
• yaml mapping values not allowed
• yaml tabs not allowed