# What Is the Role of validator.mjs in Archify? Schema Validation Deep Dive

> Discover how Archify's validator.mjs ensures diagram definitions meet schemas. Learn about schema validation and enhanced error diagnostics.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-05

---

**The `validator.mjs` module serves as Archify's central schema-validation engine, importing pre-compiled JSON-Schema validators from `generated-validators.mjs` and enriching raw validation errors with identity hints and actionable diagnostics to ensure diagram definitions conform to expected schemas.**

The `validator.mjs` file is a critical component in the **Archify** diagram rendering pipeline. Located at `archify/renderers/shared/validator.mjs`, this module bridges raw JSON-Schema validation and user-friendly error reporting, ensuring that network, tree, and other diagram types conform to their respective schemas while providing developers with precise, actionable feedback.

## Core Responsibilities of validator.mjs in Archify

### Loading Pre-Compiled JSON-Schema Validators

The module imports a set of pre-compiled validators from `generated-validators.mjs` at `archify/renderers/shared/generated-validators.mjs`. These validators are keyed by diagram type (e.g., `network`, `tree`), allowing the system to select the appropriate schema enforcement logic based on the specific diagram being rendered.

### Validating Diagram Data with validateSchema()

The exported `validateSchema(diagramType, data)` function serves as the primary entry point. It accepts a **diagram type** string and a **data** object, selects the corresponding pre-compiled validator, and executes validation against the supplied diagram description according to the source code in the Archify repository.

### Enriching Error Information with Identity Hints

When validation fails, the module transforms cryptic JSON pointers into human-readable paths. It walks the `instancePath` to locate the nearest object carrying an `id` or `label` property, attaching this as an **annotated path** hint. For example, instead of displaying `/nodes/3/label`, the error displays `/nodes/3 (id/label: "router") /label`, immediately identifying the problematic node to developers.

### Generating Actionable Diagnostic Payloads

Each validation error generates a structured diagnostic object containing:

- **Error code** and **severity** level
- **Subject** information (diagram type and path)
- **Evidence** (failing keyword, expected values)
- **Supported fixes** (e.g., "remove unsupported property", "add required property")

## Integration with Archify's Diagnostic System

### Throwing Rich Diagnostic Errors

If validation fails, `validator.mjs` calls `throwDiagnosticError` from `diagnostics.mjs` at `archify/renderers/shared/diagnostics.mjs`, passing the enriched message and diagnostics array. This creates a `DiagnosticError` that the rest of Archify consumes to surface errors to users or LLM-based fixers, ensuring validation failures halt rendering while providing recovery context.

## Practical Usage: Validating Diagrams with validator.mjs

The following example demonstrates how to use the `validateSchema` function to verify a network diagram definition:

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

// A sample diagram description (replace with your own data)
const networkDiagram = {
  nodes: [
    { id: 'router', label: 'Router', type: 'router' },
    { id: 'pc1', label: 'PC 1', type: 'computer' }
  ],
  links: [{ source: 'router', target: 'pc1' }]
};

try {
  // Validate a "network" diagram
  validateSchema('network', networkDiagram);
  console.log('Diagram is valid ✅');
} catch (err) {
  // err is a DiagnosticError containing a rich diagnostics array
  console.error(err.message);
  console.error('Diagnostics:', err.diagnostics);
}

```

When the data violates the schema (e.g., missing a required property), the catch block receives a message such as:

```

network schema validation failed:
  /nodes/0 (id/label: "router") /type must be equal to one of ["router","switch"]

```

The accompanying `diagnostics` array lists the error code (`schema/type`), severity, and suggested fixes (e.g., `use "router"` at the offending path), enabling automated or manual remediation.

## Summary

- **`validator.mjs`** acts as the central schema-validation module for Archify's diagram rendering pipeline.
- It loads pre-compiled validators from `generated-validators.mjs`, selecting the appropriate validator based on diagram type.
- The `validateSchema()` function validates diagram data and enriches errors with **identity hints** by analyzing `instancePath` for `id` or `label` properties.
- It generates structured **diagnostic payloads** containing error codes, severity, evidence, and supported fixes.
- Validation failures trigger `throwDiagnosticError` from `diagnostics.mjs`, surfacing detailed diagnostics to users or LLM-based fixers.

## Frequently Asked Questions

### What is the primary function exported by validator.mjs?

The `validateSchema(diagramType, data)` function is the main export. It accepts a diagram type string (such as `network` or `tree`) and a data object, then validates the data against the corresponding pre-compiled JSON-Schema validator loaded from `generated-validators.mjs`.

### How does validator.mjs improve error messages compared to standard JSON Schema validation?

Rather than exposing raw JSON pointers (e.g., `/nodes/3/type`), the module walks the `instancePath` to find the nearest identifiable object (via `id` or `label` properties) and constructs an **annotated path** (e.g., `/nodes/3 (id/label: "router") /type`). This allows developers to immediately locate problematic elements within complex diagram structures.

### Which files does validator.mjs depend on in the Archify repository?

The module imports validator functions from `archify/renderers/shared/generated-validators.mjs` and error-throwing utilities from `archify/renderers/shared/diagnostics.mjs`. These dependencies enable the separation of schema definitions, validation logic, and error presentation within the Archify architecture.

### What happens when validator.mjs detects a schema violation?

The module constructs a detailed diagnostic payload containing the error code, severity, human-readable message, subject path, evidence, and suggested fixes. It then calls `throwDiagnosticError` to raise a `DiagnosticError` that includes this payload, causing the Archify rendering pipeline to halt and surface the error to the user or an automated fixer.