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

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.

// 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 demonstrates a compliant IR structure that passes these strict checks. Additionally, examples/archify-repo.architecture.json contains explicit documentation noting that "ajv schema validation sits on the IR (fail-closed)", confirming the validation strategy.

// 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 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, 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.

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