Protocol Schema

The Diagram Scene Protocol (DSP) is formally defined by two JSON Schema files. These are the canonical, machine-readable specification for scene documents and operation envelopes.

Schema files

Schema	URL	Description
Scene Schema	scene.schema.json	Defines the structure of DSP scene documents - elements, styles, assets, constraints, computed data
Operations Schema	ops.schema.json	Defines the structure of operation envelopes and all 17 operation types

Both schemas use JSON Schema Draft 2020-12.

Scene schema

The scene schema (scene.schema.json) defines:

Top-level document - schemaVersion, scene, elements, styles, assets, constraints, computed, extensions, diagramFamily, layoutStrategy
7 diagram families - architecture, workflow, entityRelationship, sequence, network, orgchart, uiflow (always declare on every scene)
7 element kinds - node, edge, group, frame, text, image, guide
12 node shapes - rect, roundedRect, ellipse, diamond, cylinder, pill, hexagon, parallelogram, cloud, box3d, textBox, iconBox
52+ node types - generic types plus family-namespaced types (workflow., er., sequence., network., org., uiflow.)
4 edge routers - straight, orthogonal, curved, polyline
17 edge types - default plus family-specific types
10 constraint types - align, distribute, sameSize, stack, centerIn, contain, grid, minGap, noOverlap, order
5 cardinality values - one, many, zero-or-one, zero-or-many, one-or-many
8 container types - generic, pool, lane, subprocess, partition, package, boundary, fragment
Style properties - fill, stroke, strokeWidth, cornerRadius, fontFamily, fontSize, fontWeight, textColor, dash, labelBackground, opacity, accentColor

Operations schema

The operations schema (ops.schema.json) defines:

Envelope structure - schemaVersion, sceneId, baseRevision, transactionMode, ops array, message
17 operation types - createNode, updateNode, deleteElement, createEdge, updateEdge, groupElements, ungroupElements, createFrame, moveElement, resizeElement, setStyle, setText, addConstraint, removeConstraint, autoLayout, normalizeScene, updateScene

Using the schemas

Validation

Use any JSON Schema validator to check scene documents or operation payloads against the schemas:

# Using ajv-cli
npx ajv validate -s https://zindex.ai/schemas/scene.schema.json -d my-scene.json

# Using Python jsonschema
python3 -c "
import json, jsonschema, urllib.request
schema = json.loads(urllib.request.urlopen('https://zindex.ai/schemas/scene.schema.json').read())
scene = json.load(open('my-scene.json'))
jsonschema.validate(scene, schema)
print('Valid')
"

Code generation

Generate TypeScript, Python, or other language types from the schemas:

# Using json-schema-to-typescript
npx json-schema-to-typescript https://zindex.ai/schemas/scene.schema.json > dsp-types.ts

Agent discovery

Agents can fetch the schemas programmatically to understand the protocol structure:

GET https://zindex.ai/schemas/scene.schema.json
GET https://zindex.ai/schemas/ops.schema.json

These URLs are stable and can be referenced in agent instructions, MCP tool descriptions, or system prompts.