@miragon/value-chain-schema-model

The DOM-free core of the Value Chain Modeler: types, Zod validation, migrations and deterministic JSON serialization for value chain diagrams (ARIS-style Wertschöpfungskettendiagramme, *.vc / *.vc.json).

Plain TypeScript with no diagram-js and no DOM, so it runs in the browser, in Node and in CLIs. The browser renderer @miragon/value-chain-renderer, the web app and the VS Code extension all build on it.

Install

npm install @miragon/value-chain-schema-model

Ships ESM and CommonJS builds with type declarations. zod (^4.6.0) is a peer dependency, so the package validates with your app's copy of Zod instead of bringing a second one.

Usage

import { readFile } from 'node:fs/promises';
import {
  createEmptyDocument,
  parseDocumentJSON,
  serializeDocument,
} from '@miragon/value-chain-schema-model';

const doc = parseDocumentJSON(await readFile('landscape.vc.json', 'utf8')); // migrate + validate
const json = serializeDocument(doc); // stable output for clean Git diffs

const empty = createEmptyDocument('My value chain');

| Export | Purpose | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | loadDocument(data) / parseDocumentJSON(s) | Migrate older documents to CURRENT_SCHEMA_VERSION, then validate. Use these for any external input. | | validateDocument(data) | Zod schema plus invariants: unique ids, reserved ids, resolvable endpoints, the relation/element-type matrix. | | documentIssues(data) | The same checks as a list of findings, each with its JSON path, for editors that point at the broken spot. | | connectionAllowed(type, source, target) | The relation matrix: sequence/hierarchy link steps, assignment links an org unit with a step. | | serializeDocument(doc) | Deterministic JSON: elements and connections sorted by id, keys deep-sorted, numbers rounded to 3 decimals. | | createEmptyDocument(name?) | A valid, empty document. | | documentExtensions(doc) and its siblings | The fields a document, its meta, an element or a connection carries beyond the schema (kept, see below). | | valueChainDocumentSchema & element schemas | The raw Zod schemas. | | ValueChainDocument, DiagramElement, … | TypeScript types of the persisted format. |

Document format

{
  "schemaVersion": 1,
  "meta": { "name": "Porter Value Chain" },
  "elements": [
    {
      "id": "step-operations",
      "elementType": "step", // chevron
      "name": "Operations",
      "bounds": { "x": 280, "y": 124, "width": 160, "height": 60 },
    },
    {
      "id": "org-production",
      "elementType": "orgUnit", // ellipse
      "name": "Production",
      "bounds": { "x": 295, "y": 230, "width": 130, "height": 60 },
    },
  ],
  "connections": [
    {
      "id": "assign-1",
      "connectionType": "assignment", // or "sequence" | "hierarchy"
      "source": "step-operations",
      "target": "org-production",
      "waypoints": [
        { "x": 360, "y": 184 },
        { "x": 360, "y": 230 },
      ],
    },
  ],
}

Unknown keys on the document, meta, elements and connections are kept through load and serialization (sorted, values unrounded), so vendor extensions survive an edit in the tools. bounds and waypoints reject unknown keys, an unknown elementType or connectionType is invalid, the ids vc-root, __implicitroot… and the names of built-in JavaScript object properties (constructor, toString, …) are reserved, coordinates and sizes stay within ±1e9 (COORDINATE_LIMIT), and objects and arrays nest at most 100 levels (MAX_NESTING_DEPTH).

A complete example lives in example/porter.vc.json.

License

MIT