# How Archify Validates Schemas at Runtime Without npm Dependencies

> Discover how Archify achieves runtime schema validation without npm dependencies. It compiles JSON schemas into standalone JS functions during build for efficient, self-contained validation.

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

---

**Archify compiles JSON schemas into standalone JavaScript functions during the build process, bundling these pre-generated validators directly into the repository so that runtime validation requires no external npm packages.**

The tt-a1i/archify project eliminates runtime dependency bloat by shifting schema validation work from execution time to build time. Instead of bundling a JSON Schema validator like Ajv in production, Archify generates pure JavaScript validation functions that ship with the source code, enabling zero-dependency runtime checks for all diagram types.

## Build-Time Code Generation Strategy

Archify's architecture relies on **pre-generating** validator functions before distribution. During the build step, the project runs **Ajv** (Another JSON Schema Validator) locally to parse each diagram schema and compile it into a tiny, optimized JavaScript function. These compiled functions are written to `archify/renderers/shared/generated-validators.mjs`, creating a static snapshot of validation logic that requires zero schema compilation overhead when Archify executes.

### The Generated Validators File

The file `archify/renderers/shared/generated-validators.mjs` contains the build-step output. Each exported function corresponds to a specific diagram type—such as `workflow` or `sequence`—hardcoded as plain JavaScript rather than schema objects. This module is committed directly to the repository, ensuring consumers receive validation logic without installing or configuring Ajv.

## Runtime Validation Architecture

At runtime, Archify loads these pre-generated functions through a thin wrapper that handles lookup, execution, and error transformation.

### The Core Validator Module

The module `archify/renderers/shared/validator.mjs` implements the main validation entry point:

```javascript
import * as validators from './generated-validators.mjs';

export function validateSchema(diagramType, data) {
  const validator = validators[diagramType];
  if (!validator) {
    throw new Error(`Unknown diagram type: ${diagramType}`);
  }
  
  const isValid = validator(data);
  if (!isValid) {
    throwDiagnosticError(validator.errors);
  }
}

```

When `validateSchema(diagramType, data)` is invoked, it looks up the appropriate validator using the diagram type as a key. If validation succeeds, the function returns silently; otherwise, it triggers diagnostic error processing.

### Error Transformation and Diagnostics

Rather than exposing raw Ajv error objects, Archify transforms validation failures into rich diagnostic messages. The `validator.mjs` module processes the `validate.errors` array, converting cryptic schema paths into **annotated paths** with **suggested fixes** and **diagnostic codes**. It then throws a custom `throwDiagnosticError` containing these structured diagnostics, providing actionable feedback without leaking Ajv implementation details.

## Implementation Examples

Archify's validation layer integrates across CLI tools, compilers, and programmatic APIs without requiring npm install steps for validation dependencies.

### CLI Validation

The command-line interface validates diagrams before processing, as implemented in `archify/renderers/shared/cli.mjs`:

```javascript
import { validateSchema } from './validator.mjs';
import { readFileSync } from 'fs';

const diagramType = process.argv[2];          // e.g., "workflow"
const diagramPath = process.argv[3];
const diagram = JSON.parse(readFileSync(diagramPath, 'utf8'));

validateSchema(diagramType, diagram);         // throws if invalid
console.log('✅ Diagram is valid');

```

### Workflow Compiler Integration

Before compiling a workflow, the compiler ensures data integrity. In `archify/renderers/workflow/workflow-compiler.mjs`:

```javascript
import { validateSchema } from '../shared/validator.mjs';
import { compileWorkflow } from './compiler.mjs';

export async function compileWorkflowHandler(diagramType, workflow) {
  // Runtime validation (no npm deps)
  validateSchema(diagramType, workflow);
  // …proceed with compilation…
  return compileWorkflow(workflow);
}

```

### Programmatic API Usage

Any Node.js script can import the validator directly for zero-dependency validation:

```javascript
import { validateSchema } from 'archify/renderers/shared/validator.mjs';

try {
  validateSchema('sequence', mySequenceObject);
  // safe to use the object now
} catch (e) {
  console.error(e.message);   // detailed diagnostics
}

```

## Benefits of Zero-Dependency Validation

Eliminating Ajv from the runtime dependency tree provides distinct technical advantages:

- **Reduced Installation Footprint**: End users download only necessary source files, not a full JSON Schema validation library
- **Faster Startup Times**: No runtime schema compilation or module resolution overhead
- **Enhanced Reliability**: No risk of dependency version conflicts or npm registry availability issues affecting validation functionality
- **Immutable Behavior**: The `generated-validators.mjs` file ensures validation logic is consistent across all installations

## Summary

- **Build-time generation**: Archify uses Ajv during development to compile schemas into pure JavaScript functions stored in `archify/renderers/shared/generated-validators.mjs`
- **Zero-dependency runtime**: The `archify/renderers/shared/validator.mjs` module imports these functions and executes them without external packages
- **Rich error handling**: Validation failures are transformed via `throwDiagnosticError` into annotated paths with suggested fixes
- **Universal integration**: This architecture supports CLI tools, workflow compilers, and programmatic APIs in the tt-a1i/archify repository without runtime npm dependencies

## Frequently Asked Questions

### How does Archify validate schemas without requiring npm dependencies at runtime?

Archify runs **Ajv** exclusively during the build process to compile JSON schemas into standalone JavaScript functions. These functions are bundled in `archify/renderers/shared/generated-validators.mjs` and committed to the repository. At runtime, the system executes these pre-compiled functions directly, eliminating the need to install or load Ajv in production environments.

### Can I modify schemas or add new diagram types without breaking the zero-dependency model?

Yes, but you must regenerate the validator file. After modifying schema definitions, run the build script to recompile `archify/renderers/shared/generated-validators.mjs`. The new validators remain pure JavaScript functions, preserving the zero-dependency runtime characteristic while supporting your updated schemas.

### Are pre-generated validators slower than runtime compilation?

No. The generated validator functions in `generated-validators.mjs` are highly optimized JavaScript code that executes faster than runtime schema compilation. Since there is no parsing or compilation step during validation calls, runtime performance exceeds traditional Ajv implementations that compile schemas on-the-fly.

### How does Archify handle validation errors compared to standard Ajv output?

Instead of returning raw Ajv error objects, the `validateSchema` function catches validation failures and passes them through a diagnostic transformer. This generates rich error messages with **annotated paths**, **suggested fixes**, and **diagnostic codes** via `throwDiagnosticError`, making debugging significantly easier than interpreting standard JSON Schema validation errors.