How to Debug Archify Validation Failures Using `--json` Output and `supportedFixes`

Archify's --json flag emits a machine-readable receipt containing a diagnostics[] array with supportedFixes strings that tell you exactly how to repair validation errors.

Archify is an open-source architecture diagramming tool from tt-a1i/archify that validates JSON inputs against strict schemas. When validation fails, the CLI can output structured JSON diagnostics instead of human-readable text, enabling deterministic debugging workflows. The supportedFixes field in each diagnostic provides concrete, actionable repair instructions.

Running Validation with --json Output

To capture a machine-readable receipt, append --json to any validate or deliver command:

node archify/bin/archify.mjs validate architecture diagram.json --json

The <type> argument accepts values like architecture, workflow, or dataflow. This flag sets ARCHIFY_DIAGNOSTIC_FORMAT=json in the CLI's rendererEnv helper (archify/bin/archify.mjs#L98-L103), signaling renderers to emit structured output instead of formatted text.

Save the receipt for analysis:

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
     --quality showcase --json > receipt.json

Understanding the JSON Receipt Structure

The top-level object contains these key fields:

• ok: false — indicates validation failure
• diagnostics: [] — array of error objects with repair guidance

Each diagnostic object includes:

Field	Purpose
code	Stable identifier (e.g., schema/required, schema/type, artifact/label_route_clearance)
message	Human-readable description
subject	JSON pointer to the problematic element, with optional identity hint
evidence	Context like failing keyword and expected values
supportedFixes	Array of concrete repair instructions

The code values and subject paths are generated in validator.mjs#L38-L80, using the annotatedPath function to build precise pointers.

Example Diagnostic Object

{
  "code": "schema/required",
  "severity": "error",
  "message": "#/components/0 missing required property \"id\"",
  "subject": {
    "path": "/components/0",
    "identity": "AuthService"
  },
  "evidence": {
    "keyword": "required",
    "missingProperty": "id"
  },
  "supportedFixes": ["add required property \"id\""]
}

Interpreting supportedFixes Entries

The supportedFixes strings are deliberately phrased as edit commands. Common patterns include:

• remove unsupported property "propertyName" — delete a stray key violating additionalProperties constraints
• add required property "propertyName" — insert a missing mandatory field
• use a value >= 0 — adjust a numeric constraint violation
• choose one of ["GET","POST"] — replace an invalid enum value

These strings originate from the validator's supportedFixes map in validator.mjs, mapped by failing JSON Schema keyword.

Applying Fixes from supportedFixes

Follow this workflow to repair validation failures:

1. Locate the error using subject.path (JSON Pointer) and subject.identity if available
2. Select a fix from supportedFixes — typically the first option is most direct
3. Edit your source JSON according to the command phrasing
4. Re-validate with the same command

Archify permits two focused correction rounds. If identical diagnostics persist after two attempts, the tool exits with a final receipt (documented in the README's "On failure..." section).

Extracting Fixes with jq

Pipe the JSON output to jq for automated fix extraction:

node archify/bin/archify.mjs validate architecture diagram.json --json |
jq -r '.diagnostics[] | "\(.subject.path) => \(.supportedFixes[0])"'

For multiple fixes per diagnostic:

jq -r '
  .diagnostics[]
  | "\(.subject.path) – \(.supportedFixes | join("; "))"
' receipt.json

Programmatic Fix Application

This Node.js example parses supportedFixes strings and applies rudimentary repairs:

import fs from 'node:fs';

const receipt = JSON.parse(fs.readFileSync('receipt.json', 'utf8'));
const doc = JSON.parse(fs.readFileSync('input.json', 'utf8'));

for (const d of receipt.diagnostics) {
  const pointer = d.subject.path.split('/').slice(1);
  let target = doc;
  for (let i = 0; i < pointer.length - 1; i++) {
    target = target[pointer[i]];
  }
  const key = pointer[pointer.length - 1];
  const fix = d.supportedFixes[0];

  if (fix.startsWith('remove unsupported property')) {
    delete target[key];
  } else if (fix.startsWith('add required property')) {
    const prop = fix.match(/"([^"]+)"/)[1];
    target[key] = { ...target[key], [prop]: '' };
  }
}

fs.writeFileSync('fixed.json', JSON.stringify(doc, null, 2));

Re-validate the repaired file:

node archify/bin/archify.mjs validate workflow fixed.json --quality showcase --json

Handling Non-Schema Validation Failures

Renderer-level diagnostics (layout constraints, artifact issues) use the same JSON structure but different code prefixes. These are generated in diagnostics.mjs#L36-L44, such as:

• artifact/label_route_clearance — label positioning conflicts
• layout/edge_crossing — diagram topology issues

The supportedFixes field remains present and follows identical edit-command conventions. Apply the same locate-inspect-fix-re-validate cycle.

Key Implementation Files

File	Role in Debugging Workflow
archify/bin/archify.mjs	CLI entry; sets ARCHIFY_DIAGNOSTIC_FORMAT=json, builds final receipt
archify/renderers/shared/validator.mjs	Schema validation; constructs diagnostics with supportedFixes
archify/renderers/shared/diagnostics.mjs	Normalizes diagnostics; handles I/O and syntax error fallbacks
README.md "On failure..." section	Documents the two-round correction limit and supportedFixes contract

Summary

• --json flag activates machine-readable output via ARCHIFY_DIAGNOSTIC_FORMAT=json
• diagnostics[] array contains every validation failure with precise location (subject)
• supportedFixes field provides concrete, actionable repair strings mapped from JSON Schema keywords
• Two-round correction limit — Archify stops assisting after persistent failures across two attempts
• jq integration enables automated extraction of path-to-fix mappings for scripting workflows

Frequently Asked Questions

What types of validation errors provide supportedFixes?

All diagnostics from validator.mjs include supportedFixes, covering schema violations (schema/required, schema/type, schema/additionalProperties) and renderer-level issues (artifact/label_route_clearance). The field is populated for both JSON Schema failures and diagram-specific constraints, though the fix phrasing differs by error category.

Can I use --json with the deliver command?

Yes. The --json flag works with both validate and deliver subcommands, producing identical receipt structures. Delivery failures (rendering or export errors) include supportedFixes when the failure is repairable through input modification.

Why does Archify limit corrections to two rounds?

The two-round limit prevents infinite loops when fixes are misapplied or when errors mask deeper structural problems. After two attempts with identical diagnostic codes, Archify emits a final receipt and exits, expecting manual intervention. This behavior is documented in the README's "On failure..." section and enforced in the CLI's exit handling.

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