How to Handle Schema Validation Errors in Archify: 5 Repair Strategies

Archify uses AJV-generated JSON-Schema validators in strict mode to catch validation errors before rendering, providing JSON-Pointer paths to each violation that you can fix by correcting types, adding required fields, or removing disallowed properties.

Handling schema validation errors in Archify requires understanding how the framework validates JSON IR documents at runtime and what repair options are available when validation fails. The tt-a1i/archify repository implements a robust validation pipeline using pre-compiled AJV validators, with fallback mechanisms for degraded environments.

How Archify Validates JSON IR Documents

The AJV Validator Generation Pipeline

Archify compiles all JSON schemas into standalone validators during development. In archify/scripts/generate-validators.mjs, the build script imports AJV 2020-12 in strict mode and bundles the compiled schemas into a dependency-free validator that ships with each skill package:

// From archify/scripts/generate-validators.mjs
import Ajv from 'ajv';

const ajv = new Ajv({
  strict: true,
  code: { esm: true },
  allErrors: true
});

This approach ensures zero runtime dependencies on AJV while maintaining strict validation guarantees.

Runtime Validation and Error Reporting

When runSkill() executes, it invokes the pre-compiled validator against the supplied IR. Each validation failure produces an error with:

• A JSON-Pointer path to the offending element (e.g., /nodes/3)
• The element ID and label for context (e.g., id/label: "router")
• A descriptive message explaining the constraint violation

As shown in CHANGELOG.md, a typical error appears as:

/nodes/3 (id/label: "router"): must have required property 'type'

On validation failure, Archify exits with non-zero status, preventing corrupted renders.

Degraded Mode Without AJV

For environments where the validator bundle is unavailable, Archify falls back to degraded mode as implemented in archify/renderers/shared/geometry.mjs. This mode skips schema validation but retains structural guards checking for valid arrays, finite coordinates, and required top-level fields:

// From archify/renderers/shared/geometry.mjs
export const asArray = (v) => Array.isArray(v) ? v : [];
export const isFinitePoint = (p) => Array.isArray(p) && p.every(Number.isFinite);

Common Archify Schema Validation Error Types

Error Category	Trigger	Example Message
Missing required properties	Omitted mandatory field in schema	/nodes/3 (id/label: "router"): must have required property 'type'
Wrong data type	Value doesn't match schema type	/cards/2: should be array
Additional properties	Unknown property with additionalProperties: false	/nodes/5: must NOT have additional properties

AJV strict mode also catches schema-level errors like duplicate $id values or invalid $ref pointers, ensuring published schemas remain sound per archify/schemas/README.md.

5 Strategies for Repairing Schema Validation Errors

1. Inspect the Error Path

The JSON-Pointer and element metadata provide precise location data. Navigate to the offending node using the path:

// Example error parsing
const errorPath = '/nodes/3/props/color';
const segments = errorPath.split('/').filter(Boolean); // ['nodes', '3', 'props', 'color']

2. Add Missing Required Fields

Consult the schema in archify/schemas/ to identify mandatory properties. For nodes, type, id, and label are typically required:

// Before: missing 'type'
{
  "nodes": [{ "id": "router", "label": "Router Node" }]
}

// After: valid
{
  "nodes": [{ "id": "router", "label": "Router Node", "type": "router" }]
}

3. Correct Data Types

Match values to schema expectations. Convert strings to arrays, ensure numbers aren't passed as strings:

// Before: wrong type for cards
{ "cards": "single-card" }

// After: array as required
{ "cards": ["single-card"] }

4. Remove or Extend Disallowed Properties

AJV's default additionalProperties: false rejects unknown fields. Either remove custom metadata or extend the schema following the extension guidelines in archify/schemas/README.md.

5. Upgrade Schema Version When Needed

Archify pins IR to a schemaVersion field. The example in examples/checkout-platform-delta.receipt.json shows version 1:

{
  "schemaVersion": 1,
  "nodes": []
}

Increment this field and adjust IR structure when new schema versions release.

Handling Errors Programmatically and via CLI

Programmatic Validation and Repair

import { runSkill } from 'archify';
import fs from 'fs';

const ir = JSON.parse(fs.readFileSync('my-diagram.json', 'utf8'));

try {
  runSkill(ir, { renderer: 'svg' });
} catch (e) {
  // AJV errors include the full path and message
  console.error('Schema validation failed:', e.message);
  // Parse the path to auto-suggest fixes
  const match = e.message.match(/^\/(.+?) \(/);
  if (match) {
    console.log(`Check element at path: ${match[1]}`);
  }
}

CLI Validation with Explicit Flags

# Force validation even in degraded mode

archify render my-diagram.json --renderer svg --validate

# Expected failure output:

# ❌ schema error: /nodes/2 (id/label: "service"): must have required property 'type'

Key Files for Understanding Validation

File	Purpose
archify/scripts/generate-validators.mjs	AJV validator bundle generation in strict mode
archify/schemas/README.md	Schema documentation and strict mode configuration
archify/package.json	AJV dependency declaration (^8.17.1)
archify/test/layout-rules.test.mjs	Test cases triggering additionalProperties errors
archify/renderers/shared/geometry.mjs	Degraded-mode structural guards
examples/checkout-platform-delta.receipt.json	Live example with schemaVersion: 1

Summary

• Archify validates every IR document using pre-compiled AJV validators in strict mode before rendering
• Errors include JSON-Pointer paths and element metadata for precise debugging
• Degraded mode provides fallbacks when AJV is unavailable, with basic structural checks
• Repair by: inspecting paths, adding required fields, correcting types, removing disallowed properties, or upgrading schema versions
• CLI and programmatic APIs both support explicit validation with detailed error reporting

Frequently Asked Questions

How do I identify which field is causing a schema validation error in Archify?

Archify's AJV errors include a JSON-Pointer path and element identifier. The path (e.g., /nodes/3/props) tells you the exact location, while the element ID (e.g., id/label: "router") identifies the specific node. Parse e.message programmatically or use a JSON editor to navigate to the failing field.

Can I run Archify without AJV installed?

Yes. Archify operates in degraded mode when the AJV validator bundle is missing. As implemented in archify/renderers/shared/geometry.mjs, structural guards check for required fields and valid geometry, though full schema validation is skipped. Run with --validate flag to force validation errors if bundle is present.

Why does Archify reject properties I added for my own use?

AJV runs with additionalProperties: false by default. To retain custom metadata, either remove the fields from your IR or extend the relevant schema in archify/schemas/ following the extension patterns documented in archify/schemas/README.md.

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