Protocol Overview

The Diagram Scene Protocol (DSP) is a structured format for creating and manipulating diagrams programmatically. It defines how scenes are structured, how operations mutate scenes, and how validation ensures correctness.

Design principles

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

Scene structure

A DSP scene contains:

{
  "schemaVersion": "0.1",
  "scene": {
    "id": "unique-id",
    "title": "My Diagram",
    "units": "px",
    "canvas": { "width": 1200, "height": 800, "background": "#ffffff" }
  },
  "elements": [],
  "styles": {},
  "assets": {},
  "constraints": []
}

Element kinds

Kind	Description
`node`	A shape with a label (rect, roundedRect, ellipse, diamond, cylinder, pill, hexagon, parallelogram, cloud)
`edge`	A connection between two nodes
`group`	A logical grouping of elements
`frame`	A visual container with a title bar
`text`	A standalone text block
`image`	An image element
`guide`	A horizontal or vertical alignment guide

Layout modes

Absolute — Elements positioned with explicit x, y, width, height
Relative — Elements positioned relative to other elements (rightOf, leftOf, above, below, inside)

Constraints

Constraints enforce spatial relationships between elements:

align — Align elements along an axis
distribute — Distribute elements evenly
sameSize — Make elements the same width/height
stack — Stack elements vertically or horizontally
centerIn — Center an element within another