# How JSON IR Schemas Validate Diagram Structure in Archify: A Complete Technical Guide

> Learn how Archify uses JSON IR schemas and AJV to rigorously validate diagram structure, ensuring type constraints and required fields are met before rendering. A technical deep-dive.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-08

---

**Archify enforces strict structural validation on every diagram by running JSON Intermediate Representation (IR) through JSON Schema draft 2020-12 using AJV, rejecting any input that violates type constraints or missing required fields before rendering begins.**

Archify converts architecture, workflow, sequence, and lifecycle diagrams into JSON Intermediate Representation (IR) documents before visualization. The system validates these payloads against specialized JSON IR schemas to ensure type safety and structural integrity, acting as a fail-closed gatekeeper that prevents malformed data from reaching the rendering pipeline. This schema-first approach guarantees consistent diagram output across all supported diagram types in the `tt-a1i/archify` repository.

## The Validation Pipeline

Archify’s validation process follows a strict sequence that checks every layer of the diagram IR. The system uses **AJV** (Another JSON Validator) to compile schemas and validate incoming JSON against the specific diagram type being processed.

### Schema Selection by Diagram Type

Every diagram must declare its structure upfront in the root object. The schema requires four mandatory fields: `schema_version`, `diagram_type`, `meta`, and a type-specific payload such as `components` or `connections`. All schemas set `additionalProperties: false` to strictly forbid extraneous fields.

In [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the root object enforces `schema_version` locked to integer `1` and `diagram_type` restricted to specific enum values like `"architecture"` or `"workflow"`. This guarantees that the validator loads the correct schema file for the specific diagram variant being processed.

### Shared Definitions via $ref

Common primitives are defined once in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) and referenced across all diagram schemas using JSON Schema’s `$ref` keyword. This centralizes definitions for:

- **`id`**: String identifiers for components and connections
- **`point`**: Coordinate arrays for positioning
- **`componentType`**: Enumerated node types (frontend, backend, database, etc.)
- **`legendEntry`** and **`guidedViews`**: UI metadata structures

By referencing these shared definitions, Archify maintains a single source of truth for validation rules while keeping individual schema files focused on diagram-specific logic.

## Structural Validation Layers

Each schema validates distinct aspects of the diagram IR, from high-level metadata to low-level connection geometry.

### Metadata and View Configuration

The `meta` block (defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) lines 12-66) validates optional presentation fields including `title`, `subtitle`, `output` format, `animation` settings, `quality` profiles, and `viewBox` dimensions. This ensures that renderers receive consistent configuration objects regardless of the diagram source.

### Components, Nodes, and Layouts

Architecture diagrams validate `components` arrays (lines 82-125 in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)) requiring each element to contain `id`, `type` (from the `componentType` enum), and `label`. Optional positioning fields like `row`, `col`, `pos`, and `size` are strictly type-checked against the shared `point` definition.

Workflow diagrams use similar constraints in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 19-68), validating `nodes` arrays with `lane` assignments and grid coordinates. Layout objects enforce numeric constraints for `origin`, `cols`, `gapX`, `gapY`, `cellW`, and `cellH`, ensuring grid-based diagrams calculate correct cell boundaries.

### Connections and Edge Integrity

Every relationship must reference valid endpoints. In [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) (lines 145-171), the `connections` array requires `from` and `to` properties that must match existing component IDs. Optional routing fields like `variant`, `fromSide`, `toSide`, and `via` are validated against enumerated values or the shared `point` array definition.

Workflow schemas implement similar validation for `edges` (lines 70-108 in [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)), checking that `from` and `to` reference valid node IDs within the same diagram context.

## Validating Diagrams with AJV

Archify implements validation using AJV in Node.js environments. The validator loads the base schema and any referenced common definitions before testing the JSON IR.

```javascript
import Ajv from "ajv";
import architectureSchema from "./archify/schemas/architecture.schema.json";
import commonSchema from "./archify/schemas/common.schema.json";

const ajv = new Ajv({ allErrors: true });
ajv.addSchema(commonSchema, "common");
const validate = ajv.compile(architectureSchema);

const diagramData = {
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Demo Architecture" },
  "layout": { "mode": "grid", "cols": 4, "gapX": 10, "gapY": 10, "cellW": 80, "cellH": 30 },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Web UI", "row": 0, "col": 0 },
    { "id": "backend", "type": "backend", "label": "API", "row": 0, "col": 1 }
  ],
  "connections": [
    { "from": "frontend", "to": "backend", "variant": "default" }
  ]
};

const valid = validate(diagramData);
if (!valid) {
  console.error(validate.errors);
} else {
  console.log("Diagram structure validated successfully");
}

```

For workflow diagrams, substitute [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) and adjust the payload structure:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Order Processing" },
  "lanes": [{ "id": "lane1", "label": "Customer" }],
  "nodes": [
    { "id": "n1", "lane": "lane1", "col": 0, "type": "frontend", "label": "Checkout" }
  ],
  "edges": [
    { "from": "n1", "to": "n1", "role": "main", "variant": "default" }
  ]
}

```

## Schema File Reference

Archify organizes validation logic into discrete schema files within the `archify/schemas/` directory:

- **[`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json)**: Centralizes shared type definitions including identifiers, coordinate points, enumerations, and card structures referenced via `$ref` across all diagram types.

- **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)**: Defines validation for system architecture diagrams including component grids, connection routing, and boundary enclosures.

- **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)**: Validates swimlane-based workflow diagrams with node positioning and edge routing constraints.

- **[`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)**: Enforces message sequence diagrams with lifelines and activation boxes.

- **[`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)**: Validates state transition diagrams and lifecycle flows.

- **[`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)**: Defines schemas for data pipeline and ETL process visualizations.

## Summary

- **JSON IR schemas** in Archify use JSON Schema draft 2020-12 to enforce strict type checking on diagram structures before rendering.
- **AJV validation** runs as a fail-closed gatekeeper, rejecting any diagram with missing required fields, type mismatches, or undefined component references.
- **Shared definitions** in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) eliminate duplication by centralizing primitives like IDs, points, and enums across all diagram-specific schemas.
- **Structural constraints** ensure that `components`, `connections`, `nodes`, and `edges` maintain referential integrity and valid geometric properties.
- **Schema versioning** via `schema_version` and `diagram_type` fields enables Archify to evolve its IR format while maintaining backward compatibility validation.

## Frequently Asked Questions

### What JSON Schema version does Archify use?

Archify implements JSON Schema draft 2020-12 for all IR validation. This modern specification supports advanced features like `$ref` dereferencing and strict type checking required for the complex nested structures in architecture and workflow diagrams.

### How does Archify handle invalid diagram JSON?

When AJV detects validation errors, Archify immediately halts processing and returns a detailed error list specifying which fields failed constraints. This fail-closed approach prevents malformed diagrams from reaching the rendering engine, avoiding runtime visualization errors.

### Can I extend the schemas with custom properties?

No, Archify schemas explicitly set `additionalProperties: false` on root objects and most nested structures. This strictness ensures cross-compatibility between different renderers and prevents undefined behavior from unexpected fields. To add custom metadata, use the extensible `meta` object or propose changes to the shared definitions in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json).

### What happens if a connection references a non-existent component ID?

The schema validates that `from` and `to` properties in connections and edges reference valid IDs defined within the same JSON document. While the JSON Schema enforces string type and format constraints, Archify’s validation layer verifies referential integrity to ensure every connection points to a defined component or node before processing continues.