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

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:

{
  "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).

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:

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

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

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

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

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)

# .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	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)	Real-world example with checksPassed = 28.
[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)	Lists JSON IR schemas that the validator checks.
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 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). 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.

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