YAML block scalars: an OpenAPI cheat sheet

Markdown (CommonMark) is supported on OpenAPI fields like summary, description, externalDocs.description, schema/parameter/response description, etc.

And the situations to use each Scalar type can be a bit confusing if you don't do it everyday.

The types of Scalar

• > Folded (prose) — single newlines become spaces; blank lines = paragraph breaks. Best default for paragraphs.
• | Literal (layout-sensitive) — keep newlines exactly. Use for lists you want hard breaks, tables, or code you want untouched.

Modifiers

• Add - to strip the final newline (>-, |-) to avoid trailing EOLs.
• Add + to keep all trailing newlines (>+, |+) if you need them.

Notes

• Single newline = space (no hard break). Use two spaces + newline or a blank line for a real break.
• Blank line separates paragraphs.
• Lists usually need a blank line before them for consistent rendering.
• Code: use fenced blocks ``` for best results.

Prescriptions & examples

1) Long paragraphs (default choice)

description: >-
  Returns a list of orders filtered by status and date.
  Handles pagination and sorting.

Rendered preview:

Returns a list of orders filtered by status and date. Handles pagination and sorting.

---

2) Bullet lists (preserve structure)

description: |
  **Features**
  - Fast
  - Safe
  - Boring

Rendered preview:

Features

• Fast
• Safe
• Boring

---

3) Paragraphs + list (mix)

description: |
  Use this endpoint to manage orders.

  **Parameters**
  - `limit` — max items
  - `cursor` — pagination token

Rendered preview:

Use this endpoint to manage orders.

Parameters

• limit — max items
• cursor — pagination token

---

4) Code examples (literal or fenced)

description: |
  Example:
  ```bash
  curl -H "Authorization: Bearer <token>" /orders
  ```

Rendered preview:

Example:

curl -H "Authorization: Bearer <token>" /orders

---

5) Tables (avoid folding that might reflow pipes)

description: |
  | Field | Type    | Notes      |
  |------:|:-------:|------------|
  | id    | string  | required   |
  | total | number  | USD cents  |

Rendered preview:

Field	Type	Notes
id	string	required
total	number	USD cents

---

6) Multi-paragraph prose with soft wraps

description: >
  The export job runs asynchronously and may take several minutes.

  Use the `GET /jobs/{id}` endpoint to poll status.

Rendered preview:

The export job runs asynchronously and may take several minutes.

Use the GET /jobs/{id} endpoint to poll status.

---

TL;DR

Scenario	Symbols	Meaning (newline behavior)
Prose paragraph	>	Folded + clip — single newlines → spaces; keep one final newline.
Prose paragraph, no trailing \n	>-	Folded + strip — single newlines → spaces; no final newline.
Preserve manual line breaks
Preserve manual line breaks, no trailing \n		-