How to Resolve Validation Diagnostics and Find Supported Fixes in Archify

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

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:

jq '.diagnostics[]' diagnostics.json

Typical output looks like this:

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

// 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:

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 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.

Practical Code Examples

Fixing a Node Overlap Error

This example demonstrates resolving an E010 overlap violation:

# 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:

# 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:

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 – Defines the high-level contract for the two-round focused repair workflow and how consumers should process diagnostics.
• archify/references/authoring-contract.md – Specifies the complete diagnostics[] schema, including the structure and semantics of supportedFixes.
• 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.
• 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 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. 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.

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