Protocol Overview

The Diagram Scene Protocol (DSP) is the structured format at the core of zindex - agent-native diagram state infrastructure. Zindex is a stateful diagram runtime for AI agents. DSP defines how scenes are structured, how operations mutate scenes, and how validation ensures correctness. Diagrams are durable state agents can patch, validate, diff, and render - not one-shot output regenerated from scratch on every prompt.

Using the protocol from an AI agent? Read How AI Agents Should Use Zindex for the recommended operational sequence for creating, updating, validating, and rendering scenes.

Why create a persisted scene? Stateless rendering works for one-shot previews, but persisted scenes give you: revision history (every edit is an immutable revision), incremental edits (change one node without regenerating the whole scene), visual diff (compare any two revisions - added=green, removed=red, modified=amber), and audit trail (“at this date, this is what the diagram looked like”). Always create a persisted scene for production diagrams.

Design principles

1. Operations, not pixels - Agents work with typed operations (createNode, createEdge, move) rather than pixel coordinates and mouse events
2. Validation-first - Every operation and scene state is validated against 40+ rules before execution
3. Immutable revisions - Each operation creates a new revision. No destructive mutations.
4. Format-agnostic - The scene model is independent of rendering format (SVG, PNG)

Diagram families

Always declare scene-level diagramFamily on every scene. The field is technically optional in the JSON schema, but it is effectively load-bearing - it gates family-specific behaviour the engine and downstream tooling rely on. Omitting it triggers a MISSING_DIAGRAM_FAMILY info diagnostic on the render response.

{
  "diagramFamily": "workflow",
  "schemaVersion": "0.1",
  "scene": { ... },
  "elements": [ ... ]
}

Supported families: architecture, workflow, entityRelationship, sequence, network, orgchart, uiflow.

When declared, the family enables:

• Family-specific node types - dot-namespaced values like workflow.start, er.entity, sequence.lifeline
• Family-specific edge types - workflow.sequenceFlow, er.relationship, sequence.message
• Family-specific validation - warnings for missing start/end nodes, isolated entities, etc.
• Family-specific rendering - sequence-family fan-in label exemption (same-label messages are temporally distinct), ER auto-promote-fk-labels and column-row anchoring, workflow BPMN conventions
• Typed containers - frames with containerType for pools, lanes, and subprocesses

Scenes without diagramFamily fall back to the generic-flowchart base case and lose all of the above. Always declare it.

Scene structure

A DSP scene contains:

{
  "schemaVersion": "0.1",
  "diagramFamily": "workflow",
  "layoutStrategy": { "algorithm": "hierarchical", "direction": "TB" },
  "scene": {
    "id": "unique-id",
    "title": "My Diagram",
    "units": "px",
    "canvas": { "width": 1200, "height": 800, "background": "#ffffff" }
  },
  "elements": [],
  "styles": {},
  "constraints": []
}

layoutStrategy is optional but recommended for auto-layout - when set, nodes can omit their layout field and the engine computes positions from the graph structure automatically. diagramFamily is technically optional in the schema but should always be declared (see Diagram families above).

Element kinds

Layout modes

• Absolute - Elements positioned with explicit x, y, width, height
• Relative - Elements positioned relative to other elements (rightOf, leftOf, above, below, inside)
• Auto-layout - Set layoutStrategy on the scene and omit layout from nodes. The engine computes positions using a Sugiyama-style hierarchical layout pipeline with crossing reduction and orthogonal edge routing. Supports 4 directions: TB, BT, LR, RL. Mixed mode is supported - fix critical nodes with explicit layout and let the engine position the rest. See the Layout Engine reference for the full pipeline.
• Position shorthand - Elements accept x, y, width, height directly instead of the layout wrapper. These are normalized to layout: { mode: "absolute", ... } automatically.

Node text wrapping

Node labels support textStyle for controlling text wrapping and alignment:

{
  "id": "card",
  "kind": "node",
  "shape": "roundedRect",
  "label": "A longer description that wraps within the node bounds",
  "layout": { "mode": "absolute", "x": 0, "y": 0, "width": 200, "height": 100, "autoSize": "content" },
  "textStyle": { "wrap": "word", "align": "left", "verticalAlign": "top" }
}

• wrap: "none" (default) | "word" | "character"
• align: "center" (default for nodes) | "left" | "right"
• verticalAlign: "middle" (default for nodes) | "top" | "bottom"

Set autoSize: "content" on the layout to auto-compute node height from the wrapped text content.

Constraints

10 constraint types enforce spatial relationships between elements:

• align - Align elements along an axis
• distribute - Distribute elements evenly with optional gap
• sameSize - Make elements the same width, height, or both
• stack - Stack elements vertically or horizontally with gap
• centerIn - Center elements within a container
• contain - Grow a container to enclose its children with padding
• grid - Arrange elements in a grid with configurable columns and gaps
• minGap - Enforce minimum spacing between sequential elements
• noOverlap - Push overlapping elements apart
• order - Hard spatial ordering enforced during auto-layout (leftOf, rightOf, above, below, sameRank)

Rendering

Scenes are rendered to SVG or PNG. Rendering is a projection - the scene is the canonical state, rendered output is a view.

Pass "theme" on render requests to control aesthetics without modifying the scene:

• clean - white background, clean lines, Inter font (default)
• dark - dark background, warm amber/green-cyan accents
• blueprint - navy background, cyan strokes, monospace font
• sketch - hand-drawn aesthetic with wobbly lines