How Archify Generates and Uses JSON Schema Validators: A Complete Technical Guide

Archify validates every diagram’s JSON IR against pre-compiled JSON schema validators generated by AJV's standalone code compiler, producing zero-runtime-dependency ES modules that renderers invoke before processing.

In the tt-a1i/archify repository, type safety and data integrity are enforced through a deterministic JSON schema validation pipeline. The project leverages AJV (Another JSON Schema Validator) with its standalone code generation capability to create fast, dependency-free validation functions at build time, ensuring diagram integrity before any rendering or export operation.

Schema Architecture and Source Files

Archify organizes its validation contracts under archify/schemas/, separating shared definitions from diagram-specific constraints.

Diagram-Specific Schemas

Each supported diagram type maintains its own schema file to enforce domain-specific rules:

• workflow.schema.json
• sequence.schema.json
• dataflow.schema.json
• lifecycle.schema.json
• architecture.schema.json

These files define the allowable structure for nodes, edges, and metadata unique to each visualization type.

Common Schema Definitions

All diagram schemas extend archify/schemas/common.schema.json, which houses shared definitions for base properties like identifiers, labels, and styling attributes. This inheritance model ensures consistency across the entire schema ecosystem while allowing specialized extensions.

Generating Validators with AJV Standalone

The transformation from static JSON schemas to executable validation logic occurs through a dedicated build script that utilizes AJV-2020’s advanced compilation features.

The generate-validators.mjs Script

Located at archify/scripts/generate-validators.mjs, the generator script performs the following operations:

1. Instantiates AJV with strict: true and allErrors: true to catch every schema violation and report precise JSON Pointer paths.
2. Registers all diagram schemas and the common schema with the AJV instance.
3. Invokes AJV’s standalone code generator to emit a single ES module containing compiled validation functions.

The resulting output file, archify/renderers/shared/generated-validators.mjs, contains dependency-free validation code that starts with a generation banner and exports functions like validateWorkflow, validateSequence, and validateDataflow.

NPM Scripts for Build Integration

The build pipeline exposes two npm scripts in package.json to manage validator generation:

{
  "scripts": {
    "generate:validators": "node scripts/generate-validators.mjs",
    "check:validators": "node scripts/generate-validators.mjs --check"
  }
}

Run npm run generate:validators to create or update the compiled validation module. Use npm run check:validators in CI pipelines to verify that the generated file is synchronized with its source schemas; the script exits with a non-zero status code if the validators are stale.

Runtime Validation in Renderers

Once generated, the validators integrate seamlessly into the rendering pipeline, enforcing type constraints immediately before visual processing begins.

Importing Generated Validators

Each renderer imports the specific validator it requires from the shared generated module. For example, the workflow renderer implements validation as follows:

// archify/renderers/workflow/render.mjs
import { validateWorkflow } from '../shared/generated-validators.mjs';

export function renderWorkflow(jsonIR) {
  const errors = validateWorkflow(jsonIR);
  if (errors) {
    throw new Error(
      `JSON Schema error: ${errors[0].message} (${errors[0].instancePath})`
    );
  }
  // Proceed with rendering logic...
}

Error Handling and Strict Mode

The AJV configuration employed during generation ensures comprehensive error reporting. With allErrors: true, validators return arrays containing every schema violation rather than failing fast on the first error. Each error object includes an instancePath property (e.g., /nodes/3/id/label) that precisely locates the offending data within the JSON IR structure.

Build-Time vs Runtime Dependencies

Archify’s validation architecture distinguishes sharply between development dependencies and production runtime requirements.

Zero-Runtime-Dependency Design

The validators generated by AJV’s standalone compiler are completely self-contained. Unlike standard AJV usage which requires the ajv package at runtime, these compiled functions contain no require() calls or external dependencies. This design allows the final HTML output to ship without any npm packages, reducing bundle size and eliminating runtime version conflicts. The only dependency is AJV itself, listed strictly as a development dependency (npm install ajv@^8.17.1 --save-dev).

Degraded Mode Fallback

If AJV is not present in the build environment, Archify gracefully degrades rather than crashing. The build system detects the absence of AJV and emits a warning, subsequently skipping schema validation while continuing to execute layout and structural checks. This ensures development environments without full tooling can still generate diagrams, though without the guarantees of schema validation.

Summary

• Schema sources reside in archify/schemas/, with common.schema.json providing shared definitions and individual files for each diagram type.
• Validator generation occurs via archify/scripts/generate-validators.mjs, which uses AJV-2020’s standalone compiler to create archify/renderers/shared/generated-validators.mjs.
• NPM scripts generate:validators and check:validators automate build integration and CI verification.
• Runtime usage involves importing specific validators (e.g., validateWorkflow) from the generated module and checking returned error arrays before rendering.
• Zero dependencies at runtime ensure shipped HTML contains no validation-related npm packages, with AJV required only during development.

Frequently Asked Questions

How does Archify generate JSON schema validators?

Archify uses the Node.js script archify/scripts/generate-validators.mjs to compile JSON schema files into standalone JavaScript functions. The script creates an AJV-2020 instance with strict mode enabled, registers all schema definitions, and invokes AJV’s code generator to produce archify/renderers/shared/generated-validators.mjs, an ES module containing dependency-free validation functions for each diagram type.

What happens if AJV is not installed in the build environment?

According to the Archify source code, the system enters a degraded mode when AJV is absent. The build process detects the missing dependency, prints a warning message, and bypasses schema validation while continuing to run layout checks. This allows the application to function in minimal environments, though without schema guarantees.

How do renderers use the generated validators?

Renderers import the specific validation function they need from ../shared/generated-validators.mjs (for example, import { validateWorkflow }). They pass the diagram’s JSON IR to this function and check the return value; if an array of errors is returned, the renderer throws an exception detailing the first error’s message and JSON Pointer path before any rendering logic executes.

Where are the JSON schema definitions stored in Archify?

All schema definitions live under the archify/schemas/ directory. This includes common.schema.json for shared property definitions and individual schema files for each diagram type: workflow.schema.json, sequence.schema.json, dataflow.schema.json, lifecycle.schema.json, and architecture.schema.json.

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