YAML multiline strings: the difference between | and >

Short answer

In YAML, | creates a literal block and preserves line breaks in its content. > creates a folded block and turns most single line breaks into spaces, while retaining paragraph boundaries and more-indented sections. The - and + suffixes control trailing line breaks.

|: a literal block

This YAML:

message: |
  first line
  second line

conceptually represents:

{ "message": "first line\nsecond line\n" }

Literal style is suitable for scripts, certificates, configuration fragments, or text where every line boundary matters. The common block indentation is removed from the value; it is not part of the string.

>: a folded block

With folded style:

message: >
  first line
  second line

the usual value is:

{ "message": "first line second line\n" }

This is useful for prose that should be split across source lines without creating a logical newline at every wrap. A blank line retains a paragraph boundary, and a more-indented line follows different rules, so > is not a blind replacement of every \n with a space.

Inspect the exact result with the YAML to JSON converter. It accepts the YAML 1.2 subset representable in JSON and displays line breaks as \n escapes in the resulting string.

-, no suffix, and +

The chomping indicator controls the end of the value:

For example, |- is useful when the value must not end in a newline. Use |+ only when multiple final breaks are meaningful data.

Compare the six forms with exact output

Paste this complete example into the YAML to JSON converter. Each block has one blank line after its second content line. Keep those blank lines when copying; the final end key makes the last block’s boundary explicit.

literal_strip: |-
  first line
  second line

literal_clip: |
  first line
  second line

literal_keep: |+
  first line
  second line

folded_strip: >-
  first line
  second line

folded_clip: >
  first line
  second line

folded_keep: >+
  first line
  second line

end: true

The resolved JSON is:

{
  "literal_strip": "first line\nsecond line",
  "literal_clip": "first line\nsecond line\n",
  "literal_keep": "first line\nsecond line\n\n",
  "folded_strip": "first line second line",
  "folded_clip": "first line second line\n",
  "folded_keep": "first line second line\n\n",
  "end": true
}

The JSON escape \n represents one newline character in the value. Literal versus folded controls the break between the two lines; strip, clip and keep control the trailing breaks separately. These outputs describe the non-empty blocks above; an empty block does not gain text or a newline merely from |.

Indentation and common mistakes

Content must start farther in than its key. YAML normally detects indentation from the first non-empty content line; an explicit depth such as |2 is also available for special cases. Do not add one unless it is needed.

• Choose | when line breaks are data and > when source lines make a paragraph.
• Do not mistake the dash in |- for a sequence marker.
• Check the final character when a consumer compares signatures, templates, or commands exactly.
• Review extra spaces because a more-indented line may stop folding.

The YAML 1.2.2 specification defines literal and folded styles and documents chomping separately. Convert and compare the resolved value whenever every byte matters.