How Archify Performs Schema Validation for the JSON IR

Archify validates its JSON Intermediate Representation (IR) against a JSON Schema using the AJV library, with validation occurring in 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	Defines the complete structural contract for valid IR documents
Validator Module	archify/ir/validator.ts	Loads the schema and exposes a reusable validateIr() function powered by AJV
Compiler Integration	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:

1. Schema loading — The static 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

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

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. 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)
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 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 and defines every structural requirement.

• AJV powers validation through 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.

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 with strict mode and comprehensive error reporting enabled.

Where is the IR schema defined?

The master schema resides at 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}