Scene schema

A diagram is a scene document in DSP, the Diagram Scene Protocol. Two JSON Schemas define it, and they are the machine-readable contract:

Schema	Defines
scene.schema.json	Scene documents: elements, styles, assets, constraints, computed data
ops.schema.json	Operation envelopes and the typed operations

Both use JSON Schema Draft 2020-12, and their URLs are stable. The schemas and the DSP spec are open source under the Apache License 2.0 at github.com/zindexai/diagram-scene-protocol; the Zindex engine and hosted service are not.

A scene document

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

schemaVersion, scene and elements are required.
diagramFamily is optional in the schema, but declare it on every scene: architecture, workflow, entityRelationship, sequence, network, orgchart or uiflow. It selects family node types, rules and drawing; without it the diagram draws as a generic flowchart, and nothing warns you (Diagram families).
layoutStrategy sets the direction (TB, BT, LR or RL) and spacing of the layered layout that architecture, workflow, entity-relationship and UI flow diagrams use (Layout engine).
scene holds the title, the canvas and brief, the diagram’s brief of up to 1,000 characters.
styles holds named styles elements refer to, palette the scene’s colours, constraints the constraints, and extensions options such as autoGroup.
computed is the engine’s drawing output (element boxes, edge routes, label positions). A read with view=dsp leaves it out.

Element kinds

Kind	Is
`node`	A shape with a label
`edge`	A connection between two elements
`group`	A logical grouping, not drawn
`frame`	A visual container with a title
`text`	A standalone text block
`image`	An image from the scene’s assets
`guide`	A horizontal or vertical guide line

Element types has every kind’s fields, shapes, node types and edge types.

Layout modes

Auto-layout, the default: leave layout off a node and the engine places it. After the first save it keeps each position in the node’s layout, unless a node that grows needs the room, a frame added or deleted round it would leave frames overlapping or a frame holding a node that isn’t its member, or an order constraint you add finds its two nodes the wrong way round. Sequence diagrams are laid out from their messages on every save.
Absolute: layout: { "mode": "absolute", "x": 40, "y": 40, "width": 180, "height": 70 }. Nodes and frames also take x, y, width and height directly, which Zindex turns into an absolute layout. Text and image elements need a layout.
Relative: layout: { "mode": "relative", "place": { "rightOf": "api", "gap": 40 } } places an element against another (rightOf, leftOf, above, below or inside).

A scene can mix them: fix some nodes and let the engine place the rest.

Checking a document

POST /v1/diagrams/validate and diagram_validate check a scene against the schema and every rule, with no key (Validation rules). Any JSON Schema validator checks the schema alone:

# ajv-cli reads local files: download the schema first.
# The schemas are Draft 2020-12 and use the uri and date-time formats.
curl -sO https://zindex.ai/schemas/scene.schema.json
npx -p ajv-cli -p ajv-formats ajv validate --spec=draft2020 --strict=false -c ajv-formats -s scene.schema.json -d my-scene.json

Types for other languages can be generated from the schemas, for example with npx -p json-schema-to-typescript json2ts -i scene.schema.json -o dsp-types.ts.