JSONFLOW Docs

Schema-Aware Diagrams

JSONFLOW transforms JSON into Cytoscape-ready graphs. The engine validates input, the parser prepares renderable elements, and the client renders them without a backend.

Schema

The graph schema defines nodes, edges, and layout direction. The engine defaults the graph type to flow.

{
  "type": "flow",
  "layout": { "direction": "LR" },
  "nodes": [
    { "id": "A", "label": "Start" },
    { "id": "B", "label": "Next" }
  ],
  "edges": [{ "from": "A", "to": "B", "kind": "next" }]
}

Node Shapes

Optional shape controls the node body. Supported values: ellipse, rectangle, round-rectangle, diamond, hexagon, triangle.

{
  "nodes": [
    { "id": "A", "label": "Start", "shape": "ellipse" },
    { "id": "B", "label": "Decision", "shape": "diamond" }
  ],
  "edges": [{ "from": "A", "to": "B" }]
}

Semantic Checks

The engine reports structured semantic issues and cycle metadata.

{
  "ok": true,
  "engineGraph": { "nodes": [...], "edges": [...] },
  "meta": { "isCyclic": true },
  "semantic": [
    { "type": "edge-missing-node", "missing": "X" },
    { "type": "unreachable-node", "nodeId": "C" }
  ]
}

Quickstart

1. Paste JSON in the editor.
2. Click Render.
3. Export PNG from the preview panel.

Flow Diagram

Flow is the default. Nodes are steps, edges are execution order.

{
  "type": "flow",
  "nodes": [
    { "id": "A", "label": "Start" },
    { "id": "B", "label": "Validate" },
    { "id": "C", "label": "Render" }
  ],
  "edges": [
    { "from": "A", "to": "B", "kind": "next", "link_type": "solid" },
    { "from": "B", "to": "C", "kind": "next", "link_type": "arrow" }
  ]
}

Sequence (Beta)

Sequence diagrams are renderable but still use flow layout in the client. Dedicated layout rules are planned.

Link Styles

Use link_type to control line style and arrow shape.

Layout Direction

Control orientation with layout.direction.

Engine API

The engine validates JSON with Zod, then outputs renderer-agnostic graph data. Use the adapter to map to a renderer (Cytoscape today).

import { Engine, toCytoscape } from "@andro.dev/jsonflow-engine";

const engine = new Engine();
const result = engine.parse(input);

if (result.ok) {
  const elements = toCytoscape(result.engineGraph);
}

Renderer

The client uses a renderer registry so additional renderers can be added without changing engine output.