How Archify Validates Schemas at Runtime Without npm Dependencies

Archify compiles JSON schemas into standalone JavaScript functions during the build process, bundling these pre-generated validators directly into the repository so that runtime validation requires no external npm packages.

The tt-a1i/archify project eliminates runtime dependency bloat by shifting schema validation work from execution time to build time. Instead of bundling a JSON Schema validator like Ajv in production, Archify generates pure JavaScript validation functions that ship with the source code, enabling zero-dependency runtime checks for all diagram types.

Build-Time Code Generation Strategy

Archify's architecture relies on pre-generating validator functions before distribution. During the build step, the project runs Ajv (Another JSON Schema Validator) locally to parse each diagram schema and compile it into a tiny, optimized JavaScript function. These compiled functions are written to archify/renderers/shared/generated-validators.mjs, creating a static snapshot of validation logic that requires zero schema compilation overhead when Archify executes.

The Generated Validators File

The file archify/renderers/shared/generated-validators.mjs contains the build-step output. Each exported function corresponds to a specific diagram type—such as workflow or sequence—hardcoded as plain JavaScript rather than schema objects. This module is committed directly to the repository, ensuring consumers receive validation logic without installing or configuring Ajv.

Runtime Validation Architecture

At runtime, Archify loads these pre-generated functions through a thin wrapper that handles lookup, execution, and error transformation.

The Core Validator Module

The module archify/renderers/shared/validator.mjs implements the main validation entry point:

import * as validators from './generated-validators.mjs';

export function validateSchema(diagramType, data) {
  const validator = validators[diagramType];
  if (!validator) {
    throw new Error(`Unknown diagram type: ${diagramType}`);
  }
  
  const isValid = validator(data);
  if (!isValid) {
    throwDiagnosticError(validator.errors);
  }
}

When validateSchema(diagramType, data) is invoked, it looks up the appropriate validator using the diagram type as a key. If validation succeeds, the function returns silently; otherwise, it triggers diagnostic error processing.

Error Transformation and Diagnostics

Rather than exposing raw Ajv error objects, Archify transforms validation failures into rich diagnostic messages. The validator.mjs module processes the validate.errors array, converting cryptic schema paths into annotated paths with suggested fixes and diagnostic codes. It then throws a custom throwDiagnosticError containing these structured diagnostics, providing actionable feedback without leaking Ajv implementation details.

Implementation Examples

Archify's validation layer integrates across CLI tools, compilers, and programmatic APIs without requiring npm install steps for validation dependencies.

CLI Validation

The command-line interface validates diagrams before processing, as implemented in archify/renderers/shared/cli.mjs:

import { validateSchema } from './validator.mjs';
import { readFileSync } from 'fs';

const diagramType = process.argv[2];          // e.g., "workflow"
const diagramPath = process.argv[3];
const diagram = JSON.parse(readFileSync(diagramPath, 'utf8'));

validateSchema(diagramType, diagram);         // throws if invalid
console.log('✅ Diagram is valid');

Workflow Compiler Integration

Before compiling a workflow, the compiler ensures data integrity. In archify/renderers/workflow/workflow-compiler.mjs:

import { validateSchema } from '../shared/validator.mjs';
import { compileWorkflow } from './compiler.mjs';

export async function compileWorkflowHandler(diagramType, workflow) {
  // Runtime validation (no npm deps)
  validateSchema(diagramType, workflow);
  // …proceed with compilation…
  return compileWorkflow(workflow);
}

Programmatic API Usage

Any Node.js script can import the validator directly for zero-dependency validation:

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

try {
  validateSchema('sequence', mySequenceObject);
  // safe to use the object now
} catch (e) {
  console.error(e.message);   // detailed diagnostics
}

Benefits of Zero-Dependency Validation

Eliminating Ajv from the runtime dependency tree provides distinct technical advantages:

• Reduced Installation Footprint: End users download only necessary source files, not a full JSON Schema validation library
• Faster Startup Times: No runtime schema compilation or module resolution overhead
• Enhanced Reliability: No risk of dependency version conflicts or npm registry availability issues affecting validation functionality
• Immutable Behavior: The generated-validators.mjs file ensures validation logic is consistent across all installations

Summary

• Build-time generation: Archify uses Ajv during development to compile schemas into pure JavaScript functions stored in archify/renderers/shared/generated-validators.mjs
• Zero-dependency runtime: The archify/renderers/shared/validator.mjs module imports these functions and executes them without external packages
• Rich error handling: Validation failures are transformed via throwDiagnosticError into annotated paths with suggested fixes
• Universal integration: This architecture supports CLI tools, workflow compilers, and programmatic APIs in the tt-a1i/archify repository without runtime npm dependencies

Frequently Asked Questions

How does Archify validate schemas without requiring npm dependencies at runtime?

Archify runs Ajv exclusively during the build process to compile JSON schemas into standalone JavaScript functions. These functions are bundled in archify/renderers/shared/generated-validators.mjs and committed to the repository. At runtime, the system executes these pre-compiled functions directly, eliminating the need to install or load Ajv in production environments.

Can I modify schemas or add new diagram types without breaking the zero-dependency model?

Yes, but you must regenerate the validator file. After modifying schema definitions, run the build script to recompile archify/renderers/shared/generated-validators.mjs. The new validators remain pure JavaScript functions, preserving the zero-dependency runtime characteristic while supporting your updated schemas.

Are pre-generated validators slower than runtime compilation?

No. The generated validator functions in generated-validators.mjs are highly optimized JavaScript code that executes faster than runtime schema compilation. Since there is no parsing or compilation step during validation calls, runtime performance exceeds traditional Ajv implementations that compile schemas on-the-fly.

How does Archify handle validation errors compared to standard Ajv output?

Instead of returning raw Ajv error objects, the validateSchema function catches validation failures and passes them through a diagnostic transformer. This generates rich error messages with annotated paths, suggested fixes, and diagnostic codes via throwDiagnosticError, making debugging significantly easier than interpreting standard JSON Schema validation errors.

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