# Schema Definitions That Govern IR for Each Archify Diagram Type

> Discover how Archify uses dedicated JSON Schema files to validate diagram Internal Representation (IR), ensuring type-specific constraints and consistent component typing across all formats.

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

---

**Archify validates every diagram's Internal Representation (IR) against a dedicated JSON Schema file that enforces type-specific structural constraints while inheriting common definitions for consistent component typing across all formats.**

The `tt-a1i/archify` repository stores all diagrams as JSON IR that must pass strict schema validation before rendering. Understanding what schema definitions govern IR for each Archify diagram type is essential for programmatic diagram generation and custom tooling. Each supported format—from architecture to lifecycle—maintains its own schema file in `archify/schemas/`, all extending a shared foundation defined in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json).

## Architecture Diagram Schema

The **architecture diagram** IR uses [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) to validate grid-based component layouts.

Root requirements include:

- `schema_version`
- `diagram_type = "architecture"`
- `meta` (title, visual preset, viewBox, legend)
- `components`

Each component object requires an `id` and a `type` field chosen from the enum: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, or `external`. Positioning data uses either `row`/`col` grid coordinates or absolute `pos`/`size` values.

## Workflow Diagram Schema

Workflow diagrams implement swim-lane visualization through [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json).

Required top-level properties:

- `schema_version`
- `diagram_type = "workflow"`
- `meta`
- `lanes` (vertical swim-lanes with `id` and `label`)
- `nodes` (placed within lanes)
- `edges` (connections between nodes)

Nodes specify their lane placement via `lane` and `col` fields, while edges support visual variants including `default`, `emphasis`, `security`, and `dashed`.

## Sequence Diagram Schema

Sequence diagrams validate participant interactions through [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json).

The schema mandates:

- `schema_version`
- `diagram_type = "sequence"`
- `meta`
- `participants` (objects with `id`, `type`, and `label`)
- `messages` (interaction lines)

Messages connect participant IDs through `from` and `to` fields positioned at a vertical `y` coordinate. Visual variants extend beyond workflow options to include `return` lines for reply messages.

## Dataflow Diagram Schema

Pure data-pipeline diagrams conform to [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json), which mirrors workflow structure but optimizes for data movement semantics.

Required fields:

- `schema_version`
- `diagram_type = "dataflow"`
- `meta`
- `components` (using standard component types)
- `connections`

Connections support explicit routing strategies via the `routing` property, accepting values of `auto`, `straight`, or `orthogonal-h/v`.

## Lifecycle Diagram Schema

State-machine and lifecycle diagrams use [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) to validate stage progression.

Root requirements include:

- `schema_version`
- `diagram_type = "lifecycle"`
- `meta`
- `stages`
- `transitions`

Stages define their semantic role through a `type` enum: `start`, `active`, `success`, or `error`. Transitions connect stage IDs and may include a `variant` property for visual emphasis.

## Common Schema Foundation

All diagram-specific schemas reference [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) through JSON Schema `$ref` pointers. This shared foundation provides reusable `$defs` for:

- **`id`** format validation
- **`componentType`** enum (frontend, backend, database, cloud, security, messagebus, external)
- **Legend entries**
- **Guided views**
- **Point coordinates**

By centralizing these definitions, Archify guarantees that component type strings, identifier formats, and legend structures remain consistent across architecture, workflow, sequence, dataflow, and lifecycle diagrams.

## Validating IR Against Schemas

Archify uses the AJV validator to enforce schema compliance at runtime. Below is a practical implementation pattern for validating different diagram types:

```javascript
import Ajv from "ajv";
import architectureSchema from "./archify/schemas/architecture.schema.json";
import workflowSchema from "./archify/schemas/workflow.schema.json";
import sequenceSchema from "./archify/schemas/sequence.schema.json";
import dataflowSchema from "./archify/schemas/dataflow.schema.json";
import lifecycleSchema from "./archify/schemas/lifecycle.schema.json";

const ajv = new Ajv({ allErrors: true });

const validators = {
  architecture: ajv.compile(architectureSchema),
  workflow: ajv.compile(workflowSchema),
  sequence: ajv.compile(sequenceSchema),
  dataflow: ajv.compile(dataflowSchema),
  lifecycle: ajv.compile(lifecycleSchema)
};

function validateDiagram(ir, type) {
  const validate = validators[type];
  if (!validate(ir)) {
    console.error(`${type} IR validation errors:`, validate.errors);
    return false;
  }
  return true;
}

// Usage example
const archIR = {
  schema_version: "1.0",
  diagram_type: "architecture",
  meta: { title: "System Overview" },
  components: []
};

if (validateDiagram(archIR, "architecture")) {
  console.log("IR is valid and ready for rendering");
}

```

Each validator checks the incoming JSON against its corresponding schema in `archify/schemas/`, ensuring that required fields exist, component types match the allowed enum values, and structural relationships like lane assignments or stage transitions follow the defined constraints.

## Summary

- **Five dedicated schemas** govern IR for Archify's diagram types: [`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), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json), and [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json).
- **Common foundation** at [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) provides shared `$defs` for IDs, component types, and legends, ensuring consistency across all formats.
- **Strict validation** requires root fields including `schema_version`, `diagram_type`, and type-specific collections like `components`, `lanes`, `participants`, or `stages`.
- **Component type enum** remains identical across schemas, supporting frontend, backend, database, cloud, security, messagebus, and external classifications.
- **AJV compilation** is used at runtime to validate IR before rendering, as implemented in the `tt-a1i/archify` source code.

## Frequently Asked Questions

### What file path contains the schema for Archify architecture diagrams?

The architecture diagram schema resides at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) in the repository root. This file defines the required `components` array structure and the positioning schema for grid-based layouts using either row/column coordinates or absolute positioning.

### How does Archify ensure consistent component typing across different diagram formats?

All diagram schemas reference [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) via JSON Schema `$ref` pointers. This shared schema defines the `componentType` enum and ID formats that every diagram type must use, ensuring that terms like `backend` or `database` have identical meaning in architecture, workflow, and sequence diagrams.

### Can I validate an Archify IR file programmatically without using the Archify application?

Yes. You can import the raw JSON Schema files from `archify/schemas/` and compile them using any JSON Schema validator like AJV. Instantiate the validator with the specific diagram type schema, then call the compiled validation function against your IR object to receive detailed error messages if the structure violates the schema constraints.

### What distinguishes the workflow schema from the dataflow schema in Archify?

While both use nodes and connections, [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) emphasizes swim-lane visualization with `lanes`, `nodes`, and `edges` properties, whereas [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) focuses on pipeline semantics with `components` and `connections` that support explicit routing algorithms like `orthogonal-h/v`. The dataflow schema omits lane-based positioning in favor of connection routing strategies.