Workflow JSON

Linkage workflows serialize into a canonical, versioned JSON format so host apps can persist and move workflows between environments without losing meaning.

v1 shape

type WorkflowJsonV1 = {
  schemaVersion: "1";
  nodesById: Record<string, Node>;
  edgesById: Record<string, Edge>;
  viewport?: {
    x: number;
    y: number;
    zoom: number;
  };
};

Canonicalization rules

• Nodes and edges are normalized by id before being written into nodesById / edgesById.
• UI-only fields are stripped:
  • node: selected, dragging, data.markedForDeletion
  • edge: selected, data.markedForDeletion
• Optional keys are omitted when empty/undefined.
• exportWorkflowJsonString uses stable key sorting so equivalent graphs produce identical JSON bytes.

Public API

import {
  WORKFLOW_SCHEMA_VERSION,
  WORKFLOW_JSON_SCHEMA,
  exportWorkflowJson,
  exportWorkflowJsonString,
  importWorkflowJson,
  importWorkflowJsonString,
} from "@linkage-open/lib";

Import/export example

const snapshot = exportWorkflowJson({
  nodes,
  edges,
  viewport,
});

const serialized = exportWorkflowJsonString({
  nodes,
  edges,
  viewport,
});

const restored = importWorkflowJsonString(serialized);
// restored.schemaVersion === "1"
// restored.nodesById / restored.edgesById are canonicalized

Versioning and migrations

• schemaVersion is required for v1 payloads.
• Missing schemaVersion is treated as legacy v0 payload.
• v0 payloads are migrated to v1 through a pure migration pipeline.
• Unsupported versions throw an error during import.

Legacy v0 compatibility currently supports:

• { nodes: Node[], edges: Edge[] }
• { nodesById: Record<string, Node>, edgesById: Record<string, Edge> } without schemaVersion