JSON Catalog

A lookup guide for everything a Structly diagram JSON file can express today: metadata, custom node types, stages, nodes, edges, groups, side-panel entries, and playback flows.

Canonical file: .structly.json Schema: structly.schema.json Source of truth: JSON

Top Level

The renderer reads one diagram JSON file. These are the supported top-level keys.

Key	Required	Purpose
`$schema`	No	Points editors to `structly.schema.json` for validation and autocomplete.
`meta`	Yes	Diagram title, subtitle, version, and revision metadata.
`types`	Yes	User-defined visual categories for nodes and groups.
`stages`	Yes	Ordered lanes that decide which nodes render on the canvas.
`nodes`	Yes	Architecture components and their documentation.
`edges`	Yes	Connections between nodes.
`groups`	No	Dashed boundaries around related nodes.
`crossCutting`	No	Side-panel concerns that affect many nodes (auth, observability, idempotency, DLQ recovery). Group them with each entry's `category` field.
`fileFlows`	No	Animated playback paths for the Play button.
`filePaths`	No	Legacy shorthand converted into `fileFlows` at runtime.

Field	Type	Notes
`kicker`	string	Short label for the system or domain.
`title`	string	Main diagram title.
`subtitle`	string	One-line context shown in workspace cards.
`version`	number or string	Diagram version.
`revision`	string	Human-readable revision name.
`previousVersion`	string	Pointer to an older diagram file.

types

Types are fully user-defined. A type can represent services, queues, data stores, external systems, clients, jobs, agents, or anything else.

Field	Type	Notes
`label`	string	Displayed in the details panel tag.
`color`	CSS color	Used for node borders, group labels, and highlights.
`background`	CSS color	Used for node and group backgrounds.
`icon`	string	Reserved for future icon rendering.

"types": {
  "service": {
    "label": "Service",
    "color": "#2563eb",
    "background": "#eff6ff"
  },
  "queue": {
    "label": "Queue",
    "color": "#b45309",
    "background": "#fffbeb"
  }
}

stages

Stages are ordered buckets of node ids. Nodes must be listed in a stage to render on the canvas.

Field	Type	Notes
`id`	string	Stable stage identifier.
`label`	string	Readable stage title.
`nodes`	array	Node ids included in this stage.

"stages": [
  {
    "id": "services",
    "label": "02 - Services",
    "nodes": ["order-service", "payment-service"]
  }
]

nodes

Nodes are architecture components. Object form is preferred, but array form is also accepted if each node includes an id.

Field	Type	Notes
`id`	string	Required only in array-form nodes.
`type`	string	Must match a key in `types`.
`title`	string	Main node label. `label` is accepted as an alias.
`summary`	string	Small text under the title. `sublabel` is accepted as an alias.
`description`	string	Main details panel paragraph.
`details`	object	Key-value facts shown in the details panel.
`code`	array	Code/documentation snippets with `label` and `snippet` or `content`.
`topics`	array	Reserved documentation list for message topics.
`queries`	array	Reserved documentation list for query examples.

"nodes": {
  "order-service": {
    "type": "service",
    "title": "Order Service",
    "summary": "Creates and tracks orders",
    "description": "Owns order lifecycle state and emits order events.",
    "details": {
      "Language": "Go",
      "Primary table": "orders"
    },
    "code": [
      {
        "label": "event",
        "snippet": "OrderCreated { order_id, customer_id, amount, status }"
      }
    ]
  }
}

edges

Edges connect node ids. The renderer draws arrows and labels, and uses edge direction for selection highlights.

Field	Type	Notes
`from`	string	Source node id.
`to`	string	Target node id.
`label`	string	Optional edge label.
`kind`	string	Optional style hint. Current known values: `normal`, `consult`, `return`, `control`, `raw-write`, `group-flow`.
`animated`	boolean	Reserved flag for future per-edge animation control.

"edges": [
  { "from": "api-gateway", "to": "order-service", "label": "POST /orders" },
  { "from": "payment-service", "to": "payment-provider", "label": "authorize", "kind": "consult" }
]

groups

Groups draw dashed boxes around related nodes. They can include direct nodes, nested subgroups, and optional high-level flowsTo links.

Field	Type	Notes
`id`	string	Stable group identifier.
`label`	string	Group label shown above the boundary.
`type`	string	Type id used for group color.
`nodes`	array	Node ids inside the group.
`subgroups`	array	Nested labeled groups, each with its own node ids.
`flowsTo`	array	Group ids or node ids for high-level grouped arrows.

"groups": [
  {
    "id": "core-services",
    "label": "Core Services",
    "type": "service",
    "nodes": ["order-service", "payment-service"]
  }
]

Side Panels

crossCutting is an ordered array. Entries render one after another in the cross-cutting panel. DLQ/recovery is modeled as another cross-cutting entry, not a separate concept.

Field	Type	Notes
`id`	string	Stable panel entry identifier.
`shortBadge`	string	Short badge text shown in the panel and on affected groups. `badge` is accepted as an alias.
`shortBadgeColor`	CSS color	Badge text and border color. `badgeColor` is accepted as an alias.
`shortBadgeBackground`	CSS color	Badge background color. `badgeBackground` is accepted as an alias.
`label`	string	Entry title.
`summary`	string	Small text under the panel entry title.
`type`	string	Type id used for color.
`note`	string	Details panel role text.
`nodes`	array	Node ids affected by this concern. `affects` is accepted as an alias.
`description`	string	Optional extra documentation.
`details`	object	Optional key-value facts.

"crossCutting": [
  {
    "id": "auth",
    "shortBadge": "AU",
    "shortBadgeColor": "#0f766e",
    "shortBadgeBackground": "#ecfdf5",
    "label": "AuthN/AuthZ",
    "summary": "JWT and role checks",
    "type": "service",
    "note": "JWT validation and role checks happen at the gateway.",
    "nodes": ["api-gateway", "order-service"]
  },
  {
    "id": "dlq-recovery",
    "shortBadge": "DLQ",
    "shortBadgeColor": "#be123c",
    "shortBadgeBackground": "#fff1f2",
    "label": "DLQ Recovery",
    "summary": "Replay and manual investigation",
    "type": "external",
    "note": "Failed events route to recovery queues.",
    "nodes": ["event-bus", "payment-service"]
  }
]

fileFlows

Playback flows define ordered edge steps used by the Play button. A flow only highlights steps that match real edges.

Field	Type	Notes
`id`	string	Stable playback identifier.
`label`	string	Legend label while playback is active.
`color`	CSS color	Highlight color for active path nodes and edges.
`steps`	array	Ordered objects with `from` and `to`.

"fileFlows": [
  {
    "id": "checkout",
    "label": "Checkout to fulfillment",
    "color": "#0f766e",
    "steps": [
      { "from": "web-app", "to": "api-gateway" },
      { "from": "api-gateway", "to": "order-service" }
    ]
  }
]

Legacy filePaths can use "path": ["a", "b", "c"]. The renderer converts that into a -> b and b -> c steps.

Workspace JSON

The workspace file controls the home screen and points to diagram files.

Field	Type	Notes
`name`	string	Workspace title.
`description`	string	Short workspace description.
`diagrams`	array	Cards shown on the workspace page.
`diagrams[].id`	string	Used for route params and per-diagram layout storage.
`diagrams[].title`	string	Card title.
`diagrams[].subtitle`	string	Card description.
`diagrams[].path`	string	Path to a diagram JSON file.
`diagrams[].tags`	array	Filterable card tags.

{
  "$schema": "./structly.workspace.schema.json",
  "name": "Structly Workspace",
  "diagrams": [
    {
      "id": "orders",
      "title": "Order Platform",
      "subtitle": "Small service architecture example",
      "path": "examples/order-platform.structly.json",
      "tags": ["sample", "services"]
    }
  ]
}

Common Patterns

Microservices

Use types like client, service, queue, data, and external. Group services by bounded context.

Data Pipeline

Use stages for source, ingestion, raw lake, stream, workers, storage, compute, and consumers. Add fileFlows for source-to-consumer playback.

Platform Infrastructure

Use groups for environments or control planes. Use crossCutting for auth, observability, policy, compliance, secrets, idempotency, and DLQ recovery.

Incident Runbook

Add operational entries in crossCutting and use details fields for alert thresholds, owners, and runbook links.