# How to Interpret Archify Validation and Diagnostic Receipts: A Complete Parsing Guide

> Learn to interpret Archify validation and diagnostic receipts. This guide parses the machine-readable JSON output from Archify for successful validation and detailed failure analysis.

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

---

**Archify command‑line tools emit a machine‑readable JSON receipt on STDOUT that summarizes validation results and provides structured diagnostics for failed checks.**

The `tt-a1i/archify` repository uses these receipts as the single source of truth for CI pipelines, visual reports, and automation workflows. Understanding the receipt schema lets you integrate Archify into your development workflow and debug architecture validation failures systematically.

## Understanding the Archify Receipt Schema

Every Archify command that produces validation results—`archify validate`, `archify compare`, `archify deliver`, and `archify visual-check`—outputs a receipt with `schemaVersion: 1`. This stable schema ensures your parsing logic remains compatible across tool updates.

### Core Receipt Fields

| Field | Type | Purpose |
|-------|------|---------|
| `ok` | boolean | Operation success indicator (`true` or `false`) |
| `type` | string | Artifact category: `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` |
| `validation` | object | Structural check summary with `checksPassed`, `checkCount`, `baseComposition`, and `headComposition` |
| `diagnostics` | array (optional) | Validation errors with `code`, `message`, and JSON-pointer `path` |
| `engineeringProfile` | string (architecture only) | Applied profile such as `deployment-ownership` |
| `artifact` | object | Reproducibility data: `sha256` hash and `bytes` size |
| `view` | object | Visual preset used for rendering (`visualPreset`) |
| `limitations` | array | Human‑readable disclaimers about receipt guarantees |

The receipt format is deliberately consistent across all command modes, so a single parser can handle validation, comparison, delivery, and visual check outputs.

## Reading a Successful Validation Receipt

When validation passes, the receipt contains `ok: true` and omits the `diagnostics` array. The `validation` object confirms all structural checks and composition gates succeeded.

### Example Success Receipt

```json
{
  "schemaVersion": 1,
  "ok": true,
  "type": "architecture",
  "validation": {
    "checksPassed": 28,
    "checkCount": 28,
    "baseComposition": "pass",
    "headComposition": "pass"
  },
  "artifact": {
    "sha256": "b509920b635dc816d7b0f9848bec5bbbf0b77a049ccb50225afbd1dae7a62e39",
    "bytes": 2023841
  }
}

```

**Key indicators of success:**

- **28/28 checks passed** — The `checksPassed` equals `checkCount` with no failures
- **Composition gates passed** — Both `baseComposition` and `headComposition` report `"pass"`
- **Reproducible artifact** — The `artifact.sha256` enables verification with `archify check <file>`

This example comes from the Checkout Platform delta comparison in [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json). The same file includes a `summary` section for comparison operations that lists added, removed, and changed components, connections, and boundaries.

## Parsing Diagnostic Receipts for Failed Validations

When validation fails, the receipt contains `ok: false` and a populated `diagnostics` array. Each diagnostic follows the AJV-style schema used by the underlying JSON Schema validator.

### Diagnostic Object Structure

| Property | Description |
|----------|-------------|
| `code` | Stable error identifier (e.g., `schema/additionalProperties`) |
| `message` | Human-readable problem description |
| `path` | JSON-pointer to the offending element in the source document |

### Example Failure Receipt

```json
{
  "schemaVersion": 1,
  "ok": false,
  "type": "workflow",
  "diagnostics": [
    {
      "code": "schema/additionalProperties",
      "message": "should NOT have additional properties",
      "path": "/nodes/0/colour"
    }
  ]
}

```

This specific diagnostic appears in the smoke-test suite when an extra `colour` property is injected into a workflow definition. The test expecting this receipt lives in `scripts/package-smoke.mjs` around line 33 in the `runExpectFailure` block.

The `path` field uses JSON-pointer syntax, so `/nodes/0/colour` refers to the `colour` property on the first element of the `nodes` array. This precise location data lets you jump directly to the source of validation errors in your editor.

## Automation Patterns for Archify Receipts

CI pipelines typically consume receipts to gate builds on validation success. The consistent JSON output enables straightforward integration with shell scripts, GitHub Actions, and other automation tools.

### Shell Script Pattern for Build Gating

```bash

# Run validation and capture the JSON receipt

receipt=$(archify validate architecture examples/checkout-platform.base.architecture.json --json)

# Extract the overall status

ok=$(echo "$receipt" | jq -r .ok)

if [ "$ok" = "true" ]; then
  echo "✅ Validation passed"
else
  echo "❌ Validation failed"
  # Show the first diagnostic for quick debugging

  echo "$receipt" | jq -r '.diagnostics[0].message, .diagnostics[0].path'
  exit 1
fi

```

This pattern works identically for `compare`, `deliver`, and `visual-check` commands because all share the same top-level `ok` field.

### Node.js Receipt Parsing

```javascript
const fs = require('fs');

// Load a receipt generated by `archify compare … --json`
const receipt = JSON.parse(
  fs.readFileSync('examples/checkout-platform-delta.receipt.json', 'utf8')
);

if (receipt.ok) {
  console.log('✅ Validation succeeded');
  console.log(
    `Checks passed: ${receipt.validation.checksPassed}/${receipt.validation.checkCount}`
  );
  console.log(`Artifact hash: ${receipt.artifact.sha256}`);
} else {
  console.error('❌ Validation failed');
  console.error('Diagnostics:', receipt.diagnostics);
}

```

### GitHub Actions Integration

```yaml
steps:
  - name: Validate Architecture
    id: archify
    run: |
      receipt=$(archify validate architecture examples/checkout-platform.base.architecture.json --json)
      echo "receipt=$receipt" >> $GITHUB_OUTPUT

  - name: Fail on validation errors
    if: ${{ fromJSON(steps.archify.outputs.receipt).ok != true }}
    run: |
      echo "❌ Architecture validation failed"
      echo "${{ fromJSON(steps.archify.outputs.receipt).diagnostics[0].message }}"
      exit 1

```

This CI pattern is implemented in [`.github/workflows/ci.yml`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/ci.yml) in the Archify repository.

## Where Receipts Are Generated in the Archify Codebase

### Core CLI Implementation

The `archify validate <mode> <file> --json` command produces receipts through the core CLI implementation in [`src/cli/validate.ts`](https://github.com/tt-a1i/archify/blob/main/src/cli/validate.ts). This entry point delegates to mode‑specific validators and assembles the standardized receipt envelope.

### Comparison and Delta Receipts

`archify compare architecture … --json` builds delta receipts containing a `summary` object with added, removed, and changed elements. The Checkout Platform example demonstrates this format in [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json).

### Embedded Receipts in Generated Output

The `archify deliver` and `archify visual-check` commands embed the receipt directly in generated HTML. The viewer JavaScript reads this embedded data via `Archify.view.reveal()` and displays a green "PASS" badge when `receipt.ok` is true. This enables human review of validation results alongside the visual architecture diagram.

## Summary

- **Archify receipts use a stable JSON schema** (`schemaVersion: 1`) with consistent `ok`, `type`, `validation`, and optional `diagnostics` fields across all commands

- **Success receipts** show matching `checksPassed`/`checkCount` values and `"pass"` status for both `baseComposition` and `headComposition`

- **Diagnostic receipts** provide machine‑actionable error data with stable `code` identifiers, human‑readable `message` text, and precise JSON-pointer `path` locations

- **The `artifact.sha256` field** enables reproducibility verification through `archify check <file>` comparison

- **Receipt parsing logic** works identically for `validate`, `compare`, `deliver`, and `visual-check` outputs, simplifying CI integration

- **Reference implementations** appear in `scripts/package-smoke.mjs`, [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json), and [`.github/workflows/ci.yml`](https://github.com/tt-a1i/archify/blob/main/.github/workflows/ci.yml)

## Frequently Asked Questions

### What does the `schema/additionalProperties` diagnostic code mean?

This error indicates that your architecture, workflow, or other definition contains properties not defined in the JSON Schema for that artifact type. The `path` field points to the specific location of the extra property. Remove the undefined property or update your schema if the property should be valid.

### How do I verify that a generated HTML file matches its receipt?

Run `archify check <file>` against the generated HTML. This command extracts the embedded receipt, computes the SHA-256 hash of the artifact content, and compares it against `receipt.artifact.sha256`. A match confirms the file has not been modified since generation.

### Why do some receipts include `limitations`? What guarantees are missing?

The `limitations` array contains human‑readable notes about what the receipt does not guarantee. Common entries include "no runtime impact" or "semantic correctness not verified." These cues remind consumers that passing validation confirms structural and compositional correctness, not necessarily that the architecture behaves correctly in production.

### Can I rely on `schemaVersion: 1` for long-term automation?

Yes. The Archify maintainers designed the receipt schema for backward compatibility. The version field enables future schema evolution without breaking existing parsers. Your automation should check `schemaVersion` and handle unknown versions gracefully, but `1` will remain supported.