YAML Multiline String Styles (| and >)
Master YAML's multiline string options: literal block (|) and folded block (>). Learn when to use each style and how they convert to and from JSON.
Detailed Explanation
One of YAML's most powerful features is its multiline string support. JSON requires all strings to be on a single line with \n escape sequences for newlines, which makes long text unreadable. YAML offers two block scalar styles that solve this elegantly.
Literal Block Scalar (|) -- preserves newlines:
description: |
This is line one.
This is line two.
This is line three.
Converts to this JSON:
{
"description": "This is line one.\nThis is line two.\nThis is line three.\n"
}
Every line break in the YAML is preserved exactly as \n in the JSON string. The trailing newline is included by default.
Folded Block Scalar (>) -- folds newlines into spaces:
description: >
This is a long paragraph
that will be folded into
a single line.
Converts to this JSON:
{
"description": "This is a long paragraph that will be folded into a single line.\n"
}
Line breaks are replaced with spaces, making it ideal for long paragraphs that you want to wrap in the YAML file for readability.
Chomping indicators control trailing newlines:
|+or>+(keep): preserves all trailing newlines|-or>-(strip): removes the final trailing newline|or>(clip, default): keeps one trailing newline
clean: |-
No trailing newline here
Results in JSON: "No trailing newline here" (no \n at the end).
When converting from JSON to YAML, any string containing \n characters can be rendered using block scalars for improved readability. This is especially valuable for embedded scripts, SQL queries, or documentation text.
Use Case
Embedding a multi-line shell script or SQL query inside a CI/CD configuration file where readability matters, such as a GitHub Actions step that runs a complex bash command.