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

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

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

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

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