How to Debug Validation Failures in Archify: A Step-by-Step Troubleshooting Guide

Archify validates every diagram against Ajv-compiled JSON Schemas and outputs structured diagnostic receipts containing error codes, JSON paths, and element IDs that pinpoint exactly why validation failed.

When working with the tt-a1i/archify repository, architecture, workflow, and dataflow diagrams must conform to strict JSON Schema contracts. Understanding how to interpret validation failures allows you quickly resolve schema violations and restore diagram integrity.

Understanding Archify's Validation Architecture

How Ajv Schema Validation Works

According to the source code in archify/scripts/generate-validators.mjs, Archify pre-compiles all JSON Schemas using the Ajv 2020-12 specification. This script generates standalone validator code that the CLI imports at runtime, ensuring strict enforcement of type safety, required fields, and additional property constraints across all diagram types including architecture, workflow, dataflow, and lifecycle.

The Diagnostic Receipt Structure

When validation fails, archify/bin/archify.mjs emits a JSON receipt containing a diagnostics array. Each diagnostic entry includes:

• code: The specific validation rule that failed (e.g., schema/additionalProperties, schema/required, schema/type)
• path: An Ajv JSON Pointer indicating the exact location in the document IR
• elementId: Optional identifier mapping the error to a specific visual node in the diagram viewer

Step-by-Step Debugging Workflow

Generate a Machine-Readable Receipt

Run the validator with the --json flag to capture structured diagnostic data rather than human-readable summaries:

archify validate <type> path/to/document.json --json > receipt.json

Replace <type> with your diagram type (architecture, workflow, dataflow, or lifecycle). The receipt written to receipt.json contains the complete diagnostic trail needed to identify the failure point.

Interpret Diagnostic Codes

Inspect the receipt using jq to extract relevant diagnostic information:

jq '.diagnostics[] | {code, path, elementId}' receipt.json

Look for entries where code starts with schema/. The path field reveals which property in the Intermediate Representation (IR) violates the contract, while elementId (when present) identifies the exact node rendered in the visual viewer.

Cross-Reference Schema Documentation

All validation schemas reside under archify/schemas/. Consult archify/schemas/README.md to understand the contract requirements for your specific diagram type. If the diagnostic indicates a missing required field, open the corresponding schema file (e.g., architecture.schema.json) to verify the expected structure against your document's IR.

Check Schema Version Compatibility

Archify pins a schemaVersion (or schema_version) field to every IR. The file archify/skill-release.json stores the current schema version for all diagram types. A mismatch between your document's version and the validator's expected version triggers a schema/version error. Ensure your document's top-level version field matches the value declared in the schema folder (currently 1).

Force Degraded Mode to Isolate Ajv Issues

If you suspect the Ajv package is corrupted or missing, set the environment variable to force degraded mode:

ARCHIFY_DEGRADED=1 archify validate <type> path/to/document.json --json

In degraded mode, the validator skips JSON Schema validation and emits a warning: "ajv is not installed – skipping JSON-schema validation". This helps you determine whether the failure stems from genuine schema violations or tooling installation issues.

Visual Debugging Techniques

Highlight Offending Nodes

The diagnostic receipt's elementId field integrates with the Archify viewer to provide visual context:

archify open-artifact receipt.json

This command launches the visual UI focused on the offending node, revealing exactly which property broke the schema—such as an unexpected col value or a misspelled id field.

Common Validation Fixes

Based on typical errors found in archify/test/legend-contract.test.mjs, resolve issues by:

• Adding missing required properties: Ensure fields like label or type are present
• Correcting property types: Verify string vs number declarations
• Removing disallowed properties: Delete fields not permitted when additionalProperties: false is set
• Updating schema versions: Bump schemaVersion after upgrading Archify

Automated Repair Strategies

Apply Suggested Fixes Automatically

Some validation failures include repair suggestions in the supportedFixes list. Use the repair subcommand to apply fixes without manual editing:

archify repair <type> path/to/document.json --fix=route/via

This is particularly useful for common layout errors such as "edge-through-node" violations or routing issues.

Summary

• Run archify validate <type> <file> --json to generate machine-readable diagnostic receipts containing precise error locations
• Use jq to parse the diagnostics array for code, path, and elementId values that identify schema violations
• Reference archify/schemas/README.md and the specific schema files to understand contract requirements
• Verify schemaVersion in your document matches archify/skill-release.json to avoid version mismatch errors
• Set ARCHIFY_DEGRADED=1 to bypass Ajv validation when isolating tooling issues
• Launch archify open-artifact receipt.json to visualize offending nodes in the diagram viewer
• Apply automatic repairs using archify repair for supported fix types

Frequently Asked Questions

What does the "schema/additionalProperties" error mean in Archify?

This error indicates your diagram JSON includes properties not defined in the schema. When additionalProperties: false is set in schemas like architecture.schema.json, any extra fields beyond the documented contract trigger this violation. Remove the undefined property or check archify/schemas/README.md for the correct field names.

How do I find which schema version my Archify document uses?

Check the top-level schemaVersion or schema_version field in your document's JSON. Compare this value against the current version declared in archify/skill-release.json. If they differ, update your document to match the expected version, or downgrade Archify to a release compatible with your document's schema version.

Can I skip validation entirely if Ajv is causing issues?

Yes, set the environment variable ARCHIFY_DEGRADED=1 before running validation commands. This forces the CLI into degraded mode where it skips Ajv validation entirely, as implemented in archify/bin/archify.mjs. Use this only for debugging, as it disables all schema safety checks.

Where are the validation schemas defined in the Archify repository?

All JSON Schemas reside in the archify/schemas/ directory. The file archify/scripts/generate-validators.mjs compiles these schemas using Ajv 2020-12 during the build process. For human-readable documentation of required fields and validation rules, consult archify/schemas/README.md.

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