How to Create Custom Validators for Archify Diagram Schemas: A Complete Guide

To create custom validators for Archify diagram schemas, write a JSON-Schema definition in archify/schemas/, register the diagram type in the diagramTypes array within archify/scripts/generate-validators.mjs, execute npm run generate:validators to compile the schemas into renderers/shared/generated-validators.mjs, and validate instances at runtime using the validateSchema() helper from archify/renderers/shared/validator.mjs.

Archify is an open-source diagramming framework in the tt-a1i/archify repository that validates diagram JSON files by compiling JSON-Schema definitions into a single stand-alone ESM validator module. When you need to support a new diagram type or extend existing validation logic, you must integrate with this compilation pipeline to create custom validators for Archify diagram schemas that leverage the same diagnostic and error-handling infrastructure as built-in types.

Understanding Archify's Validation Architecture

Unlike runtime schema validation, Archify uses a compile-time validation strategy. The archify/scripts/generate-validators.mjs script reads all schema definitions listed in the diagramTypes array, instantiates an Ajv2020 compiler, and outputs optimized validation functions to renderers/shared/generated-validators.mjs. This generated module exports validator functions (e.g., workflow, custom) that perform synchronous validation without re-parsing schemas at runtime.

Key architectural components include:

• archify/schemas/*.schema.json – Source JSON-Schema definitions for each diagram type
• archify/scripts/generate-validators.mjs – Build script that compiles schemas using Ajv2020
• archify/renderers/shared/generated-validators.mjs – Auto-generated module containing compiled validation functions
• archify/renderers/shared/validator.mjs – Public API layer that wraps AJV errors into structured diagnostics

Step 1: Define Your JSON-Schema

Schema Location and Structure

Create a new file in archify/schemas/ using the .schema.json extension. The schema must declare a unique $id that matches the repository URL structure and use the JSON Schema Draft 2020-12 specification.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/tt-a1i/archify/schemas/custom.schema.json",
  "title": "My Custom Diagram",
  "type": "object"
}

Required Properties and References

Every Archify diagram schema must define three required properties: schema_version, diagram_type, and meta. Use const constraints to lock the version and type identifiers, and reference the shared meta definition via $ref.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/tt-a1i/archify/schemas/custom.schema.json",
  "title": "Custom Diagram",
  "type": "object",
  "required": ["schema_version", "diagram_type", "meta"],
  "properties": {
    "schema_version": { "const": 1 },
    "diagram_type": { "const": "custom" },
    "meta": { "$ref": "common.schema.json#/$defs/metaBase" },
    "payload": { "type": "object" }
  }
}

Reference archify/schemas/architecture.schema.json for a complete example of property definitions and nested references.

Step 2: Register the Diagram Type

Open archify/scripts/generate-validators.mjs and locate the diagramTypes array at line 13. Append your new type identifier (matching the diagram_type const value in your schema) to the array.

const diagramTypes = [
  'workflow',
  'sequence',
  'dataflow',
  'lifecycle',
  'architecture',
  'custom'   // ← added
];

The generator script iterates over this array to determine which schemas to compile into the validator module.

Step 3: Compile the Validators

Execute the generator command to compile all registered schemas:

npm run generate:validators

This command invokes archify/scripts/generate-validators.mjs, which:

1. Loads each schema from archify/schemas/{type}.schema.json
2. Compiles them using the Ajv2020 instance
3. Writes the standalone ESM module to renderers/shared/generated-validators.mjs

The generated file exports validation functions named after each diagram type.

Step 4: Validate Custom Diagrams at Runtime

Use the validateSchema function exported from archify/renderers/shared/validator.mjs (defined at line 38) to validate diagram instances. This helper automatically selects the correct validator based on the diagram type string and throws a DiagnosticError containing structured error information if validation fails.

import { validateSchema } from '../renderers/shared/validator.mjs';
import myDiagram from './my-diagram.json' assert { type: 'json' };

try {
  validateSchema('custom', myDiagram);
  console.log('✅ diagram is valid');
} catch (e) {
  console.error('❌ validation failed:', e.message);
  // e.diagnostics contains annotated error objects with paths and fixes
}

The validator normalizes AJV output into a consistent diagnostic format used by the CLI (archify/bin/archify.mjs) and renderers.

Extending Error Handling and Fixes

For custom keywords or specialized validation logic, extend the supportedFixes mapping in archify/renderers/shared/validator.mjs (lines 56-68). This mapping instructs the error formatter how to suggest automatic repairs or provide contextual hints for specific validation failures. Each entry maps a JSON-Schema keyword to a fix function or template.

Summary

• Archify compiles schemas at build time using generate-validators.mjs and Ajv2020, outputting renderers/shared/generated-validators.mjs
• Place new schemas in archify/schemas/ with proper $id, schema_version, and diagram_type constants
• Register types by adding the identifier to the diagramTypes array in generate-validators.mjs
• Validate instances using validateSchema() from validator.mjs, which handles error formatting via DiagnosticError
• Extend diagnostics by modifying the supportedFixes mapping for custom keywords

Frequently Asked Questions

What JSON-Schema draft does Archify use?

Archify uses JSON Schema Draft 2020-12 as specified in the $schema property of its definition files. The generator script explicitly instantiates Ajv2020 to ensure compatibility with 2020-12 keywords like $dynamicRef and prefixItems.

Where are the compiled validator functions stored?

After running npm run generate:validators, the compiled functions are stored in renderers/shared/generated-validators.mjs. This file exports named functions corresponding to each string in the diagramTypes array (e.g., export function custom(data) { ... }).

How do I handle validation errors programmatically?

The validateSchema function throws a DiagnosticError containing a diagnostics property. This array includes structured objects with path, message, and optional fix suggestions. Catch this error in your renderer or CLI tool to display user-friendly messages or attempt automatic repairs.

Can I extend existing schemas without creating a new diagram type?

Yes. Modify the existing .schema.json file in archify/schemas/ and regenerate validators. If you need to share definitions across schemas, place reusable components in $defs within common.schema.json and reference them using $ref: "common.schema.json#/$defs/yourDef".

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