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

> Explore Archify's JSON IR schema to understand how it defines nodes and edges for various diagram types. Learn about components, connections, and attributes.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-05

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), the node definition is implemented as:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json):

```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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/product-analytics.dataflow.json):

```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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Node and edge schema for control-flow diagrams |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Node and flow schema for data-flow diagrams |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Cross-cutting type definitions |
| [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) | Complete workflow example with nodes and edges |
| [`archify/examples/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.