# How to Fix Archify Validation Errors: 9 Supported Fixes Explained

> Resolve Archify validation errors with 9 supported fixes like addMissingField and renameId. Learn how to apply these deterministic operations for guaranteed resolution.

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

---

**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)](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`.

```bash
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:

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

```bash
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:

```bash
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:

```bash
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)](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)](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)](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`](https://github.com/tt-a1i/archify/blob/main/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/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)](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)](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)](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).