# How to Debug Validation Failures in Archify: A Step-by-Step Troubleshooting Guide > Debug validation failures in Archify with this step by step guide. Learn to interpret diagnostic receipts and resolve errors quickly using error codes, JSON paths, and element IDs. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-09-11 --- **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](https://github.com/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: ```bash archify validate path/to/document.json --json > receipt.json ``` Replace `` with your diagram type (`architecture`, `workflow`, `dataflow`, or `lifecycle`). The receipt written to [`receipt.json`](https://github.com/tt-a1i/archify/blob/main/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: ```bash 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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: ```bash ARCHIFY_DEGRADED=1 archify validate 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: ```bash 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: ```bash archify repair 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 --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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) and the specific schema files to understand contract requirements - Verify `schemaVersion` in your document matches [`archify/skill-release.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), any extra fields beyond the documented contract trigger this violation. Remove the undefined property or check [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md).