How Archify Generates Validators and Their Dependencies

Validators in the tt-a1i/archify repository are generated by a Node.js script that compiles JSON-Schema definitions into optimized JavaScript functions using the AJV library, creating a zero-dependency runtime validation layer.

The Archify diagram-as-code framework validates every workflow, sequence, and data-flow diagram against strict structural schemas before rendering. This validation layer is not manually maintained but automatically generated from source schemas located in archify/schemas/, ensuring that diagram type definitions and validation logic remain perfectly synchronized.

Validator Generation Process in Archify

The Generation Script

The entry point for validator creation is scripts/generate-validators.mjs. This ES module executes during the development workflow (triggered via npm run generate:validators) to transform static JSON-Schema files into executable JavaScript.

The script performs the following operations:

• Loads all *.schema.json files from archify/schemas/
• Instantiates an AJV validator instance with format and error plugins
• Compiles each schema using ajv.compile(schema) into standalone validation functions
• Aggregates these functions into a single output module

Compilation Pipeline

During compilation, the generator writes to archify/renderers/shared/generated-validators.mjs. This file includes a mandatory banner comment indicating its auto-generated status:

// Generated by scripts/generate-validators.mjs - DO NOT EDIT MANUALLY

The output module exports a named validator function for each diagram type (e.g., workflow, sequence, dataflow, lifecycle). These functions are synchronous, stateless, and immediately callable without requiring the AJV library at runtime.

Runtime Validation Architecture

The Validator Module

At runtime, archify/renderers/shared/validator.mjs serves as the validation dispatcher. It imports the generated validators module and exposes a validateSchema function that:

• Accepts a diagram object containing a diagram_type field
• Selects the appropriate pre-compiled validator from the generated module
• Returns either { ok: true } or a detailed error object with validation failures

// Example: Runtime validation of a workflow diagram
import { validateSchema } from './archify/renderers/shared/validator.mjs';

const diagram = {
  diagram_type: 'workflow',
  schema_version: 1,
  nodes: [{ id: 'start', type: 'terminal' }],
  edges: [{ from: 'start', to: 'end' }]
};

const result = validateSchema(diagram);
if (!result.ok) {
  console.error('Validation errors:', result.errors);
}

Pre-compiled Performance Benefits

Because AJV compiles schemas ahead of time rather than at runtime, the validation step avoids expensive schema parsing operations. The generated validators perform property checks and type validations through optimized JavaScript code paths, making validation suitable for high-frequency calls during CLI rendering or skill execution.

Dependencies and Requirements

AJV Library Stack

The generation script depends on the following npm packages, defined in the project's devDependencies:

• AJV (version ≥8) - The core JSON-Schema compiler and validator
• Ajv-formats - Provides format validators for standard strings like uri, email, and date-time
• Ajv-errors - Enhances error reporting with human-readable messages beyond AJV's default output

These dependencies are only required for development. Since generated-validators.mjs is committed to the repository, production consumers do not need to install AJV to perform diagram validation.

Node.js Environment

The generator script requires Node.js version 18 or higher due to its use of ES modules, top-level await, and modern filesystem APIs (via fs/promises). The script uses native import statements for both local schema files and third-party AJV plugins.

Regenerating Validators After Schema Changes

When modifying schema definitions in archify/schemas/, you must regenerate the validation code:

# Compile schemas into validators

npm run generate:validators

# Verify the generated file matches the source schemas (CI check)

npm run check:validators

The check:validators command exits with a non-zero status code if generated-validators.mjs is out of sync with the source schemas, preventing stale validation logic from being deployed.

Summary

• Generation Script: scripts/generate-validators.mjs compiles JSON-Schemas into JavaScript using AJV
• Output Location: Validators are written to archify/renderers/shared/generated-validators.mjs with a "do not edit" banner
• Runtime Entry: archify/renderers/shared/validator.mjs dispatches pre-compiled validators based on diagram_type
• Core Dependencies: AJV ≥8, ajv-formats, ajv-errors, and Node.js ≥18
• Workflow: Run npm run generate:validators after schema changes; use npm run check:validators in CI to prevent drift

Frequently Asked Questions

What triggers the validator generation process?

Developers manually trigger generation by running npm run generate:validators after modifying any file in archify/schemas/. The CI pipeline also runs npm run check:validators to ensure the generated file remains synchronized with source schemas before allowing merges.

Why does Archify commit generated validators to the repository?

Archify commits archify/renderers/shared/generated-validators.mjs to eliminate runtime dependencies on AJV for end users. This allows the CLI and skills to perform fast validation without requiring consumers to install the AJV library or compile schemas themselves.

What version of AJV does Archify require?

The generation script requires AJV version 8 or higher, which provides improved JSON-Schema draft support and better compilation performance than earlier versions. The ajv-formats and ajv-errors plugins must be compatible with this major version.

How do I validate a diagram at runtime?

Import validateSchema from archify/renderers/shared/validator.mjs and pass your diagram object to it. The function returns an object with an ok boolean and an optional errors array containing detailed validation failure messages.

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