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

> Learn to create custom validators for Archify diagram schemas. Follow this guide to define, register, compile, and validate your schemas for robust data integrity. Get started today!

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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`](https://github.com/tt-a1i/archify/blob/main/.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.

```json
{
  "$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`.

```json
{
  "$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`](https://github.com/tt-a1i/archify/blob/main/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.

```javascript
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:

```bash
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.

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and reference them using `$ref: "common.schema.json#/$defs/yourDef"`.