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

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:

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.

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