# Schema Differences Between Archify's JSON IR Types and Validation Methods

> Explore Archify's five JSON IR types architecture workflow sequence lifecycle dataflow and their validation methods Learn about unique properties collections and runtime validation with Ajv

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

---

**Archify defines five distinct JSON Intermediate Representation (IR) types—architecture, workflow, sequence, lifecycle, and dataflow—each with unique required properties and type-specific collections, validated at runtime through pre-compiled Ajv validators generated from JSON Schema files in `archify/schemas/`.**

Archify is an open-source diagramming engine (tt-a1i/archify) that stores all diagrams as JSON Intermediate Representations (IR). Understanding the schema differences between Archify's JSON IR types and their validation pipeline is essential for generating valid diagram inputs and debugging schema violations.

## The Five Archify JSON IR Types

Archify supports five diagram types, each governed by its own JSON Schema file under `archify/schemas/`. While all share common definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), they diverge in their **top-level required properties** and **type-specific collections**.

### Architecture IR

The **architecture** IR represents system component diagrams and requires the most diverse set of collections beyond core components.

- **Constant `diagram_type`**: `"architecture"`
- **Required properties**: `schema_version`, `diagram_type`, `meta`, `components`
- **Type-specific collections**: `layout`, `boundaries`, `connections`, `cards`

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

### Workflow IR

The **workflow** IR models process flows using swim lanes and directed edges between nodes.

- **Constant `diagram_type`**: `"workflow"`
- **Required properties**: `schema_version`, `diagram_type`, `meta`, `lanes`, `nodes`, `edges`
- **Type-specific collections**: `phases`, `groups`, `mainPath`, `cards`

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

### Sequence IR

The **sequence** IR captures interaction sequences between participants with temporal ordering.

- **Constant `diagram_type`**: `"sequence"`
- **Required properties**: `schema_version`, `diagram_type`, `meta`, `participants`, `messages`
- **Type-specific collections**: `segments`, `activations`, `cards`

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

### Lifecycle IR

The **lifecycle** IR represents state machines with states and transitions organized in lanes.

- **Constant `diagram_type`**: `"lifecycle"`
- **Required properties**: `schema_version`, `diagram_type`, `meta`, `lanes`, `states`, `transitions`
- **Type-specific collections**: `cards` (minimal compared to other types)

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

### Dataflow IR

The **dataflow** IR tracks data movement through processing stages with nodes and directional flows.

- **Constant `diagram_type`**: `"dataflow"`
- **Required properties**: `schema_version`, `diagram_type`, `meta`, `stages`, `nodes`, `flows`
- **Type-specific collections**: `cards`

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

## Shared Schema Foundations

All five schemas reference [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) for reusable definitions. This shared file defines `$defs` for `id`, `point`, `componentType`, `variant`, `legendMode`, `legendEntry`, `guidedViews`, and `cards` that each specific schema imports via `$ref`.

Every IR type requires:
- `schema_version` — always set to `1` (enforced by a `const` constraint in each schema)
- `meta` — containing at minimum a `title`, with optional fields for `subtitle`, `output`, `animation`, `visual_preset`, `quality_profile`, `views`, `legend`, and `viewBox`

## JSON Schema Validation Workflow

Archify employs a two-phase validation strategy: **build-time compilation** and **runtime execution**.

### Validator Generation

Standalone validators are generated at build time by `scripts/generate-validators.mjs`. This script loads each schema using **Ajv 2020** with `strict: true` and emits a single ES module at `renderers/shared/generated-validators.mjs`.

```bash
npm run generate:validators

```

The generated module contains pre-compiled validator functions for all five diagram types, eliminating runtime schema compilation overhead.

### Runtime Validation

The module `renderers/shared/validator.mjs` imports these generated validators and exposes `validateSchema(diagramType, data)`. If validation fails, the module transforms Ajv errors into diagnostic objects that include:
- The JSON pointer path
- The nearest `id` or `label` for context
- A `DiagnosticError` with actionable fixes

For example, a missing required property error transforms from:

```text
/components/0/type is missing required property "type"

```

To:

```text
/components/0 (id/label: "frontend") type is missing required property "type"

```

### CLI Usage

The `archify` command provides direct access to the validation engine:

```bash

# Standard validation (exits non-zero on failure)

archify validate architecture path/to/diagram.json

# JSON output for tooling integration

archify validate workflow diagram.json --json

```

### Degraded Mode

If `ajv` is not installed, the renderer enters degraded mode: it skips schema validation but continues with layout checks, emitting a warning rather than failing. This ensures HTML generation never crashes, even with malformed input.

## Practical Validation Examples

### Minimal Architecture IR

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "My System" },
  "components": [
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Web UI",
      "row": 0,
      "col": 0
    }
  ],
  "connections": []
}

```

Validate via CLI:

```bash
archify validate architecture my-arch.json

# → exits 0 (no output)

```

### Minimal Workflow IR

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Order Flow" },
  "lanes": [{ "id": "order", "label": "Order" }],
  "nodes": [
    { "id": "receive", "lane": "order", "col": 0, "type": "frontend", "label": "Receive" }
  ],
  "edges": []
}

```

### Programmatic Validation (Node.js)

```javascript
import { validateSchema } from './archify/renderers/shared/validator.mjs';
import fs from 'node:fs';

const data = JSON.parse(fs.readFileSync('my-dataflow.json', 'utf8'));

try {
  validateSchema('dataflow', data);
  console.log('✅ dataflow IR is valid');
} catch (err) {
  console.error('❌ validation failed:', err.message);
}

```

When validation fails, the error object includes:
- `code: "schema/required"`
- `subject.path: "/components/0/type"`
- `subject.identity: "frontend"`
- `supportedFixes: ["add required property \"type\""]`

## Summary

- **Five distinct IR types**—architecture, workflow, sequence, lifecycle, and dataflow—each enforce unique required properties and type-specific collections.
- **Shared foundations** in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) provide reusable definitions for identifiers, points, and component types across all schemas.
- **Build-time generation** via `scripts/generate-validators.mjs` pre-compiles Ajv validators for runtime performance.
- **Diagnostic errors** in `renderers/shared/validator.mjs` annotate validation failures with JSON pointers and nearest identifiers for rapid debugging.
- **CLI and programmatic APIs** support both manual validation and automated tooling integration.
- **Degraded mode** ensures rendering resilience when validation dependencies are unavailable.

## Frequently Asked Questions

### What differentiates Architecture IR from Workflow IR in Archify's JSON schemas?

**Architecture IR** focuses on static system structure with `components`, `connections`, and `boundaries`, while **Workflow IR** models dynamic processes using `lanes`, `nodes`, and `edges` with additional collections like `phases` and `mainPath`. The Architecture schema requires only `components` at minimum, whereas Workflow requires `lanes`, `nodes`, and `edges` simultaneously.

### How does Archify validate diagrams if Ajv is not installed?

According to the source code in `renderers/shared/validator.mjs`, when `ajv` is unavailable the system enters **degraded mode**: it skips schema validation but continues with layout calculations, emitting a console warning instead of throwing a `DiagnosticError`. This ensures the renderer always produces output even with potentially invalid input.

### Can I validate Archify IR files programmatically without using the CLI?

Yes. Import `validateSchema` from `archify/renderers/shared/validator.mjs` and call it with the diagram type string and parsed JSON data. The function throws a `DiagnosticError` on first schema violation or returns silently on success, making it suitable for integration testing and build pipelines.

### What is the role of [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) in Archify's validation system?

[`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) serves as the shared vocabulary for all IR types, defining `$defs` for reusable concepts like `id`, `point`, `componentType`, and `legendEntry`. All specific schemas (architecture, workflow, etc.) reference these definitions using `$ref`, ensuring consistent data types and validation rules across the entire JSON IR ecosystem.