Canvas Snapshot Format

A Canvas snapshot is the complete shared state of a Canvas at one version. Per-user client state, such as selection and the camera, is not part of it.

Snapshot

Field	Type	Description
`nodes`	list	Canvas nodes. See Node
`edges`	list	Connections between nodes. See Edge

An empty snapshot is { nodes: [], edges: [] }.

Canonicalization

Snapshots are canonicalized before they are saved.

Accepted and Discarded

The input accepts the following fields, and canonicalization removes them:

Field on nodes	Field on edges	Reason
`measured`	—	Client-measured geometry
`selected`	`selected`	Per-user selection
`dragging`	—	Transient interaction
`resizing`	—	Transient interaction
`hovered`	`hovered`	Transient interaction
`pendingMutation`	`pendingMutation`	Client optimistic state
`clientCache`	`clientCache`	Client-derived data

viewport (the camera) is also accepted and discarded. It is per-user state, not shared Canvas state.

Node

Field	Type	Required
`id`	string	Yes
`type`	string	Yes
`label`	string	No
`position`	`{ x: number; y: number }`	Yes
`size`	`{ width: number; height: number }`	No
`parentId`	string	No
`collapsed`	boolean	No
`data`	node data. See Node Data Kinds	No
`backingReferences`	list of backing references. See Backing References	Yes
`selectedRun`	`{ flowRunId: string; flowPackageId: string }`	No

Invariant. When data is present, type must equal data.kind. A node whose type and data.kind disagree is rejected.

Edge

Field	Type	Required
`id`	string	Yes
`source`	string	Yes
`target`	string	Yes
`label`	string	No

Node Data Kinds

data.kind determines the node's meaning. The available kinds are:

Literal Kinds

Literal nodes pin an immutable definition artifact. No first-class resource exists for a literal.

Kind	Payload
`schema:literal`	`definitionArtifact: { artifactId, contentHash }`
`experience:literal`	`definitionArtifact: { artifactId, contentHash }`
`flow:literal`	`definitionArtifact: { artifactId, contentHash }`

Reference Kinds

Reference nodes point at a converted, first-class resource at a pinned version.

Kind	Payload
`schema:reference`	`resourceId`, `versionId`
`experience:reference`	`resourceId`, `versionId`
`flow:reference`	`resourceId`, `versionId`

Step Kinds

Kind	Payload
`step:extract-table`	`sheetName`, `range?`

Nodes with no data — for example uploaded file nodes and extracted table nodes — carry their content solely through backingReferences and use type: "artifact".

Backing References

backingReferences is a list of discriminated unions naming what a node is backed by. The available kinds are:

Kind	Fields
`entity`	`entityId`, `schemaId`
`artifact`	`artifactId`, `contentHash`
`resource`	`resourceType` (`schema` \| `experience` \| `flow`), `resourceId`, `versionId`
`flow-package`	`flowPackageId`, `versionId`
`flow-run`	`flowRunId`, `flowPackageId`

A node may carry more than one backing reference. An uploaded file node carries the raw artifact plus the flow-package and flow-run of the ingestion run that produced it.

Storage

Snapshots are stored with media type application/vnd.ligantic.canvas-snapshot+json. Snapshots with identical canonical content are stored once per Space, so two Canvas versions with identical canonical content share one stored snapshot.

Canvas Lifecycle and Versions

A Canvas is a named authoring surface in a Space. Each saved change to its content is kept as a version. Versions are not edited or deleted.

Canvas Reference Overview

Canvas is the admin-only, versioned authoring surface for a Space. This section documents its snapshot format, its operations, and its access rules.