How the Schema Validation Loop Integrates with the Renderer in Archify

Archify couples schema validation to the renderer via a CLI orchestration layer that validates JSON diagrams against AJV-generated validators before dispatching to type-specific renderers, ensuring only schema-compliant inputs reach the SVG generation phase.

The archify repository implements a strict validation-first pipeline for diagram rendering. The schema validation loop is tightly integrated with the renderer through the shared CLI module located at archify/renderers/shared/cli.mjs, which acts as a gatekeeper that runs pre-generated AJV validators immediately before invoking the rendering logic.

The Validation-First Pipeline Architecture

Archify processes every diagram through a strict three-step sequence enforced by the CLI. This design guarantees that schema validation executes before any rendering takes place, while maintaining tight coupling between the validation logic and the renderer dispatch mechanism.

Step 1: Diagram Loading and Type Resolution

The pipeline begins when loadDiagram() reads the input JSON file and determines the diagram type—such as workflow, sequence, lifecycle, or dataflow. This function resolves the appropriate renderer directory and returns both the raw diagram data and the type identifier.

Step 2: The Schema Validation Loop

Immediately after loading, the CLI invokes validateSchema(diagramType, diagram) from archify/renderers/shared/validator.mjs. This function implements the core validation loop:

1. Validator Lookup: It retrieves a pre-generated validator from archify/renderers/shared/generated-validators.mjs using the diagram type as a key (e.g., validators.workflow).
2. Schema Validation: It runs the AJV validator against the raw JSON data.
3. Error Handling: If validation returns false, the helper formatErrors() constructs a readable error message and the CLI throws an error, aborting the run before any rendering code executes.

This loop runs before the renderer is imported or invoked, ensuring that only conformant diagrams are passed to the rendering subsystem.

Step 3: Renderer Dispatch and Artifact Checking

Once the schema is accepted, the CLI dynamically imports the specific renderer entry point (e.g., render-workflow.mjs, render-sequence.mjs) and invokes its top-level rendering functions. After the SVG is written via writeDiagram(), a separate post-process script (archify/scripts/check-render-output.mjs) performs sanity checks on the generated artifacts. Because validation already occurred, this step only verifies rendering outputs—such as ensuring no temporary directories were left behind—rather than checking structural correctness.

Validator Implementation Details

The validation system relies on auto-generated AJV validators stored in archify/renderers/shared/generated-validators.mjs. The central validation entry point in archify/renderers/shared/validator.mjs maps diagram types to these generated validators and standardizes error formatting.

// archify/renderers/shared/validator.mjs
import { workflow, sequence, lifecycle, dataflow } from './generated-validators.mjs';
const validators = { workflow, sequence, lifecycle, dataflow };

export function validateSchema(diagramType, data) {
  const validate = validators[diagramType];
  if (!validate) throw new Error(`unknown diagram type "${diagramType}"`);
  if (!validate(data)) {
    throw new Error(`${diagramType} schema validation failed:\n${formatErrors(validate.errors, data)}`);
  }
}

Each type-specific renderer (such as archify/renderers/workflow/render-workflow.mjs) performs additional layout-specific checks after the initial schema validation, then generates the SVG artifact via writeDiagram().

Code Examples

The following simplified extraction from archify/renderers/shared/cli.mjs demonstrates how the validation loop is integrated with the renderer dispatch:

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

const { diagram, diagramType } = loadDiagram({ /* … */ });
validateSchema(diagramType, diagram);   // ← schema validation loop

// If the call succeeds, the specific renderer is required:
import(`./${diagramType}/render-${diagramType}.mjs`).then(mod => {
  mod.render(diagram);                 // ← render step
});

The renderer entry point then handles layout validation and file output:

// archify/renderers/workflow/render-workflow.mjs
import { loadDiagram, writeDiagram } from '../shared/cli.mjs';
import { validateWorkflow } from './render-workflow.mjs';

const { diagram: workflow } = loadDiagram({ diagramType: 'workflow' });
validateWorkflow();                     // additional layout validation
writeDiagram({ /* … */ });              // produces SVG artifact

Summary

• Validation Location: The schema validation loop runs in archify/renderers/shared/cli.mjs immediately after loadDiagram() and before any renderer code is imported.
• Validator Source: AJV-generated validators are imported from archify/renderers/shared/generated-validators.mjs and invoked via validateSchema().
• Abort Mechanism: Failed validation triggers an immediate error via formatErrors(), preventing the renderer from executing.
• Artifact Checking: Post-render verification in archify/scripts/check-render-output.mjs assumes schema validity and only checks output artifacts.
• Entry Point: The CLI orchestration at archify/bin/archify.mjs wires together loading, validation, rendering, and artifact checking into a unified pipeline.

Frequently Asked Questions

Where does the schema validation loop occur in the Archify pipeline?

The schema validation loop executes immediately after diagram loading in archify/renderers/shared/cli.mjs. The CLI calls validateSchema(diagramType, diagram) before dynamically importing or invoking any type-specific renderer, ensuring that only schema-compliant JSON reaches the rendering logic.

What happens if a diagram fails schema validation?

If validation fails, the validateSchema() function calls formatErrors() to build a readable error message and throws an error that aborts the entire run. The renderer is never imported or executed, and no SVG artifacts are generated.

How does the CLI know which validator to use for a specific diagram type?

The CLI uses the diagramType string (e.g., "workflow", "sequence") returned by loadDiagram() as a key to look up the corresponding validator in the validators object imported from archify/renderers/shared/generated-validators.mjs. Each diagram type has a pre-generated AJV validator mapped to this registry.

Why is artifact checking performed after schema validation rather than before?

Artifact checking runs after rendering because it verifies the outputs of the rendering process (such as ensuring no temporary directories remain). Since schema validation already guaranteed structural correctness of the input JSON, the post-process script (archify/scripts/check-render-output.mjs) only needs to validate the generated files, not the input data structure.

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