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

> Fix Archify schema validation errors with 5 repair strategies. Learn to correct types, add missing fields, and remove disallowed properties using JSON-Pointer paths.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-15

---

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

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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:

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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:

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

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

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) shows version `1`:

```json
{
  "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

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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | Schema documentation and strict mode configuration |
| [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md).