# How Archify's JSON IR Schema System Ensures Data Integrity: A Complete Technical Guide

> Archify ensures data integrity with a strict, versioned JSON Schema and pre-compiled AJV validators. Learn how Archify rejects malformed data early for robust processing.

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

---

**Archify guarantees data integrity by enforcing a strict, versioned JSON Schema on its Intermediate Representation (IR), using pre-compiled AJV validators generated at build time to reject malformed data before processing.**

The **Archify** project (`tt-a1i/archify`) represents diagrams, workflows, and software architectures as a JSON-based Intermediate Representation (IR). To prevent data corruption and ensure consistency across its rendering pipeline, Archify implements a rigorous **JSON IR schema** validation system that operates at both compile time and runtime with a fail-closed policy.

## The Foundation: Versioned JSON Schema Definitions

At the core of Archify's integrity guarantees lies a hand-crafted JSON Schema that defines the exact structure of valid IR documents. This schema enforces strict typing through **AJV** (Another JSON Schema Validator), configured with `additionalProperties: false` to reject any unexpected fields.

The schema is explicitly versioned (currently **schema v1**) to ensure backward compatibility and controlled evolution. Every IR document must include the `schema_version` field, allowing the system to select the appropriate validator and prevent version mismatches that could lead to processing errors.

### Schema Location and Structure

While the raw schema definitions reside in the repository's schema directory, the authoritative source of truth is compiled into the validation pipeline through `archify/scripts/generate-validators.mjs`. This script processes the JSON Schema definitions and outputs optimized validation functions that are bundled with the application.

## Compile-Time Validator Generation

Archify does not parse schemas at runtime. Instead, it uses a **compile-time generation strategy** to maximize performance and consistency.

In `archify/scripts/generate-validators.mjs`, the build process invokes AJV to generate optimized validator functions from the JSON Schema definitions. These validators are pre-compiled and bundled into the final distribution, eliminating runtime schema parsing overhead and ensuring identical validation logic across all environments.

### Build Integration

During the build process, running the generation script creates strongly-typed validation functions that are imported by the core IR processor. This approach ensures that any schema changes trigger a rebuild, catching validation logic errors before deployment.

```javascript
// Example: Generated validator usage pattern within the Archify core
import { validateIR } from './validators.js';

const irDocument = {
  schema_version: 1,
  type: "workflow",
  steps: [ /* ... */ ]
};

if (!validateIR(irDocument)) {
  console.error("IR validation failed:", validateIR.errors);
  throw new Error("Invalid IR structure");
}

```

## Runtime Validation with Fail-Closed Enforcement

Every IR document undergoes **fail-closed validation** before entering the rendering or execution pipeline. The system imports the pre-compiled validators from `archify/scripts/generate-validators.mjs` and validates payloads immediately upon receipt.

If validation fails, Archify aborts the operation and surfaces detailed error messages rather than attempting to process malformed data. This prevents corrupt IR from propagating to downstream renderers, workflow engines, or skill plugins.

### Validation in Practice

The validation layer checks required fields, enumerations, and data types. The fixture in [`archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json) demonstrates a compliant IR structure that passes these strict checks. Additionally, [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) contains explicit documentation noting that **"ajv schema validation sits on the IR (fail-closed)"**, confirming the validation strategy.

```javascript
// Runtime validation example from Archify's ingestion layer
const Ajv = require('ajv');
const ajv = new Ajv({ strict: true, allErrors: true });

// Load the compiled schema validator
const validate = require('../validators/ir-schema-v1.js');

function processIR(inputData) {
  const valid = validate(inputData);
  
  if (!valid) {
    // Fail closed: throw immediately with specific error details
    throw new Error(`IR validation error: ${JSON.stringify(validate.errors)}`);
  }
  
  return renderWorkflow(inputData);
}

```

## Integration Points and Error Handling

The validation system integrates at multiple boundaries to ensure comprehensive coverage:

- **Input ingestion**: All external IR submissions are validated immediately upon receipt
- **Skill plugins**: Third-party extensions must produce IR that conforms to the schema before submission to the renderer
- **Test fixtures**: Baseline files like [`archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json) serve as regression tests for the schema validation

When validation fails, AJV provides detailed error objects indicating exactly which constraint was violated, enabling rapid debugging and preventing silent failures.

## Summary

- **Archify** enforces data integrity through a **versioned JSON Schema** (v1) that defines strict IR structure with `additionalProperties: false`
- **AJV validators** are **pre-compiled at build time** via `archify/scripts/generate-validators.mjs` for performance and consistency
- The system operates on a **fail-closed** policy, rejecting invalid IR before processing and preventing corruption in downstream components
- **Schema versioning** via the `schema_version` field ensures backward compatibility while allowing controlled evolution
- Validation occurs at ingestion boundaries, ensuring all renderers and execution engines receive well-formed data

## Frequently Asked Questions

### How does Archify handle schema version mismatches?

Archify requires every IR document to declare its schema version explicitly through the `schema_version` field. The validator selects the appropriate schema definition based on this field, ensuring that legacy IR documents continue to validate against their original schema while new features use updated definitions. This prevents breaking changes from affecting existing workflows.

### What happens when an IR document fails validation?

The system aborts the operation immediately and returns detailed error information from AJV, including the specific field path and constraint that failed. As documented in [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json), this "fail-closed" approach prevents malformed data from reaching renderers or execution engines, avoiding runtime crashes or silent corruption.

### Where is the JSON Schema validation logic implemented?

The validation logic is implemented in `archify/scripts/generate-validators.mjs`, which compiles the JSON Schema into optimized JavaScript functions using AJV. These compiled validators are then imported by the core IR processor and applied at runtime to all incoming documents, ensuring consistent validation across the entire application.

### Why does Archify use compile-time validator generation instead of runtime validation?

By generating validators at build time via `archify/scripts/generate-validators.mjs`, Archify eliminates the performance overhead of parsing JSON Schemas during execution. This ensures consistent validation behavior across environments and allows the build process to catch schema definition errors before deployment, reducing production failures and improving startup performance.