# What JSON IR Schema Types Does Archify Support? A Complete Guide to All 5 Diagram Formats

> Discover the 5 JSON IR schema types Archify supports: Architecture, Workflow, Sequence, Data Flow, and Lifecycle. Understand each diagram format and its validation.

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

---

**Archify supports five distinct JSON IR schema types: Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each validated by its own JSON Schema and identified by the required `diagram_type` field.**

The `tt-a1i/archify` repository ingests **JSON Intermediate Representation (IR)** and deterministically compiles it into HTML/SVG diagrams. Before rendering, Archify validates every incoming payload against a dedicated schema based on the `diagram_type` specified. Understanding these five schema types is essential for generating valid diagram instructions programmatically.

---

## Overview of the Five JSON IR Schema Types

Archify's validator selects the appropriate schema by inspecting the `diagram_type` string. Each type serves a distinct modeling purpose, from system architecture to state machines.

| Diagram Type | Schema File | Purpose |
|-------------|-------------|---------|
| **Architecture** | [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Component-based system maps with boundaries, connections, and cards |
| **Workflow** | [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | CI/CD pipelines, approval processes, and procedural flows with lanes and nodes |
| **Sequence** | [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Ordered interactions between participants with messages and activations |
| **Data Flow** | [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data movement through stages, with classification and routing rules |
| **Lifecycle** | [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | State machines including retries, waits, and terminal outcomes |

All schemas require `"schema_version": 1` and enforce type-specific constraints through JSON Schema validation.

---

## The Architecture Schema Type

The **Architecture** schema models component-based systems. It supports services, databases, external systems, and the connections between them, organized within visual boundaries.

**Key entities in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json):**
- `components` — typed elements (service, database, external, queue, cache, etc.)
- `boundaries` — visual groupings with labels and containment lists
- `connections` — directed or bidirectional links between component IDs
- `cards` — additional informational boxes overlaying the diagram

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Service Architecture" },
  "components": [
    { "id": "svc", "type": "service", "label": "Service A" },
    { "id": "db", "type": "database", "label": "Primary DB" }
  ],
  "connections": [
    { "from": "svc", "to": "db", "label": "queries" }
  ]
}

```

Common component types include `service`, `database`, `external`, `queue`, `cache`, `bucket`, `cdn`, `vpc`, `lambda`, and `user`. The schema inherits shared definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for IDs, visual presets, and styling properties.

---

## The Workflow Schema Type

The **Workflow** schema represents procedural flows using a lane-based layout. This JSON IR schema type excels at CI/CD pipelines, approval workflows, and any process with distinct phases or responsible parties.

**Key entities in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json):**
- `lanes` — horizontal swimlanes with IDs and display labels
- `nodes` — positioned elements within lanes (`col` index determines horizontal placement)
- `edges` — connections between nodes, supporting conditional routing

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI Pipeline" },
  "lanes": [
    { "id": "build", "label": "Build" },
    { "id": "test", "label": "Test" }
  ],
  "nodes": [
    { "id": "compile", "lane": "build", "col": 0, "type": "task", "label": "Compile" },
    { "id": "unit", "lane": "test", "col": 0, "type": "task", "label": "Unit Tests" }
  ],
  "edges": [
    { "from": "compile", "to": "unit", "type": "sequence" }
  ]
}

```

Node types include `task`, `decision`, `start`, `end`, `delay`, and `manual`. The column-based positioning system ensures deterministic layout without manual coordinate specification.

---

## The Sequence Schema Type

The **Sequence** schema captures ordered interactions between participants. This JSON IR schema type renders classic UML-style sequence diagrams with messages, activations, and optional segments.

**Key entities in [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json):**
- `participants` — actors, services, or systems arranged left-to-right
- `messages` — directed communications with vertical positioning (`y` coordinate)
- `activations` — execution bars showing processing duration
- `segments` — optional labeled regions grouping related interactions

```json
{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "API Call Sequence" },
  "participants": [
    { "id": "client", "type": "actor", "label": "Client" },
    { "id": "api", "type": "service", "label": "API Server" },
    { "id": "db", "type": "database", "label": "Database" }
  ],
  "messages": [
    { "from": "client", "to": "api", "y": 100, "label": "GET /resource" },
    { "from": "api", "to": "db", "y": 200, "label": "SELECT *" },
    { "from": "db", "to": "api", "y": 300, "label": "Result set" },
    { "from": "api", "to": "client", "y": 400, "label": "200 OK" }
  ]
}

```

Participant types inherit from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and include `actor`, `service`, `database`, `queue`, and `external`. The explicit `y` coordinate system provides precise control over vertical spacing while maintaining readable left-to-right flow.

---

## The Data Flow Schema Type

The **Data Flow** schema visualizes how information moves through processing stages. This JSON IR schema type supports ETL pipelines, data pipelines, and any system where data origin, transformation, and destination matter.

**Key entities in [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json):**
- `stages` — processing phases arranged left-to-right
- `nodes` — data sources, processors, and sinks positioned by stage and row
- `flows` — directed data movements with optional classification labels
- `routing` — conditional flow logic based on data properties

```json
{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "ETL Pipeline" },
  "stages": [
    { "label": "Extract" },
    { "label": "Transform" },
    { "label": "Load" }
  ],
  "nodes": [
    { "id": "src", "type": "source", "label": "Operational DB", "stage": 0, "row": 0 },
    { "id": "clean", "type": "process", "label": "Cleanse", "stage": 1, "row": 0 },
    { "id": "dst", "type": "sink", "label": "Data Warehouse", "stage": 2, "row": 0 }
  ],
  "flows": [
    { "from": "src", "to": "clean", "label": "Raw records" },
    { "from": "clean", "to": "dst", "label": "Clean records", "classification": "validated" }
  ]
}

```

Node types include `source`, `sink`, `process`, `store`, `queue`, and `api`. The stage/row positioning system creates clean pipeline visualizations without manual coordinate management.

---

## The Lifecycle Schema Type

The **Lifecycle** schema describes state machines for services, jobs, or any entity with discrete states and transitions. This JSON IR schema type renders state diagrams with support for complex transition semantics.

**Key entities in [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json):**
- `states` — named conditions with optional entry/exit behaviors
- `transitions` — directed state changes triggered by events
- `retries` — automatic re-entry logic for failed transitions
- `waits` — timed delays before transition availability
- `terminal` — final states that halt further processing

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "states": [
    { "id": "queued", "label": "Queued" },
    { "id": "running", "label": "Running", "entry": "allocate_resources" },
    { "id": "completed", "label": "Completed", "terminal": true },
    { "id": "failed", "label": "Failed", "terminal": true }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "trigger": "dequeue" },
    { "from": "running", "to": "completed", "trigger": "success" },
    { "from": "running", "to": "failed", "trigger": "error" },
    { "from": "failed", "to": "queued", "trigger": "retry", "wait": 60, "max_retries": 3 }
  ]
}

```

The lifecycle schema uniquely supports **orthogonal regions** for modeling parallel state machines and **compound states** for hierarchical decomposition.

---

## Shared Schema Infrastructure

All five JSON IR schema types reference [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) for consistent definitions:

- **ID format** — regex-constrained alphanumeric identifiers
- **Component type enum** — shared vocabulary across architecture, sequence, and data flow
- **Visual presets** — color schemes, icon references, and layout hints
- **Meta structure** — standard title, description, and authorship fields

This shared infrastructure ensures that tooling can process cross-cutting concerns—such as theming and accessibility—uniformly regardless of diagram type.

---

## Schema Validation and Selection

When Archify receives JSON IR, it performs validation in two phases:

1. **Type detection** — extracts `diagram_type` and `schema_version` from the root object
2. **Schema validation** — loads the corresponding [`.schema.json`](https://github.com/tt-a1i/archify/blob/main/.schema.json) file and validates against JSON Schema Draft 7

Validation failures include precise path references to help agents or users correct malformed IR. Valid payloads proceed to the compilation phase for deterministic HTML/SVG generation.

---

## Summary

- Archify supports **five JSON IR schema types**: Architecture, Workflow, Sequence, Data Flow, and Lifecycle
- Each type has a dedicated schema file in `archify/schemas/` and is identified by its `diagram_type` constant
- All schemas require `schema_version: 1` and share common definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)
- **Architecture** models component systems; **Workflow** handles procedural lanes and nodes
- **Sequence** captures ordered participant interactions; **Data Flow** traces information movement through stages
- **Lifecycle** represents state machines with retries, waits, and terminal conditions

---

## Frequently Asked Questions

### What happens if I omit the `diagram_type` field in my JSON IR?

Archify rejects the payload with a validation error. The `diagram_type` field is required in all schemas to determine which validator to apply. Without it, the system cannot select among [`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), or the other schema files.

### Can I combine multiple diagram types in a single JSON IR file?

No. Each JSON IR document must specify exactly one `diagram_type` and conform to its corresponding schema. For multi-diagram outputs, generate separate IR files and invoke Archify multiple times, or use the architecture schema's nested boundary approach for high-level overviews.

### Does Archify support schema versions beyond 1?

Currently all schemas enforce `"schema_version": 1`. The version field exists to enable future breaking changes. When new schema versions are introduced, Archify will maintain backward compatibility by selecting validators based on the version-determined schema path.