How Archify's JSON IR Schema Defines Nodes and Edges for Different Diagram Types

Archify uses a JSON-based intermediate representation (IR) where nodes represent visual components positioned in lanes and columns, while edges (or flows) define directed connections with routing, styling, and semantic role attributes.

The open-source Archify repository structures diagram definitions through JSON Schema files that enforce consistent node and edge shapes across workflow and data-flow diagram types. These schemas enable the rendering engine to parse diagram files interchangeably while preserving type-specific semantics.

Core IR Structure: Nodes

Nodes in Archify's IR define the visual elements that appear on diagrams—services, databases, frontends, or custom components. Every node follows the same foundation regardless of diagram type.

Required Node Fields

Field	Type	Description
id	string	Unique identifier referenced by edges/flows
lane	string	Horizontal swimlane placement
col	integer	Column index within the lane
type	string	Component classification from common.schema.json
label	string	Display text for the node

Optional Node Fields

Field	Purpose
sublabel	Secondary descriptive text
tag	Categorization marker
width, height	Explicit dimensions in pixels
yOffset	Vertical adjustment from default position

In archify/schemas/workflow.schema.json, the node definition is implemented as:

{
  "type": "object",
  "properties": {
    "id": { "$ref": "common.schema.json#/$defs/id" },
    "lane": { "$ref": "common.schema.json#/$defs/laneId" },
    "col": { "type": "integer", "minimum": 0 },
    "type": { "$ref": "common.schema.json#/$defs/componentType" },
    "label": { "type": "string" },
    "sublabel": { "type": ["string", "null"] },
    "tag": { "type": ["string", "null"] },
    "width": { "type": "number" },
    "height": { "type": "number" },
    "yOffset": { "type": "number", "default": 0 }
  },
  "required": ["id", "lane", "col", "type", "label"]
}

The dataflow.schema.json reuses this exact node structure through schema composition, ensuring visual consistency across diagram types.

Workflow Diagrams: Edges

Workflow diagrams use edges to model control flow—function calls, returns, error paths, and asynchronous operations. The edge schema in archify/schemas/workflow.schema.json provides extensive routing and styling control.

Edge Field Reference

Field	Required	Description
from, to	Yes	Source and target node IDs
id	No	Optional edge identifier
label	No	Connection label text
variant	No	Style variant reference
role	No	Semantic purpose: main, branch, async, return, error, timeout
fromSide, toSide	No	Attachment points: auto, top, bottom, left, right
route	No	Path algorithm: auto, straight, drop, outside-right, outside-left
via	No	Array of intermediate points
labelAt, labelDx, labelDy, labelSegment	No	Label positioning
channelX, channelY, bias	No	Routing channel constraints
width	No	Edge stroke width

Example workflow edge from archify/examples/agent-tool-call.workflow.json:

{
  "edges": [
    {
      "from": "agent",
      "to": "tool-call",
      "role": "main",
      "route": "straight",
      "fromSide": "right",
      "toSide": "left"
    },
    {
      "from": "tool-call",
      "to": "agent",
      "role": "return",
      "route": "outside-right",
      "label": "result"
    }
  ]
}

Data-Flow Diagrams: Flows

Data-flow diagrams substitute flows for edges, modeling data movement rather than control transfer. The archify/schemas/dataflow.schema.json file mirrors the edge schema exactly but renames the relationship property to align with data-processing semantics.

The structural equivalence means:

• Node definitions are identical to workflow diagrams
• Flow fields match edge fields one-to-one, including role values (main, branch, etc.)
• Routing and styling use the same coordinate system and algorithms

From archify/examples/product-analytics.dataflow.json:

{
  "flows": [
    {
      "from": "events-stream",
      "to": "analytics-db",
      "role": "main",
      "route": "auto",
      "label": "event batch"
    },
    {
      "from": "analytics-db",
      "to": "report-service",
      "role": "branch",
      "route": "drop"
    }
  ]
}

Shared Schema Foundations

Both diagram types inherit common definitions from archify/schemas/common.schema.json:

Definition	Purpose
$defs/id	URI-safe identifier pattern
$defs/laneId	Lane reference format
$defs/componentType	Enum of built-in component types
$defs/point	{ x, y } coordinate objects
$defs/legendEntry	Color and line-style legend items

This shared foundation ensures that custom tooling can parse any Archify IR file with consistent validation logic.

Source File Locations

File	Responsibility
archify/schemas/workflow.schema.json	Node and edge schema for control-flow diagrams
archify/schemas/dataflow.schema.json	Node and flow schema for data-flow diagrams
archify/schemas/common.schema.json	Cross-cutting type definitions
archify/examples/agent-tool-call.workflow.json	Complete workflow example with nodes and edges
archify/examples/product-analytics.dataflow.json	Complete data-flow example with nodes and flows

Summary

• Nodes in Archify's JSON IR require id, lane, col, type, and label, with optional positioning and sizing fields
• Workflow edges use the edges array with control-flow semantics and extensive routing configuration
• Data-flow connections use the flows array with identical structure but data-movement semantics
• Both diagram types share common.schema.json definitions for identifiers, types, and coordinates
• The role field distinguishes connection purpose: main, branch, async, return, error, or timeout

Frequently Asked Questions

What is the difference between edges and flows in Archify's JSON IR?

Edges and flows have identical field structures but serve different diagram types. Edges appear in workflow diagrams to model control flow between operations. Flows appear in data-flow diagrams to model data movement between processing stages. The distinction allows the same rendering engine to apply appropriate visual semantics while parsing both structures uniformly.

Can a node have multiple roles in different edges?

Yes. A node's role is not a property of the node itself but of each edge or flow connecting to it. In archify/examples/agent-tool-call.workflow.json, the agent node participates in a main edge (outgoing call) and a return edge (incoming result), demonstrating how role varies per connection.

How does Archify handle edge routing between diagram types?

Both edges and flows support the same route enum values: auto, straight, drop, outside-right, and outside-left. The renderer applies identical path-finding algorithms regardless of whether the connection is labeled an edge or flow. The via array in either type allows explicit intermediate points for complex routing.

Where are component types defined for node validation?

Component types are defined in archify/schemas/common.schema.json under $defs/componentType. This central definition ensures that workflow nodes, data-flow nodes, and future diagram types reference a consistent, extensible taxonomy of visual element categories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}