# How to Debug Validation Failures with Supported Fixes in Archify

> Debug Archify validation failures with supportedFixes. Run archify validate to get suggested fixes and resolve schema or repository-evidence errors quickly.

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

---

**Run `archify validate <type> <file>.json --json` to expose the `supportedFixes` array, then apply the first suggestion to resolve schema or repository-evidence errors.**

Archify validates diagram JSON against strict JSON-Schema definitions and repository-evidence rules. When validation fails, the tool emits structured diagnostics containing **actionable repair suggestions** in the `supportedFixes` property. Understanding how to interpret and apply these fixes—whether generated from schema keywords like `additionalProperties` or `required`, or from Git-related repository checks—lets you rapidly resolve diagram errors without guesswork.

---

## Where Diagnostics and Supported Fixes Originate

Archify builds validation diagnostics in three core locations. Each attaches `supportedFixes` based on the specific failure mechanism.

### Schema Validation in `validator.mjs`

The file `archify/renderers/shared/validator.mjs` executes generated validators (e.g., `validators['architecture']`) and constructs diagnostic objects on failure. The mapping from JSON-Schema **keywords** to suggested fixes is defined in the `supportedFixes` object at lines 56–68:

- `additionalProperties` → suggests property removal
- `required` → suggests adding missing properties
- `type`, `enum`, `pattern`, and numeric constraints → suggest value corrections

### Repository-Evidence Validation in `repository-evidence.mjs`

The file `archify/renderers/shared/repository-evidence.mjs` performs Git-related checks—verifying local repository roots, path validity, and file existence. Each failure includes domain-specific fixes, such as:

- "install Git and ensure it is available on PATH"
- "pass --repo-root with the matching local Git checkout"

See the first failure handling at lines 25–28 for the pattern.

### CLI Output in `archify.mjs`

The CLI entry point at `archify/bin/archify.mjs` wraps validation and exposes diagnostics when you pass `--json` or `--diagnostic-format=json`. Lines 21–23 handle this flag, printing the full diagnostic payload including `supportedFixes`.

---

## Step-by-Step Debugging Workflow

Follow this repeatable process to resolve validation failures using `supportedFixes`:

1. **Run validation with JSON output**

   ```bash
   archify validate architecture diagram.json --json
   ```

2. **Locate the failure path**

   Check `subject.path` (e.g., `/components/2/sources/0/path`). If `subject.identity` exists, it annotates the element's ID or label for easier navigation.

3. **Read the `supportedFixes` array**

   This contains exact mutations to make the JSON valid—typically one-liners like `remove unsupported property "unexpected"` or `add required property "name"`.

4. **Apply the suggested fix**

   Edit manually or use `archify repair` (if available) to apply automatically.

5. **Re-run validation**

   Confirm the diagnostic disappears. Repeat for any new errors.

For CI automation, `archify repair` applies the first fix and re-validates in a loop.

---

## Example 1: Fixing an `additionalProperties` Error

**Invalid JSON** with an unsupported property:

```json
{
  "components": [
    {
      "id": "auth",
      "type": "service",
      "unexpected": "foo"
    }
  ]
}

```

**Validation command**:

```bash
archify validate architecture diagram.json --json

```

**Diagnostic output**:

```json
{
  "code": "schema/additionalProperties",
  "message": "/components/0 (id: \"auth\") additional property \"unexpected\" is not allowed",
  "subject": {
    "diagramType": "architecture",
    "path": "/components/0",
    "identity": "auth"
  },
  "evidence": {
    "keyword": "additionalProperties",
    "additionalProperty": "unexpected"
  },
  "supportedFixes": [
    "remove unsupported property \"unexpected\""
  ]
}

```

**Apply the fix**:

```bash
sed -i '/\"unexpected\"/d' diagram.json

```

Re-run validation—the error is resolved.

---

## Example 2: Repository Evidence Missing `--repo-root`

**Diagram with source evidence but no local repository specified**:

```json
{
  "meta": {
    "repository": {
      "url": "https://github.com/example/project",
      "revision": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t"
    }
  },
  "components": []
}

```

**Validation without `--repo-root`**:

```bash
archify validate architecture diagram.json --json

```

**Diagnostic output**:

```json
{
  "code": "repository-evidence/root-required",
  "message": "This diagram declares source evidence. Pass --repo-root <repository> so Archify can verify it before rendering.",
  "subject": { "path": "/meta/repository" },
  "supportedFixes": [
    "pass --repo-root with the matching local Git checkout"
  ]
}

```

**Apply the fix**:

```bash
archify validate architecture diagram.json --repo-root /path/to/local/checkout --json

```

Archify now verifies sources; any path or file errors surface with their own `supportedFixes`.

---

## Programmatic Access to Diagnostics

Embed Archify validation in Node.js tooling to build automated repair pipelines:

```javascript
import { validateSchema } from './archify/renderers/shared/validator.mjs';
import fs from 'fs';

const data = JSON.parse(fs.readFileSync('diagram.json', 'utf8'));

try {
  validateSchema('architecture', data);
  console.log('✅ Diagram is valid');
} catch (e) {
  // e.diagnostics contains the same array as CLI --json output
  for (const d of e.diagnostics) {
    console.error(`❌ ${d.message}`);
    console.error('   Fixes:', d.supportedFixes.join(' | '));
  }
}

```

The exception's `diagnostics` property matches CLI output exactly, enabling your tooling to propose or auto-apply fixes.

---

## Fix Generator Reference

| Keyword | Fix Template (from `validator.mjs` lines 56–68) |
|---------|------------------------------------------------|
| `additionalProperties` | `remove unsupported property "${property}"` |
| `required` | `add required property "${property}"` |
| `type` | `use "${expectedType}" at ${path}` |
| `enum` | `choose one of [${allowedValues}]` |
| `pattern` | `match the required pattern "${pattern}"` |
| `minimum` / `maximum` | `use a value ${comparison} ${limit}` |
| `minItems` / `maxItems` | `provide at least/at most ${limit} item(s)` |
| `minLength` / `maxLength` | `provide at least/at most ${limit} character(s)` |

Repository-evidence fixes are defined in `repository-evidence.mjs` and include Git installation, path formatting, and `--repo-root` guidance.

---

## Key Source Files

| File | Purpose |
|------|---------|
| `archify/renderers/shared/validator.mjs` | Core validation driver; builds `supportedFixes` from JSON-Schema keywords |
| `archify/renderers/shared/repository-evidence.mjs` | Git-related checks with domain-specific repair suggestions |
| `archify/bin/archify.mjs` | CLI wrapper; exposes diagnostics via `--json` flag |

---

## Summary

- **Always use `--json`** to expose the full diagnostic payload including `supportedFixes`
- **Read `subject.path`** to locate errors precisely in your diagram JSON
- **Apply the first `supportedFixes` entry**—it provides the minimal valid mutation
- **For repository issues**, provide `--repo-root` and follow path-related guidance
- **Automate repairs** by catching exceptions from `validateSchema()` and acting on `diagnostics` programmatically

Archify's `supportedFixes` transform cryptic validation failures into concrete, actionable steps—dramatically reducing debug time for architecture diagrams.

---

## Frequently Asked Questions

### What is `supportedFixes` in Archify?

`supportedFixes` is an array of string suggestions attached to every validation diagnostic. Each suggestion describes a concrete edit—such as removing a property or adding a required field—that will resolve the specific JSON-Schema or repository-evidence failure. The array is generated automatically based on the validation keyword that triggered the error.

### How do I see `supportedFixes` in the CLI?

Pass `--json` or `--diagnostic-format=json` to any `archify validate` command. This prints the full diagnostic structure including `code`, `message`, `subject`, `evidence`, and `supportedFixes`. Without this flag, Archify may render a human-readable summary that omits the structured fix suggestions.

### Can I automate fixes using `supportedFixes`?

Yes. The `archify repair` command (when available) applies the first fix automatically and re-validates. For custom tooling, catch exceptions from `validateSchema()` in `validator.mjs` and parse `e.diagnostics[].supportedFixes` to drive automated mutations. Most fixes are simple string templates you can translate directly to JSON patch operations or direct file edits.

### Why does repository validation fail without `--repo-root`?

Archify verifies declared source evidence against an actual Git repository on disk. If your diagram contains `meta.repository` or component-level source references, the tool needs a local checkout to validate paths, commits, and file existence. The `supportedFixes` array will explicitly suggest passing `--repo-root` with the appropriate local path when this requirement is unmet.