# How to Interpret Archify Validation Errors: A Complete Guide to Understanding JSON Receipts

> Learn to interpret Archify validation errors with our guide to understanding JSON receipts. Resolve issues efficiently using diagnostics and supported fixes.

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

---

**Archify validation errors are presented as a machine-readable JSON receipt that contains `checksPassed`, `checkCount`, `composition` status, and a `diagnostics` array with specific error details and `supportedFixes` for each failure.**

Archify validates every generated artifact before it is delivered. The validator produces a **JSON receipt** that tells you exactly what succeeded and what failed. Understanding how to interpret Archify validation errors lets you quickly locate problems, apply suggested fixes, and re-run the pipeline with confidence.

## Understanding the Archify Validation Receipt Structure

The core of Archify's error reporting system is the JSON receipt. Here is an excerpt from an actual receipt in the repository:

```json
{
  "checksPassed": 28,
  "checkCount": 28,
  "checks": [
    { "name": "schema",               "ok": true },
    { "name": "layout",               "ok": true },
    { "name": "routing",              "ok": true }
  ],
  "composition": "pass",
  "stage": "validate",
  "diagnostics": [
    {
      "subject": "relationship",
      "message": "duplicate ID 'A-B'",
      "supportedFixes": [
        "rename the relationship ID",
        "remove the duplicate"
      ]
    }
  ]
}

```

*Source: A complete receipt example is available at [[`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json)](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json).*

### Key Fields in the Validation Receipt

| Field | Meaning |
|-------|---------|
| **checksPassed** | Number of validation checks that succeeded. |
| **checkCount** | Total number of checks the validator ran. |
| **composition** | `"pass"` means overall validation succeeded; `"fail"` or `"partial"` indicates a problem. |
| **stage** | Present only on failure; indicates which phase (`validate`, `deliver`, etc.) raised the error. |
| **diagnostics** | Array of detailed error objects pointing to exact elements that caused failure. |
| **checks[]** | Ordered list of individual checks with `name` and `ok` boolean status. |

## How to Read a Failed Archify Validation Receipt

When `composition` is not `"pass"`, the receipt includes a `diagnostics` array. Each diagnostic contains three critical properties:

| Property | Purpose |
|----------|---------|
| **subject** | The artifact type that failed: `relationship`, `node`, `group`, `engineeringProfile`, etc. |
| **message** | Human-readable description (e.g., "duplicate ID", "missing required field", "overlapping labels"). |
| **supportedFixes** | Concrete actions you can take; the CLI accepts only these values with `archify validate --fix`. |

**Practical Example:**

```json
{
  "subject": "relationship",
  "message": "duplicate ID 'A-B'",
  "supportedFixes": ["rename the relationship ID", "remove the duplicate"]
}

```

This diagnostic indicates two edges in your JSON IR share the same ID. Rename one or delete the duplicate, then re-run the pipeline.

## Where Archify Validation Error Logic Resides

The code that assembles the receipt from validator output lives in the build gallery script:

- **Source file**: [`scripts/build-gallery.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-gallery.mjs)
- **Lines 260-290**: Parse validator stdout, count passed checks, and construct the receipt object including `checks[]`, `composition`, `stage`, and `diagnostics` fields.

This location is where the raw validation results transform into the structured receipt you receive when interpreting Archify validation errors.

## What Validation Receipts Mean for Your Workflow

| Phase | Guarantee of a Passing Receipt |
|-------|-------------------------------|
| **`validate`** | All schema, layout, routing, and composition checks passed; safe to preview. |
| **`deliver`** | Artifact rendered to HTML/SVG/PNG and re-validated; triggers atomic swap of "last-good" artifact only on pass. |
| **`compare`** | Both "before" and "after" snapshots individually valid before diffing. |

If any phase emits `composition !== "pass"`, the CLI exits with non-zero status, prints the JSON receipt, and stops processing. This **fail-closed** approach ensures no broken artifact reaches the Archify gallery.

## Step-by-Step Workflow to Fix Archify Validation Errors

### 1. Run Validation with JSON Output

```bash
node archify/bin/archify.mjs validate architecture my-diagram.json --json

```

The JSON receipt prints to stdout.

### 2. Read the Diagnostics

Locate the `subject` and `message` fields to identify what failed.

### 3. Apply a Supported Fix

Edit your source JSON or upstream generator according to one of the `supportedFixes`.

### 4. Re-validate

Repeat until `composition` reads `"pass"` and `checksPassed === checkCount`.

### 5. Deliver the Artifact

Only then run `archify deliver ...` to replace the live artifact.

### Automatic Fix Mode

```bash
node archify/bin/archify.mjs validate architecture my-diagram.json --fix

```

This applies the first listed fix automatically (if possible) and re-validates.

## Common Archify Validation Error Categories

| Category | Typical Subject | Typical Message | Typical Supported Fixes |
|----------|---------------|---------------|------------------------|
| **Schema errors** | `node`, `relationship`, `group` | "missing required property `type`" | "add the missing property" |
| **Duplicate IDs** | `relationship`, `node` | "duplicate ID 'X-Y'" | "rename the ID", "remove the duplicate" |
| **Layout violations** | `layout` | "edge crosses another edge more than allowed" | "re-order nodes", "adjust spacing" |
| **Engineering profile** | `engineeringProfile` | "profile omitted" | "add a deployment-ownership profile" |
| **Composition failures** | `composition` | "unresolved route for edge 'A→B'" | "provide a valid target", "remove the edge" |

All categories appear as individual boolean entries in the `checks` array, enabling scripted dashboards (e.g., counting diagrams failing due to duplicate IDs).

## Code Examples for Working with Validation Errors

### Validate and Capture Receipt to File

```bash

# Validate an Architecture diagram and save JSON receipt

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

```

### Programmatic Receipt Processing (JavaScript)

```javascript
import fs from 'fs';

const receipt = JSON.parse(fs.readFileSync('receipt.json'));

if (receipt.composition !== 'pass') {
  console.error('Validation failed:', receipt.diagnostics);
  // Iterate over diagnostics to apply fixes automatically
  for (const diag of receipt.diagnostics) {
    console.log(`Fix for ${diag.subject}: ${diag.supportedFixes[0]}`);
  }
} else {
  console.log('All checks passed:', receipt.checksPassed, 'of', receipt.checkCount);
}

```

### CI Pipeline Integration (GitHub Actions)

```yaml

# .github/workflows/ci.yml

- name: Validate diagram
  run: |
    node archify/bin/archify.mjs validate architecture diagrams/arch.json --json > receipt.json
    jq -e '.composition == "pass"' receipt.json

```

The `jq` command exits non-zero if validation fails, causing the CI job to fail.

## Key Source Files for Understanding Archify Validation

| File | Relevance |
|------|-----------|
| [`scripts/build-gallery.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-gallery.mjs) | Creates receipts from validator output (lines 260-290). |
| [[`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json)](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) | Real-world example with `checksPassed = 28`. |
| [[`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md)](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) | Documents the JSON receipt format and `diagnostics[]` structure. |
| [[`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md)](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) | Lists JSON IR schemas that the validator checks. |
| [`archify/test/workflow-compiler.test.mjs`](https://github.com/tt-a1i/archify/blob/main/archify/test/workflow-compiler.test.mjs) | Test suite asserting correct receipt generation for success and failure cases. |

## Summary

- **Archify validation errors** are delivered as structured JSON receipts with `checksPassed`, `checkCount`, `composition`, and `diagnostics`.

- **`composition: "pass"`** with matching `checksPassed === checkCount` indicates a clean artifact.

- **`diagnostics[]`** provides precise error details including `subject`, `message`, and actionable `supportedFixes`.

- Use **`--json`** to capture receipts programmatically and **`--fix`** for automatic repair of known issues.

- The receipt generation logic resides in [`scripts/build-gallery.mjs`](https://github.com/tt-a1i/archify/blob/main/scripts/build-gallery.mjs) lines 260-290.

- Archify's **fail-closed** design guarantees only fully validated artifacts reach the gallery.

## Frequently Asked Questions

### What does the `composition` field indicate in an Archify validation receipt?

The `composition` field reports the overall validation outcome. A value of `"pass"` means all checks succeeded and the artifact is valid. Any other value—`"fail"` or `"partial"`—indicates problems that must be resolved before the artifact can be delivered.

### Where can I find example validation receipts in the Archify repository?

The repository includes a fully-passed validation example at [[`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json)](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json). This file shows all 28 checks passing with `composition: "pass"`, serving as a reference for what successful validation looks like.

### How do I fix validation errors automatically in Archify?

Run the CLI with the `--fix` flag: `node archify/bin/archify.mjs validate architecture my-diagram.json --fix`. This applies the first `supportedFix` if it can be performed automatically, then re-validates. Note that not all fixes are automatable; some require manual source editing.

### Why does my CI pipeline fail even when my diagram looks correct?

Archify uses a **fail-closed** approach: any receipt with `composition !== "pass"` causes the CLI to exit with non-zero status. Visual correctness does not guarantee validation success. Check the `diagnostics` array for specific `subject` and `message` details, then apply one of the listed `supportedFixes`.