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.

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.