# Archify JSON IR Schema Structure: A Complete Guide to Diagram Syntax

> Learn the Archify JSON IR schema structure for diagrams. Understand lanes, nodes, edges, and summaryCards validated with JSON Schema. Get the complete guide to diagram syntax.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-06

---

**The Archify JSON IR schema structure uses a typed Intermediate Representation with a mandatory `schema_version` and `diagram_type`, containing `lanes`, `nodes`, `edges`, and optional `summaryCards` that are validated against versioned JSON Schema definitions.**

Every diagram in **Archify** (`tt-a1i/archify`) compiles to a typed **JSON IR (Intermediate Representation)**—a structure that separates semantic content from visual rendering. This article breaks down the exact schema structure validated by the AJV-powered pipeline, based on the source definitions in `archify/schemas/`.

---

## Core Schema Properties Common to All Diagram Types

All diagram types extend a **shared base schema** located at [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). The top-level object requires these fields:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `schema_version` | integer | Yes | Schema version: `1` for architecture/dataflow/sequence, `2` for modern workflow diagrams |
| `diagram_type` | string | Yes | Renderer selection: `workflow`, `architecture`, `dataflow`, `sequence`, or `lifecycle` |
| `nodes` | array | Yes | Visual elements with unique IDs, placement hints, and type-specific styling |
| `lanes` | array | No | Lane containers for workflow/sequence/lifecycle diagrams |
| `edges` | array | No | Connections between nodes with routing and styling variants |
| `summaryCards` | array | No | Floating explanatory cards with positioning metadata |
| `metadata` | object | No | Tool-specific key-value pairs (generator, timestamp, etc.) |

Validation uses **AJV with JSON Schema draft-2020-12**. Failures abort rendering and report the exact JSON Pointer path.

---

## Node Schema Structure

The `nodes` array is the universal building block. Each node object supports these fields according to [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json):

- **`id`** (string, required): Unique identifier referenced by edges
- **`type`** (string, required): Visual primitive—`process`, `decision`, `messagebus`, `start`, `end`
- **`label`** (string): Primary display text
- **`sublabel`** (string): Secondary descriptive text
- **`lane`** (string): Lane assignment for lane-based diagrams
- **`row`** / **`col`** (number): Grid positioning
- **`pos`** ([number, number]): Absolute `[x, y]` coordinates for free-form placement
- **`width`** / **`height`** / **`size`** (number): Dimension overrides
- **`tag`** (string): Color-coding identifier (workflow-specific, e.g., `"structured result"`)

---

## Edge Schema Structure

Edges in the `edges` array define relationships with these properties:

- **`from`** / **`to`** (string, required): Source and target node IDs
- **`label`** (string): Optional edge annotation
- **`variant`** (string): Visual style—`emphasis`, `security`, `warning`, `muted`
- **`route`** (string): Routing algorithm hint—`straight`, `curved`, `orthogonal`
- **`fromSide`** / **`toSide`** (string): Attachment side—`top`, `right`, `bottom`, `left`

The **`security`** variant triggers special "policy-gate" visual treatment in workflow renderers.

---

## Diagram-Specific Schema Extensions

### Workflow Schema ([`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json))

Located at [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), this schema (version 2) adds lane-based layout:

- `lanes` entries require unique `id` and support `direction` (`horizontal` | `vertical`)
- `messagebus` nodes accept a `tag` field for color coding
- `edges` support the `security` variant for approval gates

### Architecture Schema ([`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json))

Defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json):

- No `lanes`; uses free-form `pos` coordinates or `row`/`col` grid
- Hierarchical relationships via optional `parent`/`children` fields
- Emphasizes spatial positioning over sequential flow

### Dataflow Schema ([`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json))

In [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json):

- Nodes typically use `type: "messagebus"` for stream semantics
- **`stage`** field (number): Denotes processing pipeline position
- Edges carry streaming semantics with partition awareness

### Sequence Schema ([`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json))

Per [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json):

- `lanes` represent participants/lifelines
- Specialized message types for sync/async communication
- Activation bars and return messages as edge variants

---

## Complete JSON IR Examples

### Workflow Diagram (Schema v2)

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "lanes": [
    { "id": "ui",        "label": "User Interface" },
    { "id": "planner",   "label": "Planner" },
    { "id": "approval",  "label": "Approval Gate" },
    { "id": "tool",      "label": "Tool Execution" }
  ],
  "nodes": [
    { "id": "request", "lane": "ui",      "col": 0, "type": "process", "label": "User Request" },
    { "id": "plan",    "lane": "planner", "col": 1, "type": "process", "label": "Plan" },
    { "id": "gate",    "lane": "approval","col": 2, "type": "decision","label": "Needs Approval?" },
    { "id": "tool",    "lane": "tool",    "col": 3, "type": "messagebus","label": "Tool Call", "tag": "structured result" }
  ],
  "edges": [
    { "from": "request", "to": "plan",    "variant": "emphasis" },
    { "from": "plan",    "to": "gate",    "variant": "emphasis" },
    { "from": "gate",    "to": "tool",    "variant": "security", "label": "approved" }
  ],
  "summaryCards": [
    {
      "title": "Approval Gate",
      "body": "Human‑in‑the‑loop checkpoint before invoking external tools.",
      "row": 1,
      "col": 2
    }
  ]
}

```

### Architecture Diagram (Schema v1)

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "nodes": [
    { "id": "frontend", "type": "process", "label": "Frontend", "pos": [100,200] },
    { "id": "api",      "type": "process", "label": "API Server", "pos": [300,200] },
    { "id": "db",       "type": "messagebus", "label": "PostgreSQL", "pos": [500,200] }
  ],
  "edges": [
    { "from": "frontend", "to": "api", "variant": "emphasis" },
    { "from": "api",      "to": "db",  "variant": "emphasis" }
  ]
}

```

### Dataflow Diagram (Schema v1)

```json
{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "nodes": [
    { "id": "orders",   "type": "messagebus", "label": "orders.v1",   "sublabel": "12 partitions", "stage": 1, "row": 0 },
    { "id": "payments", "type": "messagebus", "label": "payments.v2", "sublabel": "8 partitions",  "stage": 1, "row": 2 },
    { "id": "dlq",      "type": "messagebus", "label": "events.dlq",  "sublabel": "poison events", "stage": 3, "row": 4 }
  ],
  "edges": [
    { "from": "orders",   "to": "payments", "variant": "emphasis", "label": "OrderPlaced" },
    { "from": "payments", "to": "dlq",      "variant": "warning",  "label": "Failed" }
  ]
}

```

---

## Schema Validation Behavior

The Archify pipeline validates JSON IR at two stages:

1. **Parse-time validation**: AJV checks against the appropriate schema file in `archify/schemas/`
2. **Render-time validation**: The target diagram renderer verifies semantic constraints (e.g., all edge `from`/`to` IDs exist in `nodes`)

Validation errors include the exact **JSON Pointer path** (e.g., `/nodes/2/label`) and abort processing before SVG/PNG generation.

---

## Key Source Files

| File | Purpose |
|------|---------|
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Base schema with universal `nodes`, `edges`, `metadata` definitions |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Lane-based workflow diagrams with `schema_version: 2` |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Free-form spatial diagrams with coordinate positioning |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Streaming dataflow with `stage` and `messagebus` semantics |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Sequence diagrams with participant lifelines |
| `archify/test/fixtures/` | Example JSON IR files for regression testing |

---

## Summary

- **Archify JSON IR** uses a typed, versioned structure with mandatory `schema_version` and `diagram_type` fields
- **Common base schema** ([`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)) defines `nodes`, `edges`, `lanes`, `summaryCards`, and `metadata` available to all diagram types
- **Schema extensions** add diagram-specific fields: workflow uses `direction` and `tag`; dataflow uses `stage`; architecture uses `pos` coordinates
- **Validation** runs via AJV (draft-2020-12) with precise error reporting via JSON Pointer paths
- **Test fixtures** in `archify/test/fixtures/` provide working examples of each schema variant

---

## Frequently Asked Questions

### What is the current schema version for Archify workflow diagrams?

Workflow diagrams use `schema_version: 2` as defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json). Other diagram types (architecture, dataflow, sequence) currently use `schema_version: 1`. The version determines which renderer branch processes the IR and which validation rules apply.

### Can I mix schema versions within a single diagram file?

No. Each JSON IR document has exactly one `schema_version` at the root level. The version selects the base validation schema and renderer pipeline. To use newer workflow features, migrate the entire document to version 2.

### What happens if my JSON IR fails schema validation?

AJV validation aborts the rendering pipeline and returns an error with the exact JSON Pointer path to the offending property (e.g., `/edges/0/from` references a missing node). The CLI exits with a non-zero status and detailed validation output; no output image is generated.

### How do I add custom metadata to a diagram without breaking validation?

Include arbitrary key-value pairs in the `metadata` object at the root level. This field is defined in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) as an unconstrained object and is ignored by renderers but preserved for downstream tooling.