How to Fix Archify Validation Errors: 9 Supported Fixes Explained

Archify validation errors return a deterministic supportedFixes array containing specific operations like addMissingField, renameId, and fixGeometry that guarantee resolution when applied to the diagnosed subject.

Archify validates architecture diagrams against strict schemas and deterministic contracts, returning detailed diagnostics when validation fails. Each diagnostic includes a supportedFixes array that lists exactly which operations will resolve the specific Archify validation error encountered. Understanding these fixes allows you to programmatically repair diagrams instead of guessing at solutions.

How Validation Diagnostics Work

When you run archify validate, the tool outputs a JSON receipt containing a diagnostics array. Each diagnostic object identifies the subject (the specific JSON path where the error occurred) and provides a supportedFixes array containing the exact operations that will resolve the issue.

According to [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), these fixes represent the complete set of operations that the deterministic validator recognizes. Only fixes listed in this array are guaranteed to make the diagnostic pass; any ad-hoc changes may be rejected upon re-validation.

The workflow involves three steps:

1. Inspect the JSON receipt to locate the failing subject
2. Select one fix from the supportedFixes array
3. Apply the fix to the source JSON and rerun validation

The 9 Supported Fix Categories

Archify recognizes nine distinct fix categories, each represented as a string in the supportedFixes array. These categories cover structural corrections, metadata updates, and geometric adjustments.

addMissingField inserts required fields that the schema expects but the document lacks, such as schema_version, diagram_type, or meta.title. This resolves errors like "Missing required property 'schema_version'".

removeDuplicateId deletes or renames identifiers that appear multiple times within node or edge collections, fixing "Duplicate IDs found in nodes" errors.

renameId changes an existing ID to a new unique value while preserving all references, addressing "ID already used" conflicts without breaking relationships.

fixGeometry adjusts node coordinates or edge routing to satisfy layout validation gates including overlap detection, crossing prevention, and corridor width requirements.

fixRelationship corrects edge definitions with invalid source/target references, missing type fields, or wrong directions.

setMetaField sets or updates top-level meta properties including meta.quality_profile, meta.engineering_profile, or meta.title when they are missing or invalid.

addRepoMetadata supplies required repository information for Architecture diagrams, including Git origin, commit SHA, and source-range data.

updateLabel modifies node or edge labels to satisfy schema constraints such as non-empty requirements or scope uniqueness.

applyPatch executes concrete JSON-Patch operations (replace, add, remove) generated by the diagnostic for general JSON-structure corrections.

Locating Fixes in the JSON Receipt

To inspect available fixes for a specific error, use the --json flag during validation and parse the output with jq.

node bin/archify.mjs validate architecture examples/web-app.architecture.json \
  --quality showcase --json > receipt.json

cat receipt.json | jq '.diagnostics[0]'

A typical diagnostic fragment shows the error code, subject path, evidence, and available fixes:

{
  "code": "duplicate_id",
  "subject": "/nodes/12",
  "evidence": "ID \"svc\" appears 2 times",
  "supportedFixes": ["removeDuplicateId", "renameId"]
}

Applying Supported Fixes to Source Files

Once you identify the appropriate fix from the supportedFixes array, modify the source JSON accordingly. For duplicate ID errors, use jq to rename the conflicting identifier:

jq '(.nodes[] | select(.id=="svc") | .id) = "svc-1"' \
  examples/web-app.architecture.json > tmp.json && mv tmp.json examples/web-app.architecture.json

Then re-run validation to confirm resolution:

node bin/archify.mjs validate architecture examples/web-app.architecture.json \
  --quality showcase --json

For missing required fields like meta.title, add the property directly:

jq '.meta.title = "My Web App Architecture"' \
  examples/web-app.architecture.json > tmp.json && mv tmp.json examples/web-app.architecture.json

Source Documentation References

The complete contract for validation fixes is documented across three key files in the repository:

• [docs/authoring-cookbook.md](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) describes the validation workflow and explains how to use supportedFixes to repair diagnostics iteratively.

• [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) clarifies that you must change only the diagnosed subject using one of its listed supportedFixes, preventing unrelated modifications that could introduce new errors.

• [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) defines the formal contract for consuming diagnostics[], including the specification for the supportedFixes field and its relationship to deterministic validation.

Summary

• Archify validation errors return a supportedFixes array containing only the operations that will resolve that specific error.
• The nine supported fixes cover fields, IDs, geometry, relationships, metadata, repository info, labels, and JSON patches.
• Each diagnostic identifies a specific subject (JSON path) where the fix must be applied.
• Only fixes listed in supportedFixes are guaranteed to pass re-validation; other changes may be rejected.
• Reference the authoring contract in archify/references/authoring-contract.md for the complete specification.

Frequently Asked Questions

What happens if I apply a fix not listed in supportedFixes?

The deterministic validator will likely reject your correction. According to the [authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), only the specific strings in the supportedFixes array are guaranteed to resolve the diagnostic. Any ad-hoc modification risks failing subsequent validation even if it appears logically correct.

How do I find which fix to apply for a missing schema_version error?

Check the supportedFixes array in the diagnostic for the subject path. Missing schema fields typically trigger the addMissingField fix, which you can apply by inserting the required schema_version property into the root of your JSON document.

Can I automate the application of these fixes?

Yes. Since supportedFixes provides deterministic operation names, you can build scripts that parse the JSON receipt and apply corresponding jq transformations or JSON-Patch operations automatically. The applyPatch fix category specifically supports automated processing by providing concrete JSON-Patch operations.

Where are the supported fixes defined in the source code?

The fix categories are defined in the authoring contract at [archify/references/authoring-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), with usage patterns documented in [archify/SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) and [docs/authoring-cookbook.md](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).

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