Archify Schema Validation: How JSON Schemas Enforce Data Integrity

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:

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:

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:

# 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:

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.

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