Render JSON / YAML as a diagram

Introduction

Raw config and API payloads are tedious to read: a single order JSON expands into a dozen indented lines, and a YAML deployment manifest into dozens of nested ones. Both engines have a way to turn such “pure data” into a structure diagram. PlantUML ships native @startjson / @startyaml directives that render the data as a tree automatically. Mermaid has no built-in JSON parser, but its flowchart syntax maps naturally onto a tree, which makes it more flexible in return. This article draws the same order payload in both engines and explains when each one is the better choice.

PlantUML version

PlantUML has dedicated diagram types for data: wrap JSON in @startjson and YAML in @startyaml, and the result is a tree of field names where indentation maps straight onto nesting depth.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@startjson
{
  "id": "ORD-2026-1042",
  "status": "PAID",
  "customer": {
    "name": "Alice",
    "tier": "gold"
  },
  "items": [
    { "sku": "P-001", "qty": 2, "price": 49.99 },
    { "sku": "P-002", "qty": 1, "price": 99.00 }
  ],
  "total": 198.98
}
@endjson

Key points:

• No extra declaration needed: paste the payload as-is and every field becomes a node.

• Arrays expand into sibling nodes: the two entries of the items array become parallel branches.

• YAML works the same way: swap @startjson / @endjson for @startyaml / @endyaml. For example, a Kubernetes deployment manifest:

  1 2 3 4 5 6 7 8 9 10 11 12 13

  @startyaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: replicas: 3 template: spec: containers: - name: my-app image: my-app:1.0 @endyaml

• Careful: do not put JSON inside @startuml — it will be parsed as ordinary UML text and produce garbage output.

Mermaid version

Mermaid has no JSON directive, but a flowchart’s “nodes plus edges” is a natural fit for a tree. The technique is to treat each object as a node and each field as an edge.

1
2
3
4
5
6
7
8
9

flowchart TD
  ROOT["ORD-2026-1042"] --> status["status = PAID"]
  ROOT --> customer["customer"]
  customer --> name["name = Alice"]
  customer --> tier["tier = gold"]
  ROOT --> items["items (2)"]
  items --> i1["P-001 x2 @ 49.99"]
  items --> i2["P-002 x1 @ 99.00"]
  ROOT --> total["total = 198.98"]

Key points:

• Quote node labels with square brackets: write ROOT["ORD-2026-1042"], not ROOT[ORD-2026-1042] — unquoted labels containing spaces get truncated.

• flowchart TD lays out vertically, LR horizontally; use LR for large structures to save horizontal space.

• You decide how to handle arrays: a label like items (2) summarises the array, and you attach the individual entries below it — Mermaid does not expand arrays on its own, and this “summary plus detail” shape reads more like how people parse data.

• subgraph groups one level of the structure:

  1 2 3 4 5 6 7

  flowchart TD subgraph A["customer"] direction TB A1["name = Alice"] A2["tier = gold"] end ROOT["ORD-2026-1042"] --> A

• Never paste a raw JSON string into a label: the quotes and braces inside {"a": 1} are parsed as Mermaid syntax, so replace them with plain text first.

Side-by-side

Which to pick: to drop a data snapshot into a README or an API doc, use PlantUML’s @startjson — it is the least work. If you want to add grouping, callouts or status markers, or the payload only has three fields, a Mermaid flowchart is clearer. Mixing is fine too: use Mermaid to explain the structure and PlantUML to attach a verbatim snapshot.

Wrap-up

Turning JSON and YAML into diagrams is fundamentally about treating data as structure. PlantUML takes the automatic route — one directive turns the source into a tree. Mermaid takes the manual route and draws the hierarchy explicitly with a flowchart. The first suits snapshots and quick archival; the second suits real documentation where the diagram has to explain and annotate.