# 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)**

```yaml
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)**

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

**Rendered preview:**

> **Features**
>
> * Fast
> * Safe
> * Boring

---

**3) Paragraphs + list (mix)**

```yaml
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)**

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

**Rendered preview:**

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

---

**5) Tables (avoid folding that might reflow pipes)**

```yaml
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**

```yaml
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                   | |       | **Literal + clip** — keep all line breaks; keep **one** final newline.    |
| Preserve manual line breaks, no trailing `\n` | |-      | **Literal + strip** — keep all line breaks; **no** final newline.         |