How Archify Validates Diagram JSON Against Schemas: Build-Time AJV Compilation

Archify validates diagram JSON against schemas using AJV in draft-2020-12 mode, generating standalone validator functions at build time to ensure zero runtime dependencies while enforcing strict structural constraints.

The tt-a1i/archify repository implements a robust validation pipeline that ensures diagram integrity without bloating the final HTML output. Instead of bundling a validation library with every rendered diagram, Archify validates diagram JSON against schemas by pre-compiling validators during the build process. This architecture supports workflow, architecture, dataflow, and other diagram types through strict JSON Schema enforcement while maintaining a zero-dependency runtime environment.

Schema Definition and Structure

All diagram type definitions reside in archify/schemas/ as individual JSON Schema files. These schemas conform to the draft-2020-12 specification and define required properties including schema_version, diagram_type, meta, nodes, and edges. Each schema enforces constraints such as additionalProperties: false to prevent extraneous fields and uses enumerated values to restrict diagram types to valid categories.

The schemas are fully documented in the repository's schemas README and are version-controlled alongside the source code. This ensures that every diagram JSON must explicitly declare its type and structure before processing, with validation failing immediately if required fields are missing or malformed.

Build-Time Validator Generation

Rather than loading AJV at runtime, Archify uses a compilation step to create standalone validator functions. The script scripts/generate-validators.mjs orchestrates this process by loading every schema file, instantiating an AJV compiler, and generating pre-compiled validation code.

The Generation Script

The scripts/generate-validators.mjs file creates an AJV instance configured for draft-2020-12 validation. It iterates through all schema definitions in archify/schemas/, compiles them into validation functions, and writes a single output module. This approach eliminates the need to parse schemas or load AJV in the browser or CLI runtime environment.

Pre-Compiled Validator Functions

The generation script outputs archify/renderers/shared/generated-validators.mjs, which exports plain JavaScript functions named after each diagram type. Validators such as workflow, architecture, and dataflow are available as named exports. Because these are pre-compiled validation functions, they execute without requiring the AJV library at runtime, achieving true zero-dependency validation.

// Example: Manually invoking a generated validator
import { workflow as validateWorkflow } from './archify/renderers/shared/generated-validators.mjs';

const diagram = JSON.parse(fs.readFileSync('my-diagram.json', 'utf8'));
const result = validateWorkflow(diagram);

if (result) {
  console.log('Diagram is valid!');
} else {
  console.error('Diagram failed validation – see AJV errors above.');
}

Runtime Validation Pipeline

At runtime, the CLI and renderers import the generated validators through a thin abstraction layer. The file archify/renderers/shared/validator.mjs loads archify/renderers/shared/generated-validators.mjs and exposes the appropriate validator based on the diagram type being processed.

The Validator Wrapper

The validator.mjs module acts as the interface between the CLI commands and the generated validation functions. When the user invokes a validation command, the wrapper selects the correct validator (e.g., validators.workflow) and applies it to the parsed JSON object. This architecture centralizes validation logic while keeping the generated code isolated and replaceable during builds.

CLI Integration and Error Handling

The CLI entry point at archify/bin/archify.mjs handles the validate <type> <file> command sequence. When invoked, it parses the target JSON file and passes it to the corresponding validator function. If validation succeeds, the function returns true and the CLI may proceed with rendering. If validation fails, AJV produces path-prefixed error messages such as "/nodes/3 (id/label: \"router\")", which the CLI prints before exiting with a non-zero status code.

# CLI usage – validates a workflow diagram and prints a JSON receipt

archify validate workflow path/to/diagram.json --json

// Inside the CLI (simplified implementation)
const validatorsPath = path.join(skillRoot, 'renderers/shared/generated-validators.mjs');
import * as validators from validatorsPath;
const validator = validators[diagramType];   // e.g. 'workflow'
const ok = validator(diagram);

if (!ok) process.exit(1);

Degraded Mode and Fallback Behavior

When AJV is not installed in the build environment, Archify detects the missing dependency and enters a degraded mode. In this state, the system skips schema validation entirely and continues with layout checks, emitting a warning rather than throwing an error. This ensures that development environments without full build tooling can still generate diagrams, though without the guarantees of strict schema validation.

Summary

• Archify validates diagram JSON against schemas using AJV draft-2020-12 specifications defined in archify/schemas/.
• The build script scripts/generate-validators.mjs generates standalone validators in archify/renderers/shared/generated-validators.mjs.
• Runtime validation occurs through archify/renderers/shared/validator.mjs, enabling zero-dependency operation in the final output.
• The CLI in archify/bin/archify.mjs provides path-prefixed error messages for precise debugging of schema violations.
• Degraded mode allows continued operation without AJV installed, skipping validation while warning the user.

Frequently Asked Questions

What JSON Schema draft does Archify use for validation?

Archify uses AJV (Another JSON-Schema Validator) in draft-2020-12 mode to validate diagram JSON against schemas. This modern draft specification provides advanced validation features while maintaining compatibility with standard JSON Schema tooling.

How does Archify handle validation without runtime AJV dependencies?

By utilizing AJV's standalone code generation feature in scripts/generate-validators.mjs, Archify pre-compiles all validators into archify/renderers/shared/generated-validators.mjs. These exported functions perform validation without requiring the AJV library at runtime, resulting in zero-dependency HTML outputs.

Where are the diagram schema definitions stored in the repository?

All diagram type schemas are stored in the archify/schemas/ directory. Each diagram variant (workflow, architecture, dataflow, etc.) has its own JSON Schema file that defines required properties such as schema_version, diagram_type, meta, nodes, and edges.

What happens when a diagram fails validation in the Archify CLI?

When validation fails, the CLI prints path-prefixed error messages (e.g., "/nodes/3 (id/label: \"router\")") that indicate the exact location of the schema violation, then exits with a non-zero status code. This precise error formatting helps developers quickly identify and fix structural issues in their diagram JSON files.

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