How Archify's JSON IR Schema Validation Works: A Technical Deep Dive

Archify validates JSON Intermediate Representation through a four-stage pipeline using AJV-generated standalone validators, runtime wrappers with annotated error paths, and strict schema-version enforcement.

The tt-a1i/archify repository implements a rigorous JSON-IR validation system that ensures structural correctness before any diagram rendering occurs. This fail-closed pipeline guarantees that only well-formed IR documents reach the rendering stage while providing precise diagnostics for debugging.

Schema Definitions and Structure

Archify supports five diagram types—workflow, sequence, dataflow, lifecycle, and architecture—each governed by dedicated JSON-Schema files in archify/schemas/. The workflow schema at archify/schemas/workflow.schema.json mandates top-level fields including schema_version, diagram_type, meta, lanes, nodes, and edges.

The schema strictly limits schema_version to enum values 1 or 2, enabling versioned contracts that support legacy IRs through migration utilities. Shared reusable definitions for id, locale, and legendEntry reside in archify/schemas/common.schema.json and are composed into specific diagram schemas during the build process.

Build-Time Validator Generation

The pipeline compiles schemas into standalone validators using AJV 2020. The Node.js script archify/scripts/generate-validators.mjs reads every schema file, merges definitions from common.schema.json, and outputs bundled functions to archify/renderers/shared/generated-validators.mjs.

The generator applies strict configuration:

• allErrors: true captures all validation failures simultaneously
• strict: true enforces rigorous schema adherence
• Embedded UCS-2 length helper eliminates runtime import dependencies

Generate validators via npm:

npm run generate:validators

This executes node archify/scripts/generate-validators.mjs, rewriting the output file only when source schemas change to avoid unnecessary builds.

Runtime Validation with Annotated Errors

The module archify/renderers/shared/validator.mjs imports generated validators and exposes validateSchema(diagramType, data). This wrapper performs structural validation and converts AJV errors into human-readable DiagnosticError instances.

Example validation workflow:

import { validateSchema } from './archify/renderers/shared/validator.mjs';
import fs from 'node:fs';

const ir = JSON.parse(fs.readFileSync('my-workflow.json', 'utf8'));

try {
  validateSchema('workflow', ir);
  console.log('✅ IR is valid – safe to render');
} catch (e) {
  console.error('❌ Validation failed:\n', e.message);
  // e.diagnostics contains structured error objects for tooling
}

When validation fails, the wrapper produces annotated paths that combine JSON pointers with element identifiers. Instead of raw indices like /nodes/3/label, errors reference /nodes/3 (id/label: "router") /label by extracting the nearest id or label field. The system also suggests supported fixes such as "remove unsupported property" or "add required property" for automated correction workflows.

Degraded Mode and Version Enforcement

The mandatory schema_version field ensures the renderer selects appropriate validation logic and migration paths. In degraded mode—when AJV is not installed at runtime—the wrapper prints a warning and skips schema validation, though layout and composition checks continue executing.

// Degraded mode behavior when AJV is unavailable
process.env.NODE_ENV = 'production'; 
validateSchema('workflow', ir); 
// Logs: 'Running without schema validation – check your dependencies.'

This design prevents crashes in constrained environments while maintaining explicit warnings that type-checking is disabled. When validators are present, invalid IR aborts rendering with a non-zero exit status.

Summary

• Schema definitions in archify/schemas/ enforce structure for five diagram types using versioned contracts via schema_version enums.
• Build-time generation via archify/scripts/generate-validators.mjs produces standalone AJV validators with allErrors: true and zero runtime dependencies.
• Runtime wrapper at archify/renderers/shared/validator.mjs provides validateSchema() with annotated error paths and actionable fix suggestions.
• Fail-closed security aborts rendering with non-zero exit status when validation fails.
• Degraded mode gracefully handles missing AJV installations with warnings while preserving layout validation.

Frequently Asked Questions

What JSON Schema draft does Archify use for validation?

Archify uses AJV 2020 to compile and validate schemas, as implemented in archify/scripts/generate-validators.mjs. The 2020 draft specification provides advanced validation features required for complex nested structures in diagram IRs, including the schema composition patterns found in common.schema.json.

How does Archify handle validation errors?

The runtime wrapper converts AJV errors into DiagnosticError instances with annotated paths that include element identifiers like id or label. For example, errors reference /nodes/3 (id/label: "router") /label instead of raw array indices. Each error object includes suggestedFixes such as "add required property" or "remove unsupported property" for integration with developer tooling.

Where are the generated validators stored in the codebase?

The build script writes compiled validators to archify/renderers/shared/generated-validators.mjs. This ES module exports standalone validation functions for each diagram type, generated with strict: true settings for comprehensive error reporting. The file is overwritten only when schema source files change.

What happens when AJV is not available at runtime?

When AJV is unavailable, Archify enters degraded mode: the runtime wrapper skips schema validation but continues with layout and composition checks, printing a warning to stderr. This ensures diagrams can still render in constrained environments while explicitly alerting users that structural type-checking is disabled.

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