# How Archify's JSON IR Schema Validation Works: A Technical Deep Dive

> Explore Archify's JSON IR schema validation pipeline. Learn how AJV validators, runtime wrappers, and strict schema versioning ensure data integrity.

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

---

**Archify validates JSON Intermediate Representation through a four-stage pipeline using AJV-generated standalone validators, runtime wrappers with annotated error paths, and strict schema-version enforcement.**

The `tt-a1i/archify` repository implements a rigorous JSON-IR validation system that ensures structural correctness before any diagram rendering occurs. This fail-closed pipeline guarantees that only well-formed IR documents reach the rendering stage while providing precise diagnostics for debugging.

## Schema Definitions and Structure

Archify supports five diagram types—`workflow`, `sequence`, `dataflow`, `lifecycle`, and `architecture`—each governed by dedicated JSON-Schema files in `archify/schemas/`. The workflow schema at [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) mandates top-level fields including `schema_version`, `diagram_type`, `meta`, `lanes`, `nodes`, and `edges`.

The schema strictly limits `schema_version` to enum values `1` or `2`, enabling versioned contracts that support legacy IRs through migration utilities. Shared reusable definitions for `id`, `locale`, and `legendEntry` reside in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) and are composed into specific diagram schemas during the build process.

## Build-Time Validator Generation

The pipeline compiles schemas into standalone validators using **AJV 2020**. The Node.js script `archify/scripts/generate-validators.mjs` reads every schema file, merges definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), and outputs bundled functions to `archify/renderers/shared/generated-validators.mjs`.

The generator applies strict configuration:

- `allErrors: true` captures all validation failures simultaneously
- `strict: true` enforces rigorous schema adherence
- Embedded UCS-2 length helper eliminates runtime import dependencies

Generate validators via npm:

```bash
npm run generate:validators

```

This executes `node archify/scripts/generate-validators.mjs`, rewriting the output file only when source schemas change to avoid unnecessary builds.

## Runtime Validation with Annotated Errors

The module `archify/renderers/shared/validator.mjs` imports generated validators and exposes `validateSchema(diagramType, data)`. This wrapper performs structural validation and converts AJV errors into human-readable **DiagnosticError** instances.

Example validation workflow:

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

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

try {
  validateSchema('workflow', ir);
  console.log('✅ IR is valid – safe to render');
} catch (e) {
  console.error('❌ Validation failed:\n', e.message);
  // e.diagnostics contains structured error objects for tooling
}

```

When validation fails, the wrapper produces **annotated paths** that combine JSON pointers with element identifiers. Instead of raw indices like `/nodes/3/label`, errors reference `/nodes/3 (id/label: "router") /label` by extracting the nearest `id` or `label` field. The system also suggests supported fixes such as "remove unsupported property" or "add required property" for automated correction workflows.

## Degraded Mode and Version Enforcement

The mandatory `schema_version` field ensures the renderer selects appropriate validation logic and migration paths. In *degraded mode*—when AJV is not installed at runtime—the wrapper prints a warning and **skips** schema validation, though layout and composition checks continue executing.

```javascript
// Degraded mode behavior when AJV is unavailable
process.env.NODE_ENV = 'production'; 
validateSchema('workflow', ir); 
// Logs: 'Running without schema validation – check your dependencies.'

```

This design prevents crashes in constrained environments while maintaining explicit warnings that type-checking is disabled. When validators are present, invalid IR aborts rendering with a non-zero exit status.

## Summary

- **Schema definitions** in `archify/schemas/` enforce structure for five diagram types using versioned contracts via `schema_version` enums.
- **Build-time generation** via `archify/scripts/generate-validators.mjs` produces standalone AJV validators with `allErrors: true` and zero runtime dependencies.
- **Runtime wrapper** at `archify/renderers/shared/validator.mjs` provides `validateSchema()` with annotated error paths and actionable fix suggestions.
- **Fail-closed security** aborts rendering with non-zero exit status when validation fails.
- **Degraded mode** gracefully handles missing AJV installations with warnings while preserving layout validation.

## Frequently Asked Questions

### What JSON Schema draft does Archify use for validation?

Archify uses **AJV 2020** to compile and validate schemas, as implemented in `archify/scripts/generate-validators.mjs`. The 2020 draft specification provides advanced validation features required for complex nested structures in diagram IRs, including the schema composition patterns found in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json).

### How does Archify handle validation errors?

The runtime wrapper converts AJV errors into **DiagnosticError** instances with **annotated paths** that include element identifiers like `id` or `label`. For example, errors reference `/nodes/3 (id/label: "router") /label` instead of raw array indices. Each error object includes `suggestedFixes` such as "add required property" or "remove unsupported property" for integration with developer tooling.

### Where are the generated validators stored in the codebase?

The build script writes compiled validators to `archify/renderers/shared/generated-validators.mjs`. This ES module exports standalone validation functions for each diagram type, generated with `strict: true` settings for comprehensive error reporting. The file is overwritten only when schema source files change.

### What happens when AJV is not available at runtime?

When AJV is unavailable, Archify enters **degraded mode**: the runtime wrapper skips schema validation but continues with layout and composition checks, printing a warning to stderr. This ensures diagrams can still render in constrained environments while explicitly alerting users that structural type-checking is disabled.