What's the difference between |, > and >- in OpenAPI YAML descriptions?

Question

I'm looking at OpenAPI and the description tag. What are the differences between these tags? They all support multiple lines, but anything else?

description: |
description: >
description: >-

Answer 1

|, >, >- are some of YAML block style indicators. They are used to break a long string value over multiple lines and format multi-paragraphs Markdown strings. You can find more information here:

• https://yaml-multiline.info/
• How do I break a string in YAML over multiple lines?

In OpenAPI context, the use of > vs | in descriptions affects the resulting Markdown rendering.

> (folded style)

This replaces single new lines with spaces, but adds a new line at the end of the YAML value. To have a literal new line in the value, add a blank line between the lines. To start a new Markdown paragraph, add two blank lines between the paragraphs.

For example:

description: >
  Quick
  brown fox

  jumps over a lazy dog.


  And this is a new paragraph.

This means the description value is:

which after being processed with a Markdown renderer becomes:

<p>Quick brown fox<br/>
jumps over a lazy dog.</p>

<p>And this is a new paragraph.</p>

>- (folded style with the strip block chomping indicator)

Same as > but with no new line at the end of the YAML value.

Markdown renderers don't care about the trailing new line, so the > and >- styles are rendered exactly the same.

| (literal style)

New lines in the YAML value are kept as is. For example:

description: >
  Quick
  brown fox

  jumps over a lazy dog.


  And this is a new paragraph.

This means the description value is:

which will be rendered as

<p>Quick<br>
brown fox</p>

<p>jumps over a lazy dog.</p>

<p>And this is a new paragraph.</p>

Answer 2

description isn't a YAML "tag", it's just a field/property in the YAML file you're editing, such as an OpenAPI or Swagger document.

The YAML specification describes the different text folding styles here: https://yaml.org/spec/1.2/spec.html#id2793652

That's pretty hard to understand at first glance, so this site makes things a lot easier, and has interactive examples: https://yaml-multiline.info/