# How to Resolve Validation Diagnostics and Find Supported Fixes in Archify

> Resolve Archify validation diagnostics easily. Learn how to find supported fixes within the diagnostics array and repair your validation errors efficiently.

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

---

**Archify returns a structured JSON envelope containing a `diagnostics[]` array with explicit `supportedFixes` fields that tell you exactly which properties to edit to repair validation errors.**

When you author diagrams in the `tt-a1i/archify` repository, the validator enforces strict schema and layout rules through the `archify validate` command. Instead of crashing with stack traces, the tool emits a versioned diagnostic payload that maps every error to specific, allowable repairs. This article explains how to parse that output, locate the affected nodes using JSON pointers, and apply only the authorized fixes to bring your diagrams into compliance.

## Understanding the Validation Output Structure

The `archify validate` command returns a single JSON object even when validation fails. Inside this envelope, the `diagnostics[]` array contains one entry per rule violation, providing a deterministic repair contract.

Each diagnostic object includes four critical fields:

- **`code`** – A stable rule identifier (e.g., `E001`, `W012`, `E014`) that uniquely identifies the violated constraint.
- **`subject`** – A JSON Pointer (RFC 6901) that pinpoints the exact object causing the failure, such as `/nodes/12`.
- **`evidence`** – Measured data proving the violation, such as overlapping coordinates or missing endpoints.
- **`supportedFixes`** – An explicit whitelist of the **only** fields or actions permitted to resolve the error.

The `supportedFixes` array is authoritative. Archify will reject any edit that modifies fields outside this list, preventing accidental changes and keeping repairs deterministic. This contract is defined in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) and enforced by the validation engine in `archify/bin/archify.mjs`.

## Step-by-Step Repair Workflow

Follow this six-step process to resolve validation diagnostics using the `supportedFixes` metadata.

### 1. Run Validation with JSON Output

Execute the validator with the `--json` flag to capture the diagnostic envelope:

```bash
node archify/bin/archify.mjs validate <type> path/to/diagram.json --quality showcase --json

```

The command emits a single JSON object. Even on failure, the top-level `diagnostics` field contains every rule violation detected.

### 2. Inspect the Diagnostics Array

Parse the output to examine individual errors:

```bash
jq '.diagnostics[]' diagnostics.json

```

Typical output looks like this:

```json
{
  "code": "E014",
  "subject": "/nodes/12",
  "evidence": { "overlap": true, "distance": 4 },
  "supportedFixes": ["x", "y"]
}

```

### 3. Locate the Subject in Your Source JSON

The `subject` value is a JSON Pointer. Navigate to that path in your source file. For the example above (`/nodes/12`), locate the 13th element in the `nodes` array (zero-indexed).

### 4. Apply One of the Supported Fixes

Modify **only** the keys listed in `supportedFixes`. Continuing the overlap example:

```json
// Before
{ "id": "12", "type": "backend", "x": 120, "y": 45 }

// After (adjusting x to eliminate overlap)
{ "id": "12", "type": "backend", "x": 150, "y": 45 }

```

### 5. Re-run Validation

Validate the corrected diagram:

```bash
node archify/bin/archify.mjs validate <type> path/to/diagram.json --quality showcase --json

```

If the fix succeeded, the `diagnostics` array will be empty and the command exits with code `0`. If new issues appear, repeat steps 2 through 4.

### 6. Iterate Up to Two Focused Rounds

Archify enforces a strict **two-round focused correction** limit per change request. After two validation cycles without resolution, you must stop and report the remaining diagnostics as unresolved. This rule is codified in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) to prevent infinite guess-and-check loops.

## Common Diagnostic Categories and Supported Fixes

Different validation errors map to specific repairable fields. Refer to this mapping when planning corrections:

| Category | Typical Code | Supported Fixes |
|----------|--------------|-----------------|
| **Node placement** | `E010` (overlap), `E011` (out-of-range) | `x`, `y` |
| **Edge routing** | `E020` (endpoint-direction), `E021` (edge-through-node) | `via`, `labelAt` |
| **Label clearance** | `E030` (label-to-node collision) | `labelAt` |
| **Schema violations** | `E040` (missing required field) | Field name (e.g., `type`, `meta`) |
| **Deployment ownership** | `E050` (missing owner) | `owner`, `region` |

These categories are enumerated in the **Structured Repair Receipt** section of [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md).

## Practical Code Examples

### Fixing a Node Overlap Error

This example demonstrates resolving an `E010` overlap violation:

```bash

# 1. Run validation

node archify/bin/archify.mjs validate architecture examples/web-app.json --json > diag.json

# 2. Extract the specific diagnostic

jq '.diagnostics[] | select(.code=="E010")' diag.json

# Output shows subject "/nodes/7" and supportedFixes ["x","y"]

# 3. Edit the source file

# Change x coordinate from 120 to 170

sed -i 's/"id":"7".*"x":120/"id":"7","x":170/' examples/web-app.json

# 4. Re-validate

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

# Empty diagnostics array indicates success

```

### Correcting Missing Endpoint Direction

When `supportedFixes` indicates missing edge properties:

```bash

# Run validation that reports missing endpoint direction

node archify/bin/archify.mjs validate workflow examples/checkout-platform-delta.json --json > d.json

# Extract fixable fields

jq -r '.diagnostics[] | "\(.subject) \(.supportedFixes[])"' d.json

# Output: /edges/3 via

# Insert the missing via field

jq '(.edges[3] += {"via":"right"})' examples/checkout-platform-delta.json > tmp && mv tmp examples/checkout-platform-delta.json

# Validate again

node archify/bin/archify.mjs validate workflow examples/checkout-platform-delta.json --json

```

### Automating Two-Round Repairs

This bash function implements the two-round repair limit enforced by the skill contract:

```bash
repair() {
  local type=$1 src=$2
  for i in 1 2; do
    out=$(node archify/bin/archify.mjs validate "$type" "$src" --json)
    echo "$out" | jq -e '.diagnostics|length==0' && break
    echo "$out" | jq -c '.diagnostics[]' |
    while read -r diag; do
      subject=$(echo "$diag" | jq -r .subject)
      fix=$(echo "$diag" | jq -r .supportedFixes[0])
      # Naive repair: numeric fixes to 0, string fixes to "FIX"

      case $fix in
        x|y) val=0;;
        via|labelAt) val="FIX";;
        *)   val=null;;
      esac
      jq "($subject) |= . + {\"$fix\":$val}" "$src" >tmp && mv tmp "$src"
    done
  done
}

# Usage

repair architecture examples/web-app.json

```

## Key Source Files and References

Understanding these files deepens your ability to troubleshoot validation errors:

- **`archify/bin/archify.mjs`** – The CLI entry point that implements the `validate` command and emits the JSON diagnostic envelope.
- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Defines the high-level contract for the two-round focused repair workflow and how consumers should process diagnostics.
- **[`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md)** – Specifies the complete `diagnostics[]` schema, including the structure and semantics of `supportedFixes`.
- **[`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md)** – Documents the introduction of the Structured Repair Receipt and enumerates the stable rule codes (E010, E020, etc.).

## Summary

- Archify validates diagrams against strict schemas and returns errors in a structured `diagnostics[]` array rather than crashing.
- Each diagnostic includes a `subject` (JSON Pointer) and `supportedFixes` (authorized edit fields) that define the exact repair path.
- You must modify only the fields listed in `supportedFixes`; any other changes will be rejected by the validator.
- The repair workflow allows a maximum of two focused correction cycles per session, as defined in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md).
- Common fixes involve adjusting `x`/`y` coordinates for node placement or adding `via`/`labelAt` properties for edge routing.

## Frequently Asked Questions

### What is the `supportedFixes` field in Archify diagnostics?

The `supportedFixes` field is an array of strings that lists the **only** object properties you are permitted to modify to resolve a specific validation error. It acts as a deterministic repair contract, ensuring that fixes remain within the allowed transformation space and preventing accidental modifications to unrelated fields.

### How many repair rounds does Archify allow per validation session?

Archify enforces a **two-round focused correction** limit. After running validation twice and applying fixes, if diagnostics persist, you must stop the repair process and report the remaining errors as unresolved. This constraint is documented in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) to maintain efficient, deterministic troubleshooting.

### Where can I find the complete schema for Archify validation diagnostics?

The complete schema definition resides in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md). This file details the structure of the `diagnostics[]` array, including the `code`, `subject`, `evidence`, and `supportedFixes` fields, along with versioning rules for the JSON envelope.

### What happens if I attempt to fix a field not listed in `supportedFixes`?

If you modify a field that is not explicitly listed in the `supportedFixes` array for a given diagnostic, Archify will **reject** the edit during subsequent validation. The validator treats such changes as unauthorized mutations, preserving the integrity of the diagram structure and ensuring repairs follow the deterministic contract defined in the authoring specifications.