# Archify Schema Validation: How JSON Schemas Enforce Data Integrity

> Archify uses JSON Schema validation with AJV to ensure data integrity for diagrams. Learn how this enforces data consistency at compile time, in the CLI, and during migrations.

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

---

**Archify validates all diagram data using JSON Schema definitions enforced by the `validateSchema` function in `validator.mjs`, which runs AJV validation against workflow and other diagram types at compile time, in the CLI, and during migrations.**

Archify, an open-source diagram-as-code toolkit in the `tt-a1i/archify` repository, implements strict **Archify schema validation** to ensure every generated workflow and diagram conforms to expected structural contracts. The validation layer catches malformed data early using pre-compiled JSON schemas executed through the AJV validator, preventing invalid configurations from propagating through the render pipeline.

## The Core Validation Engine in `validator.mjs`

The heart of **Archify schema validation** resides in `archify/renderers/shared/validator.mjs`. This module exports the `validateSchema` function, which accepts two parameters:

- **`diagramType`** (string): Identifies the schema to apply, such as `"workflow"`.
- **`data`** (object): The JavaScript object to validate against the selected schema.

Internally, `validateSchema` selects a pre-compiled JSON schema based on the `diagramType` and executes it through AJV, the industry-standard JSON Schema validator for JavaScript. If the supplied `diagramType` does not match any registered schema, the function immediately throws a descriptive error:

```javascript
throw new Error(`validateSchema: unknown diagram type "${diagramType}"`);

```

This strict checking ensures that only explicitly supported diagram categories pass through the validation gate, maintaining type safety across the entire toolchain.

## Where Validation Is Enforced in the Codebase

**Archify schema validation** is not confined to a single entry point; it is integrated at multiple critical junctures to guarantee data integrity throughout the application lifecycle.

### Workflow Compilation (`workflow-compiler.mjs`)

In `archify/renderers/workflow/workflow-compiler.mjs` at line 779, the compiler invokes validation immediately after resolving the complete workflow structure. The call `validateSchema('workflow', qualityResolvedWorkflow)` verifies that the final compiled workflow object adheres to the workflow JSON schema before any rendering occurs. This prevents runtime errors caused by malformed node connections or missing required fields in the output.

### Command-Line Interface (`cli.mjs`)

The CLI entry point in `archify/renderers/shared/cli.mjs` (line 23) performs **Archify schema validation** on any diagram loaded from the filesystem. When users execute a command with a diagram file, the code extracts the diagram type and data, then passes them to `validateSchema(diagramType, diagram)`. This ensures that locally authored diagrams meet the same structural standards as programmatically generated ones before processing continues.

### Migration Scripts (`workflow-v2.mjs`)

Data migrations also leverage the validation layer to confirm transformations produce valid output. In `archify/migrations/workflow-v2.mjs` at line 30, the migration script calls `validateSchema('workflow', workflow)` immediately after converting a v1 workflow to the v2 format. This verification step guarantees that upgraded schemas remain backward-compatible and structurally sound before persistence.

## Practical Examples of Schema Validation

### Validating a Workflow Programmatically

You can invoke the validation logic directly in custom scripts to verify workflow objects before submission:

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

const myWorkflow = {
  nodes: [{ id: 'start', type: 'trigger' }],
  edges: []
};

// Throws an error if the object violates the workflow schema
validateSchema('workflow', myWorkflow);

```

### CLI Validation in Practice

When using the Archify CLI, validation runs automatically against supplied JSON files:

```bash

# Validates the JSON against the workflow schema before compilation

archify --type workflow ./definitions/my-workflow.json

```

If the input fails **Archify schema validation**, the command exits with a non-zero status and prints the AJV validation errors, allowing immediate correction.

### Validating Migrated Data

During migration workflows, explicit validation ensures data integrity after transformation:

```javascript
import { validateSchema } from './archify/renderers/shared/validator.mjs';
import { migrateV1toV2 } from './archify/migrations/workflow-v2.mjs';

const legacyWorkflow = loadLegacyWorkflow(); // Load v1 structure
const modernWorkflow = migrateV1toV2(legacyWorkflow);

// Confirm the migration produced valid v2 schema output
validateSchema('workflow', modernWorkflow);
saveWorkflow(modernWorkflow);

```

## Summary

- **Archify schema validation** is centralized in `archify/renderers/shared/validator.mjs` via the `validateSchema` function.
- The system uses AJV to enforce JSON Schema compliance on workflow and diagram objects.
- Validation triggers at compile time in `workflow-compiler.mjs`, at the CLI entry point in `cli.mjs`, and during data migrations in `workflow-v2.mjs`.
- Unknown diagram types trigger explicit errors, preventing undefined behavior from unvalidated data structures.

## Frequently Asked Questions

### What schema format does Archify use for validation?

Archify uses standard **JSON Schema** definitions processed through the AJV (Another JSON Schema Validator) library. These schemas are pre-compiled and mapped to specific diagram types like `"workflow"` within the `validator.mjs` module.

### Which diagram types does Archify validate?

The validation system supports specific diagram categories identified by string keys. The analysis confirms `"workflow"` is explicitly validated, with the infrastructure in place to support additional types through the `diagramType` parameter in `validateSchema`. Unknown types trigger a runtime error.

### At what stages does Archify validate data?

Validation occurs at three distinct stages: during workflow compilation in `workflow-compiler.mjs` (line 779), during CLI execution in `cli.mjs` (line 23), and during data migrations in `workflow-v2.mjs` (line 30). This multi-layer approach ensures data integrity across compilation, user input, and schema evolution.

### How does Archify handle unknown diagram types during validation?

When `validateSchema` receives a `diagramType` that does not match any registered schema, it immediately throws an `Error` with the message `validateSchema: unknown diagram type "${diagramType}"`. This strict enforcement prevents the system from attempting to validate or process unsupported data structures.