# How the Schema Validation Loop Integrates with the Renderer in Archify

> Learn how Archify's schema validation loop integrates with the renderer. Ensure schema-compliant inputs reach SVG generation for error-free artifact checking.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-14

---

**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.

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

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

```javascript
// 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.