# Archify JSON Intermediate Representation (IR) Schema Structure Explained

> Understand Archify's JSON Intermediate Representation IR schema structure. Learn how this portable JSON format defines architecture, workflow, sequence, dataflow, and lifecycle diagrams.

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

---

**Archify's JSON Intermediate Representation (IR) is a strictly validated, schema-driven format that defines architecture, workflow, sequence, dataflow, and lifecycle diagrams as portable JSON documents.**

The JSON IR schema serves as the core contract between diagram authors and Archify's rendering engine. Every diagram type follows a rigorous JSON Schema specification stored in `archify/schemas/`, ensuring type safety, validation, and interoperability across tools.

## Core JSON IR Schema Structure

### Top-Level Properties

All diagram IR documents share a common envelope structure defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) and sibling schema files:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `schema_version` | `integer` | Yes | Fixed value `1` for forward compatibility |
| `diagram_type` | `string` | Yes | One of: `"architecture"`, `"workflow"`, `"sequence"`, `"dataflow"`, `"lifecycle"` |
| `meta` | `object` | Yes | Metadata including title, subtitle, visual preset, and output configuration |
| `layout` | `object` | No | Grid or free-form positioning parameters |
| `components` / `nodes` | `array` | Varies | Diagram elements (terms differ by diagram type) |
| `boundaries` | `array` | No | Logical groupings that wrap component sets |
| `connections` / `edges` | `array` | No | Directed relationships between elements |
| `cards` | `array` | No | Supplementary annotations and legends |

All top-level objects enforce `additionalProperties: false`, making validation failures explicit and catching typos immediately.

## Architecture Diagram IR Schema

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) file defines the most widely used IR format. Located at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), it structures diagrams as interconnected components within optional boundaries.

### Components Array

Each element in `components` must satisfy:

```json
{
  "id": "api-gateway",
  "type": "backend",
  "label": "API Gateway",
  "sublabel": "Nginx",
  "tag": "v2.1",
  "row": 0,
  "col": 1,
  "source_url": "https://github.com/org/repo",
  "source_path": "/src/gateway"
}

```

**Component `type` values** are drawn from the shared enum in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json):

- `frontend`
- `backend`
- `database`
- `cloud`
- `security`
- `messagebus`
- `external`

### Boundaries for Logical Grouping

Boundaries wrap component references to create security groups or architectural layers:

```json
{
  "boundaries": [
    {
      "kind": "security_group",
      "label": "DMZ",
      "wraps": ["api-gateway", "load-balancer"],
      "padding": 20
    }
  ]
}

```

### Connections with Routing Control

The `connections` array supports automatic and manual routing:

```json
{
  "from": "api-gateway",
  "to": "user-service",
  "variant": "emphasis",
  "route": "orthogonal",
  "via": [[200, 100], [400, 100]],
  "width": 2,
  "label": "HTTPS",
  "labelDx": 10,
  "labelDy": -5
}

```

**Routing options** include `"auto"`, `"direct"`, `"orthogonal"`, and `"curved"`. The `via` property accepts an array of `[x, y]` points for precise path control.

## Shared Definitions in common.schema.json

The [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) file provides reusable schema fragments referenced by all diagram types:

### Identifiers and Coordinates

- **`id`**: Regex pattern `^[a-zA-Z][a-zA-Z0-9_-]*$` for valid object identifiers
- **`point`**: Two-element numeric array `[x, y]` for positioning
- **`size`**: Object with `width` and `height` integers

### Visual Styling Enums

The `variant` enum controls visual emphasis:

- `default` — standard appearance
- `emphasis` — highlighted (thicker borders, contrasting fill)
- `security` — specialized styling for security components
- `dashed` — indirect or optional relationships

### Legends and Guided Views

```json
{
  "legend": {
    "mode": "compact",
    "entries": [
      { "label": "External API", "type": "external" }
    ]
  },
  "guided_views": [
    {
      "id": "auth-flow",
      "label": "Authentication Flow",
      "center": [300, 200],
      "zoom": 1.5
    }
  ]
}

```

## Workflow and Specialized Diagram IRs

### Workflow IR Schema

Defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), workflow diagrams introduce lane-based layouts:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI/CD Pipeline" },
  "lanes": [
    { "id": "dev", "label": "Development" },
    { "id": "staging", "label": "Staging" },
    { "id": "prod", "label": "Production" }
  ],
  "phases": [
    { "id": "build", "label": "Build" },
    { "id": "test", "label": "Test" },
    { "id": "deploy", "label": "Deploy" }
  ],
  "nodes": [
    {
      "id": "compile",
      "lane": "dev",
      "col": 0,
      "type": "backend",
      "label": "Compile"
    }
  ],
  "edges": [
    {
      "from": "compile",
      "to": "unit-test",
      "role": "main"
    }
  ]
}

```

**Workflow-specific properties**:

- `lanes` — horizontal swimlanes for organizational grouping
- `phases` — vertical divisions for process stages
- `groups` — nested containment for complex workflows
- `nodes` — equivalent to `components` in architecture IR
- `edges` — equivalent to `connections`, with added `role` property

### Sequence, Dataflow, and Lifecycle IRs

Each specialized diagram type has its own schema file following the same architectural pattern:

- [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) — step-by-step interactions with `steps` array
- [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) — data transformation pipelines with `stages`
- [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) — state transitions with `states` and `transitions`

All reference [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for identifiers, points, and component types.

## Complete Architecture IR Example

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "E-Commerce Platform",
    "subtitle": "Reference Architecture",
    "visual_preset": "modern",
    "quality_profile": "high",
    "output_filename": "ecommerce-platform"
  },
  "layout": {
    "mode": "grid",
    "origin": [0, 0],
    "columns": 3,
    "gaps": [40, 60]
  },
  "components": [
    {
      "id": "cdn",
      "type": "cloud",
      "label": "CloudFront",
      "row": 0,
      "col": 0
    },
    {
      "id": "web",
      "type": "frontend",
      "label": "Next.js App",
      "row": 0,
      "col": 1,
      "sublabel": "SSR"
    },
    {
      "id": "api",
      "type": "backend",
      "label": "GraphQL API",
      "row": 0,
      "col": 2
    },
    {
      "id": "cache",
      "type": "database",
      "label": "Redis",
      "row": 1,
      "col": 2,
      "tag": "cluster"
    },
    {
      "id": "postgres",
      "type": "database",
      "label": "PostgreSQL",
      "row": 2,
      "col": 2
    }
  ],
  "boundaries": [
    {
      "kind": "security_group",
      "label": "Private Subnet",
      "wraps": ["cache", "postgres"],
      "padding": 30
    }
  ],
  "connections": [
    {
      "from": "cdn",
      "to": "web",
      "variant": "default",
      "route": "auto"
    },
    {
      "from": "web",
      "to": "api",
      "variant": "default",
      "route": "orthogonal"
    },
    {
      "from": "api",
      "to": "cache",
      "variant": "default",
      "route": "auto",
      "label": "session"
    },
    {
      "from": "api",
      "to": "postgres",
      "variant": "emphasis",
      "route": "auto",
      "label": "persistent"
    }
  ],
  "cards": [
    {
      "position": "top-right",
      "title": "Notes",
      "content": "Redis used for session store only"
    }
  ]
}

```

## Validation and Tooling

The JSON IR schemas enable rigorous validation using standard JSON Schema validators like AJV. Key validation characteristics:

- **Strict mode**: `additionalProperties: false` on all objects
- **Required fields**: Enforced per diagram type and context
- **Type coercion**: Rejected — strings must be strings, numbers must be numbers
- **Enum validation**: Component types, variants, and routing modes checked against shared definitions

Validate an IR file against its schema:

```bash
ajv validate -s archify/schemas/architecture.schema.json -d diagram.architecture.json

```

## Summary

- **JSON IR is schema-validated**: Every diagram type has a strict JSON Schema in `archify/schemas/`
- **Shared definitions ensure consistency**: [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) provides single-source identifiers, points, and enums
- **Architecture IR uses components and connections**: Grid-based layout with optional boundaries
- **Workflow IR adds lanes and phases**: Swimlane layout for process visualization
- **All IRs are portable and tool-agnostic**: JSON format enables programmatic generation and third-party rendering

## Frequently Asked Questions

### What diagram types does Archify's JSON IR support?

Archify supports five diagram types, each with its own schema: **architecture**, **workflow**, **sequence**, **dataflow**, and **lifecycle**. The `diagram_type` field in each IR document identifies which schema governs validation.

### Where are the JSON Schema files located?

All schemas reside in the `archify/schemas/` directory. The core files are [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), and [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json). Additional schemas for sequence, dataflow, and lifecycle diagrams follow the same naming convention.

### Can I extend the JSON IR with custom properties?

No — all schemas enforce `additionalProperties: false` to ensure strict validation. Custom data should be stored in the `meta` object's predefined fields or in `cards` annotations. This design guarantees that all valid IR documents render correctly across Archify versions.

### How do I validate my JSON IR against the schema?

Use any JSON Schema validator such as AJV, or Archify's built-in validation. The schemas follow JSON Schema Draft 7 and can be invoked programmatically or via command-line tools to catch structural errors before rendering.