# How Archify Performs Schema Validation for the JSON IR

> Discover how Archify performs schema validation for its JSON IR using AJV. Ensure code integrity before compilation with robust validation checks.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-01

---

**Archify validates its JSON Intermediate Representation (IR) against a JSON Schema using the AJV library, with validation occurring in [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts) before any compilation or execution begins.**

Archify represents workflows as a structured **JSON Intermediate Representation (IR)**. To guarantee structural correctness and prevent runtime failures, the framework implements a strict validation pipeline that checks every IR against a canonical JSON Schema. This article examines the implementation details based on the source code in `tt-a1i/archify`.

## The Core Validation Architecture

Schema validation in Archify relies on three interconnected components:

| Component | File Path | Purpose |
|-----------|-----------|---------|
| **JSON Schema** | [`archify/ir/schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/ir/schema.json) | Defines the complete structural contract for valid IR documents |
| **Validator Module** | [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts) | Loads the schema and exposes a reusable `validateIr()` function powered by AJV |
| **Compiler Integration** | [`archify/workflow-compiler.ts`](https://github.com/tt-a1i/archify/blob/main/archify/workflow-compiler.ts) | Invokes validation as the mandatory first step in the compilation pipeline |

This design ensures that malformed IR never advances past initial validation, protecting downstream transformation logic from unexpected input variations.

## How the Validator Works

The validation process follows a six-step flow implemented in [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts):

1. **Schema loading** — The static [`schema.json`](https://github.com/tt-a1i/archify/blob/main/schema.json) file is imported at module initialization.

2. **AJV instantiation** — An AJV instance is created with `strict: true` and `allErrors: true` to catch every violation in a single pass.

3. **Schema compilation** — The JSON Schema is compiled once into a reusable validation function. This compilation step amortizes cost across all subsequent validations.

4. **Runtime validation** — Incoming IR documents are passed to `validateIr(json)`, which applies the compiled validator.

5. **Error formatting** — If validation fails, AJV's error objects are transformed into human-readable messages that include precise JSON paths.

6. **Compilation gating** — Only successful validation allows the workflow compiler to proceed.

Because AJV performs **compile-time schema optimization**, typical workflow validations complete in sub-millisecond time after the initial startup cost.

## Using the Validator in Practice

### Basic IR Validation

```typescript
import { validateIr } from "./archify/ir/validator";

const rawIr = {
  workflow: "example",
  steps: [
    { id: "start", type: "trigger", config: { event: "push" } },
    { id: "build", type: "action", config: { cmd: "npm run build" } },
  ],
  connections: [{ from: "start", to: "build" }],
};

try {
  const validIr = validateIr(rawIr);
  console.log("IR validated — proceeding to compilation");
  // Continue to workflow-compiler.ts pipeline...
} catch (err) {
  console.error("Schema validation failed:", err.message);
}

```

### Testing Invalid IR Cases

```typescript
import { validateIr } from "./archify/ir/validator";

test("rejects IR missing required connections field", () => {
  const incompleteIr = { workflow: "bad", steps: [] };
  
  expect(() => validateIr(incompleteIr))
    .toThrow(/must have required property 'connections'/);
});

```

## Integration with the Compilation Pipeline

The `validateIr` function serves as a mandatory gate in [`archify/workflow-compiler.ts`](https://github.com/tt-a1i/archify/blob/main/archify/workflow-compiler.ts). According to the source implementation:

- The compiler imports `validateIr` from `"./ir/validator"` at the top of the file.
- The first operation on any incoming workflow is invoking `validateIr(rawInput)`.
- If validation throws, the compilation aborts immediately with formatted error details surfaced to the caller.
- Successful validation returns a typed IR object that subsequent transformation stages consume.

This fail-fast approach prevents silent data corruption and provides clear feedback to workflow authors about structural problems.

## Performance and Security Characteristics

| Aspect | Implementation Detail |
|--------|----------------------|
| **Validation engine** | AJV ^8.x (listed in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json)) |
| **Schema compilation** | Once per process startup; cached validator function |
| **Error detail level** | All errors reported via `allErrors: true` |
| **Strictness** | AJV strict mode enabled to catch schema definition issues |
| **Typical latency** | Sub-millisecond per validation after warm-up |

The `strict: true` configuration also helps maintain schema quality by flagging potential issues in [`schema.json`](https://github.com/tt-a1i/archify/blob/main/schema.json) itself during development.

## Summary

- **Schema validation** is mandatory in Archify — no IR reaches compilation without passing `validateIr()`.

- The **canonical schema** lives in [`archify/ir/schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/ir/schema.json) and defines every structural requirement.

- **AJV powers validation** through [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts), with compile-once semantics for performance.

- **Error messages** include precise JSON paths, making debugging straightforward.

- The **compilation pipeline** enforces validation as its first operation in [`archify/workflow-compiler.ts`](https://github.com/tt-a1i/archify/blob/main/archify/workflow-compiler.ts).

## Frequently Asked Questions

### What JSON Schema validator does Archify use?

Archify uses **AJV (Another JSON Schema Validator)** version 8.x. The validator is instantiated in [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts) with strict mode and comprehensive error reporting enabled.

### Where is the IR schema defined?

The master schema resides at [`archify/ir/schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/ir/schema.json). This file contains the complete structural contract that every valid IR must satisfy, including required fields, type constraints, and relational rules between workflow nodes.

### How does Archify handle validation errors?

When `validateIr()` detects schema violations, it throws an exception containing formatted error messages with exact JSON paths. The calling code in [`archify/workflow-compiler.ts`](https://github.com/tt-a1i/archify/blob/main/archify/workflow-compiler.ts) catches these and surfaces them to the user, halting compilation immediately.

### Can I perform schema validation independently of compilation?

Yes — the `validateIr` function exported from [`archify/ir/validator.ts`](https://github.com/tt-a1i/archify/blob/main/archify/ir/validator.ts) is designed for standalone use. Import it directly to validate IR documents without triggering the full compilation pipeline, useful for testing or pre-submission checks.