# How Archify Validates JSON Specifications for Diagrams: Build-Time Schema Compilation with AJV

> Learn how Archify validates JSON diagram specifications with build-time schema compilation using AJV for zero-overhead runtime checks. Optimize your diagram generation.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-07

---

**Archify validates JSON diagram specifications using AJV-based validators that are compiled once at build time and stored in generated-modules for zero-overhead runtime checks.**

Archify treats diagram definitions as JSON "architecture" specifications. To guarantee that these specifications conform to the expected structure, the **tt-a1i/archify** repository generates and runs dedicated JSON-Schema validators through a two-stage pipeline.

## Validator Generation Pipeline

Archify separates schema compilation from runtime validation for optimal performance. The heavy lifting of JSON-Schema compilation happens only once during the build process.

### Build-Time Generation with `generate-validators.mjs`

The script `archify/scripts/generate-validators.mjs` walks the repository's schema definitions, compiles each one with **AJV** (Another JSON Validator), and writes ready-to-use validator functions into `archify/renderers/shared/generated-validators.mjs`.

This approach ensures that:
- Schema parsing and compilation overhead occurs once, not per request
- Generated validators are plain JavaScript functions requiring no additional dependencies at runtime
- Errors include detailed path-to-error reports for debugging malformed specs

## Runtime Validation Flow

When a user supplies a diagram spec—such as an [`archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify-repo.architecture.json) file—the renderer imports the appropriate validator from the generated module and calls it before any rendering logic executes.

If the JSON does not satisfy the schema, the validator throws an error with a detailed path-to-error report, preventing malformed diagrams from entering the rendering pipeline.

### Example: Validating an Architecture Spec

```javascript
// Load a compiled validator for the "architecture" schema
import { validateArchitecture } from './archify/renderers/shared/generated-validators.js';

// Example JSON spec (could be read from a .json file)
const spec = {
  version: "1.0",
  nodes: [{ id: "root", type: "process" }],
  edges: []
};

// Validate – throws if the spec is invalid
validateArchitecture(spec);

```

### CLI Integration

The validation layer integrates automatically with the Archify CLI:

```bash

# The command automatically validates the JSON before rendering

archify render examples/archify-repo.architecture.json

```

## Test Coverage for Validator Reliability

The test suite `archify/test/generate-validators.test.mjs` verifies three critical behaviors:
- All schemas are successfully compiled without errors
- Valid examples pass validation and return true
- Intentionally malformed examples are rejected with correct, descriptive error messages

This testing strategy ensures that schema changes do not break existing validators or allow invalid specs to slip through.

## Key Files in the Validation System

| File | Role |
|------|------|
| `archify/scripts/generate-validators.mjs` | Generates AJV validator functions from JSON-Schema definitions |
| `archify/renderers/shared/generated-validators.mjs` | Contains compiled validator functions used at runtime |
| `archify/test/generate-validators.test.mjs` | Test suite ensuring validators work as intended |
| [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | Sample diagram specification that passes validation |

## Summary

- **Build-time compilation** via `generate-validators.mjs` eliminates runtime AJV overhead
- **Generated validators** in `generated-validators.mjs` provide fast, dependency-free checks
- **Automatic CLI validation** ensures all rendered specs are structurally correct before processing
- **Comprehensive test coverage** prevents regression in schema compliance

## Frequently Asked Questions

### What validation library does Archify use for JSON schema checking?

Archify uses **AJV** (Another JSON Validator) as its core validation engine. AJV compiles JSON-Schema definitions into optimized JavaScript functions during the build phase, resulting in high-performance runtime validation without requiring AJV itself in production dependencies.

### When does JSON validation occur in the Archify pipeline?

Validation occurs at **two distinct times**: first during build/development when `generate-validators.mjs` compiles schemas, and second at **runtime** when a renderer imports and executes the pre-compiled validator. This split ensures that users receive immediate feedback on malformed specs without paying the cost of schema compilation per request.

### What happens if I provide an invalid JSON specification to Archify?

The compiled validator throws an error containing a **detailed path-to-error report** that pinpoints exactly which property failed validation and why. This error propagates up through the CLI or API layer, halting the rendering pipeline before any diagram generation begins.

### Can I validate specs programmatically without using the CLI?

Yes. Import the specific validator function from `generated-validators.mjs` and call it directly with your parsed JSON object, as shown in the code example above. This pattern is useful for custom integrations, CI pipelines, or building wrapper tools around Archify's core engine.