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

#A worked example

A webhook payload drawn as nested containers:

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

Get the cardinality right and the rest follows.