# How Archify Generates Validators and Their Dependencies

> Learn how Archify generates validators and their dependencies. This Node.js script compiles JSON-Schema definitions into optimized JavaScript functions with AJV for zero-dependency runtime validation.

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

---

**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

```javascript
// 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:

```bash

# 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.