# JSON structure diagram

API documentation full of raw JSON is technically complete and practically unreadable. A structure diagram shows the shape: what nests inside what, what repeats, what is optional.

Keep the raw payload too. The diagram is for understanding, the payload is for copying.

---

## When to reach for one

* Webhook and API documentation for external consumers.
* Explaining a deeply nested payload without asking people to count brackets.
* Contract discussions, where the shape is the negotiation.

---

## How to draw it in Capable

| **Route** | **Use when**                                                |
| --------- | ----------------------------------------------------------- |
| Mermaid   | A class or graph view of the structure, kept in text.       |
| D2        | Nested containers, which map naturally onto nested objects. |

---

## A worked example

A webhook payload drawn as nested containers:

![JSON structure diagram](https://help.gocapable.com/images/att1431601176.svg)

The source, which you can paste into a new diagram and edit:

```
payload: webhook event {
  id: id (string)
  type: type (string)
  created: created (timestamp)

  data: data {
    order: order {
      id: id (string)
      total: total (number)
      status: status (enum)
    }
    customer: customer {
      id: id (string)
      email: email (string, optional)
    }
    items: items[] {
      sku: sku (string)
      qty: qty (number)
    }
  }
}
```

---

## A few things that catch people out

* Mark optional fields. Consumers break on the fields you forgot to mention were optional.
* Arrays deserve to look like arrays; a single box implies a single object.
* Keep the diagram and a real example payload on the same page.

---

## Related

[Entity relationship diagramTables, keys and the lines between them.](https://help.gocapable.com/diagrams/entity-relationship-diagram.html)

[Crow's foot notationReading the little marks at the end of the line.](https://help.gocapable.com/diagrams/crow-s-foot-notation.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Get the cardinality right and the rest follows._