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

> Debug Archify validation failures efficiently with --json output and supportedFixes. Learn how to repair errors using machine-readable diagnostics and find solutions fast.

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

---

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L98-L103)), signaling renderers to emit structured output instead of formatted text.

Save the receipt for analysis:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/validator.mjs#L38-L80), using the `annotatedPath` function to build precise pointers.

### Example Diagnostic Object

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/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:

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

```

For multiple fixes per diagnostic:

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

```

### Programmatic Fix Application

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

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs) | CLI entry; sets `ARCHIFY_DIAGNOSTIC_FORMAT=json`, builds final receipt |
| [`archify/renderers/shared/validator.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/validator.mjs) | Schema validation; constructs diagnostics with `supportedFixes` |
| [`archify/renderers/shared/diagnostics.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/shared/diagnostics.mjs) | Normalizes diagnostics; handles I/O and syntax error fallbacks |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/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.