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

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

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

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

# 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

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

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 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. 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.

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, and .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.

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