# Archify Typed JSON IR Structure: A Complete Schema Reference

> Explore the Archify Typed JSON IR structure, a strictly validated schema reference for all diagram types. Understand the common core and diagram-specific properties.

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

---

**Archify uses a strictly-validated Typed JSON Intermediate Representation (IR) where all diagram types extend a common core schema defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) with diagram-specific properties.**

The Archify code generator (tt-a1i/archify) treats diagrams as structured data rather than visual markup. Every workflow, sequence, data-flow, lifecycle, and architecture diagram compiles to a **Typed JSON IR** that conforms to machine-readable JSON Schema. This enables deterministic rendering, portable outputs, and reproducible builds across environments.

---

## Core IR Definitions in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)

All diagram schemas inherit shared types from [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). These foundational definitions enforce consistency across the entire IR ecosystem.

### Primitive Types

| Property | Type / Constraints | Purpose |
|----------|------------------|---------|
| `id` | `string` matching `^[a-zA-Z][a-zA-Z0-9_-]*$` | Unique identifier referenced throughout the IR |
| `locale` | `"en"` or `"zh-CN"` | Language for rendered output |
| `animation` | `"trace"` or `"none"` | Animation behavior for diagram playback |
| `visual_preset` | `"classic"`, `"signal-flow"`, `"blueprint"`, or `"editorial"` | Predefined visual styling theme |
| `quality_profile` | `"standard"` or `"showcase"` | Output resolution and fidelity |
| `side` | `"left"`, `"right"`, `"top"`, `"bottom"` | Edge routing direction |
| `point` | `[number, number]` | 2-D coordinate for waypoints and label placement |
| `componentType` | `"frontend"`, `"backend"`, `"database"`, `"cloud"`, `"security"`, `"messagebus"`, `"external"` | Semantic category for diagram nodes |
| `brandMark` | `string` or `{url: string, sha256: string}` | Optional branding asset |
| `variant` | `"default"`, `"emphasis"`, `"security"`, `"dashed"` | Visual variation for nodes and edges |

### Nested Structures

- **`guidedViews`**: Array of view descriptors with `id`, `label`, and `focus` properties for guided presentations
- **`cards`**: Array of informational cards containing dot color, title, and items for side-panel content
- **`legendMode`**, **`legendEntry`**: Enums and objects controlling diagram legend behavior

---

## Diagram-Specific IR: Workflow Schema

The workflow diagram IR in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) extends the common core with execution-flow semantics. This is the most extensively documented schema in the Archify source.

### Top-Level Workflow Properties

| Property | Type | Description |
|----------|------|-------------|
| `schema_version` | `1` or `2` | Schema compatibility version |
| `diagram_type` | `"workflow"` (constant) | Discriminator for type routing |
| `meta` | Object with required `title` | Human-readable metadata (title, subtitle, locale) |
| `lanes` | Array of lane objects | Horizontal swim-lanes grouping nodes by `id`, `label`, optional `variant` |
| `phases` | Optional array of phase objects | Column groupings with `fromCol`, `toCol` ranges |
| `groups` | Optional array of group objects | Visual node clusters within lanes |
| `mainPath` | Array of node `id`s (minimum 2) | Primary execution sequence |
| `semanticChecks` | Optional validation rules | `allowedRoots`, `allowedTerminals`, `requiredEdges`, `requiredPaths` |
| `nodes` | Array of node objects | Core diagram elements |
| `edges` | Array of edge objects | Connections between nodes |
| `cards` | Optional array | Supplemental information (reuses common definition) |

### Workflow Node Object

```json
{
  "id": "payment-gateway",
  "lane": "backend-services",
  "col": 2,
  "type": "backend",
  "label": "Payment Gateway",
  "sublabel": "Stripe integration",
  "tag": "critical-path",
  "brand": "stripe",
  "width": 64,
  "height": 48,
  "yOffset": 12
}

```

**Required fields**: `id`, `lane`, `col`, `type`, `label`

**Optional visual overrides**: `sublabel`, `tag`, `brand` (from `brandMark`), `width` (minimum 32), `height` (minimum 32), `yOffset`

### Workflow Edge Object

```json
{
  "id": "edge-001",
  "from": "payment-gateway",
  "to": "confirmation-email",
  "label": "success",
  "variant": "emphasis",
  "role": "main",
  "fromSide": "right",
  "toSide": "left",
  "route": "auto",
  "via": [[120, 200], [180, 200]],
  "labelAt": [150, 190],
  "labelDx": 0,
  "labelDy": -8,
  "labelSegment": 1,
  "channelX": 150,
  "channelY": 200,
  "bias": 0.3,
  "width": 2.0
}

```

**Semantic `role` values**: `main`, `branch`, `async`, `return`, `error`

**Routing algorithms**: `auto`, `straight`, `drop`, `outside-right`, `return-left`, `bottom-channel`, `up-channel`

---

## Additional Diagram Type Schemas

Archify implements parallel schema structures for other diagram families, each with appropriate `diagram_type` discriminator:

| Diagram Type | Schema File | Key Specialization |
|--------------|-------------|------------------|
| Sequence | [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Lifelines, activation bars, message numbering |
| Data-flow | [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data stores, processes, external entities |
| Lifecycle | [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | State transitions, phases, milestones |
| Architecture | [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Component hierarchies, deployment boundaries |

Each schema reuses common definitions (`id`, `componentType`, `point`, `variant`) and adds type-specific fields. All enforce `additionalProperties: false` for strict validation.

---

## Minimal Valid Workflow IR Example

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "User Registration Flow"
  },
  "lanes": [
    { "id": "client", "label": "Client App" },
    { "id": "api", "label": "API Layer" },
    { "id": "db", "label": "Database" }
  ],
  "nodes": [
    { "id": "submit", "lane": "client", "col": 0, "type": "frontend", "label": "Submit Form" },
    { "id": "validate", "lane": "api", "col": 1, "type": "backend", "label": "Validate Input" },
    { "id": "create", "lane": "db", "col": 2, "type": "database", "label": "Create Record" }
  ],
  "edges": [
    {
      "from": "submit",
      "to": "validate",
      "role": "main",
      "fromSide": "right",
      "toSide": "left"
    },
    {
      "from": "validate",
      "to": "create",
      "role": "main",
      "fromSide": "right",
      "toSide": "left"
    }
  ],
  "mainPath": ["submit", "validate", "create"]
}

```

---

## Validation and Schema Strictness

According to the Archify source code, every Typed JSON IR undergoes schema validation with these characteristics:

- **`additionalProperties: false`**: Rejects unrecognized fields at any level
- **`required` arrays**: Explicitly list mandatory properties per object type
- **Pattern constraints**: `id` fields must match `^[a-zA-Z][a-zA-Z0-9_-]*$`
- **Numeric bounds**: Visual dimensions enforce minimums (e.g., `width` ≥ 32)

The `semanticChecks` object in workflow schemas enables declarative validation beyond structural correctness—specifying allowed root nodes, required terminal nodes, mandatory edges, and obligatory paths through the diagram.

---

## Source File Reference

| File | Purpose |
|------|---------|
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Shared type definitions inherited by all schemas |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Full workflow diagram specification |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Sequence diagram specification |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data-flow diagram specification |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | Lifecycle/state diagram specification |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Architecture/component diagram specification |

---

## Summary

- **Archify's Typed JSON IR** unifies all diagram types under a strict, schema-driven JSON structure
- **Common definitions** in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) provide reusable primitives: `id`, `componentType`, `point`, `variant`, `brandMark`
- **Diagram-specific schemas** extend the core with specialized fields—workflow IR adds `lanes`, `phases`, `mainPath`, and `semanticChecks`
- **Validation is strict**: `additionalProperties: false`, explicit `required` fields, and pattern constraints prevent malformed IR
- **Five diagram families** share the same structural approach: workflow, sequence, data-flow, lifecycle, and architecture

---

## Frequently Asked Questions

### What makes Archify's IR "typed"?

The "typed" designation refers to JSON Schema validation. Every IR document validates against a strict schema that defines precise types, allowed values, required fields, and constraints. This prevents runtime errors and ensures reproducible rendering across different environments and Archify versions.

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

No. Archify schemas enforce `additionalProperties: false`, which rejects any fields not explicitly defined in the schema. This strictness guarantees forward compatibility and consistent rendering. Custom data should be stored in extensible fields like `meta` or conveyed through `tag` strings where permitted.

### How does the `diagram_type` field affect processing?

The `diagram_type` constant (`"workflow"`, `"sequence"`, etc.) acts as a discriminator that routes the IR to the appropriate validator and renderer. According to the source schemas, this field is required at the top level and must match the schema file being used for validation.

### What is the difference between `lanes` and `phases` in workflow IR?

**Lanes** are vertical or horizontal groupings that organize nodes by responsible party or system component (swim-lane semantics). **Phases** are logical column ranges that span across lanes, enabling timeline or stage-based visualization. A node belongs to exactly one lane but may fall within a phase range.