YAML Lint / Guides

YAML multiline strings

YAML has five styles for multiline strings. The picker is two choices: do you want literal newlines (|) or folded into spaces (>), and what should happen to trailing blank lines (chomping: nothing, -, or +).

Try the linter on your block →

The five styles in one table

Style	Newlines inside	Trailing newlines
`\|`	Preserved	One (default "clip")
`\|-`	Preserved	None ("strip")
`\|+`	Preserved	All preserved ("keep")
`>`	Folded to spaces	One (default)
`>-`	Folded to spaces	None
`>+`	Folded to spaces	All preserved

Literal style: `|`

Preserves newlines exactly as you wrote them.

script: |
  #!/bin/bash
  set -e
  echo "starting"
  npm run build
  echo "done"

The parsed value:

"#!/bin/bash\nset -e\necho \"starting\"\nnpm run build\necho \"done\"\n"

Use | for: shell scripts, code blocks, SQL queries, formatted output — anything where line breaks are part of the content.

Folded style: `>`

Replaces single newlines with spaces. Empty lines become a single newline (paragraph break). Lines that are more indented than the block keep their newline.

description: >
  This is the first line of a long description that
  wraps across multiple lines in the source for
  readability.

  This is a second paragraph.

The parsed value:

"This is the first line of a long description that wraps across multiple lines in the source for readability.\nThis is a second paragraph.\n"

Use > for: prose, long descriptions, anything where you want to wrap source lines for readability without that affecting the data.

Chomping: what to do with trailing blank lines

The default ("clip") keeps a single newline at the end. Two modifiers change this:

- ("strip") — remove all trailing newlines and blank lines.
+ ("keep") — preserve all trailing newlines and blank lines.

Comparison:

default: |
  one
  two

strip: |-
  one
  two

keep: |+
  one
  two

Parsed values (showing trailing newlines as ↵):

default: "one↵two↵"
strip:   "one↵two"
keep:    "one↵two↵↵"

Common mistakes

Mixing tabs and spaces

Block scalar indent is space-only. A tab inside a literal block is kept as a tab in the value, but a tab as leading whitespace on a content line breaks YAML's indent detection. Configure your editor to insert spaces.

First-line indentation drift

YAML calculates the block indent from the first non-blank content line. If that first line is indented more than later lines, the baseline is wrong:

broken: |
      first line indented further
  than the rest

Most parsers reject this; some accept it but produce garbage. Make the first line the shallowest indentation.

Forgetting that `>` joins with spaces

Folded style strips the line break and puts a space in. If you wrote a list inline expecting newlines, you'll get a space-joined string instead. Use | when line breaks matter.

Quick decision flow

Is the content code, a script, or formatted output? → |
Is it prose where line breaks are just visual? → >
Need exactly zero trailing newlines? → add -
Need to preserve trailing blank lines exactly? → add +
None of the above strict? → default | is almost always fine.

Reference

YAML 1.2.2 spec — Block Scalar Styles

FAQ

What's the difference between | and > in YAML?

| (literal) preserves every newline as-is. > (folded) replaces single newlines with spaces, keeping blank lines as paragraph breaks. Use | for code, scripts, or anything where line breaks are content. Use > for prose where line breaks are just for line length.

Why does my YAML multiline string have a trailing newline?

Default chomping behavior — the parser keeps exactly one trailing newline at the end of the block. To remove all trailing newlines, use |- or >- (the - is the 'strip' chomping indicator). To preserve all trailing blank lines, use |+ or >+.

Can I have unquoted special characters inside a YAML multiline string?

Yes — block scalars (| and >) treat the entire content as plain text. Colons, hashes, brackets, and other YAML syntax characters all pass through untouched. This is the safest way to embed shell scripts, SQL queries, or templated content.

Why does my multiline string include extra indentation?

YAML strips the common leading whitespace based on the first non-blank line. If your first line is indented further than later lines, the parser uses that bigger indent as the baseline and you'll see negative-indent looking content. Make the first content line the smallest indent in the block.

How do I write a multiline string that's all on one line in JSON?

Use double-quoted flow scalar with explicit \n: "first line\nsecond line". Or use the folded style (>) which converts newlines to spaces — the JSON output will be a single space-separated string. The reverse: a JSON string with embedded \n converts to a YAML literal block on output.

Open the YAML linter →