# What Does the Architecture Delta Comparison Receipt Contain? Complete JSON Structure Guide

> Explore the architecture delta comparison receipt a JSON artifact detailing structural differences between architecture models. Understand metadata changes component listings and validation outcomes.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-14

---

**The architecture delta comparison receipt is a JSON-encoded artifact that records the complete structural difference between two architecture model versions, containing metadata fields, high-level change summaries, detailed listings of modified components/connections/boundaries, identity mappings, visualization hints, cryptographic fingerprints, and validation outcomes.**

The **architecture delta comparison receipt** is the primary output of the comparison engine in the `tt-a1i/archify` repository. Stored at [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json), this machine-readable artifact provides a deterministic audit trail of how a baseline architecture model differs from a new head version, enabling downstream CI pipelines, visualizers, and governance tools to process architectural changes programmatically.

## Core Metadata and Versioning Fields

Every receipt begins with standard metadata that identifies the schema, operation, and comparison engine characteristics.

- **`schemaVersion`**: An integer defining the receipt schema version (e.g., `1`).
- **`ok`**: A boolean flag indicating overall comparison success.
- **`command`**: The operation that produced the receipt, typically `"compare"`.
- **`type`**: The artifact classification, set to `"architecture"` for delta comparisons.
- **`comparatorVersion`**: Version identifier of the comparison engine that generated the receipt.
- **`canonicalVersion`**: Version of the canonical internal representation used during comparison.
- **`completeness`**: Indicates coverage scope, typically `"complete"` when the full model was analyzed.
- **`proofLevel`**: Trust level of the generated intermediate representation, such as `"authored"`.

## Base and Head Model References

The receipt contains **`base`** and **`head`** objects that cryptographically identify the two compared architecture versions. Each block includes:

- **Title**: Human-readable description (e.g., `"Checkout Platform — Baseline"` vs `"Checkout Platform — Fraud Gate"`).
- **Raw and Semantic Hashes**: SHA-256 fingerprints of the raw input and semantic model.
- **Byte Size**: The total size of the underlying artifact.

As seen in [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json), these fields allow consumers to verify exactly which revisions were compared and ensure artifact integrity.

## High-Level Change Summaries

The **`summary`** field provides aggregate counts of architectural modifications, organized by element type:

- **Components**: Counts of added, changed, removed, and moved elements.
- **Connections**: Tallies for added, changed, removed, and rerouted links between components.
- **Boundaries**: Counts of added, changed, or removed containment boundaries.

This section also flags presentation and provenance changes that might affect rendering or audit trails without altering structural topology.

## Detailed Change Listings

The **`changes`** object contains granular arrays documenting every specific modification.

### Component Changes

Stored in `changes.components`, each entry is an object with:

- **`id`**: Unique component identifier.
- **`status`**: One of `added`, `removed`, `changed`, or `moved`.
- **Base and Head Labels**: The display names in each version.
- **Classification Tags**: Categorical metadata for filtering.
- **Changed Fields**: Specific JSON Pointer paths that differ (e.g., `"/sublabel"` for label modifications or `"/pos"` for positional moves).

For example, the receipt shows component `"checkout"` with `status: "changed"` modifying the `"/sublabel"` field, while component `"queue"` records `status: "moved"` with changes to `"/pos"`.

### Connection Changes

The `changes.connections` array tracks edge modifications between components. Each object includes:

- **`id`**: Connection identifier.
- **Endpoint Definitions**: `from`, `to`, `label` values for both base and head versions.
- **`status`**: `added`, `changed`, `removed`, or `rerouted`.
- **Field Diffs**: Specific attributes that changed, such as `fromSide`, `toSide`, or `via` routing coordinates.

In the sample receipt, connection `"authorize-payment"` shows changes to `from`, `fromSide`, `toSide`, and `via` fields, while `"fraud-check"` appears as a newly `added` connection.

### Boundary Changes

Stored in `changes.boundaries`, these objects describe containment modifications:

- **`key`**: Unique boundary identifier (e.g., `"region:Production region"`).
- **`kind`**: Boundary classification type.
- **`label`**: Human-readable description.
- **`status`**: Modification state.
- **Changed Fields**: Specific structural modifications, such as updates to `"/wraps"` indicating different contained elements.

## Identity Mappings and Visualization

### Identity Resolution

The **`identity`** field maps receipt identifiers back to underlying model elements, specifying lookup paths for components, connections, and boundaries. This ensures that visualizers and analysis tools can correlate receipt entries with source architecture artifacts.

### Visualization Preferences

The **`view`** object suggests rendering presets for delta visualization tools. For example, `"visualPreset": "signal-flow"` indicates the recommended diagram type for displaying the changes, helping tools like C4-PlantUML or Structurizr select appropriate layouts automatically.

## Limitations, Provenance, and Validation

### Limitations

The **`limitations`** array explicitly declares what the receipt does **not** infer. According to the schema implemented in `tt-a1i/archify`, these declarations include:

- No runtime impact assessment.
- No causality determination between changes.
- No risk scoring or security analysis.
- No mergeability guarantees for the proposed changes.

These boundaries prevent automated systems from over-interpreting static structural differences as behavioral or deployment-safe modifications.

### Artifact Provenance

The **`artifact`** field provides a cryptographic fingerprint (SHA-256 hash) and byte size of the compared architecture file, enabling reproducibility verification. For instance, the sample receipt records SHA-256 `b1a9…` with a size of `1 836 089` bytes.

### Validation Outcomes

The **`validation`** object reports internal consistency checks:

- **Passed Checks**: Count of successful validations (e.g., `28` passed).
- **Total Checks**: Total number of validation rules executed.
- **Composition Status**: Pass/fail indicators for both `base` and `head` model compositions.

This section confirms that the compared models were structurally sound before delta calculation began.

## Parsing the Architecture Delta Comparison Receipt

The following examples demonstrate how to extract specific insights from the receipt file using JavaScript and Python.

### JavaScript (Node.js)

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

// Load the receipt JSON
const receipt = JSON.parse(fs.readFileSync(
  'examples/checkout-platform-delta.receipt.json',
  'utf8'
));

// List all changed components (excluding additions and removals)
const changedComponents = receipt.changes.components.filter(
  c => c.status !== 'added' && c.status !== 'removed'
);
console.log('Changed components:', changedComponents.map(c => c.id));

// Summarize connection changes
const conn = receipt.summary.connections;
console.log(
  'Connection changes → added:', conn.added,
  'changed:', conn.changed,
  'removed:', conn.removed,
  'rerouted:', conn.rerouted
);

```

### Python

```python
import json

with open('examples/checkout-platform-delta.receipt.json') as f:
    receipt = json.load(f)

# Print high-level component summary

summary = receipt['summary']
print(
    'Components – added:', summary['components']['added'],
    'changed:', summary['components']['changed'],
    'removed:', summary['components']['removed'],
    'moved:', summary['components']['moved']
)

# Extract all newly added connections

added_conns = [
    c for c in receipt['changes']['connections']
    if c['status'] == 'added'
]
print('New connections:', [c['id'] for c in added_conns])

```

These snippets demonstrate filtering specific change types and generating stakeholder reports from the machine-readable structure.

## Summary

- The **architecture delta comparison receipt** is a versioned JSON artifact produced by the `tt-a1i/archify` comparison engine.
- It contains **`base`** and **`head`** metadata with SHA-256 hashes identifying the compared versions.
- The **`summary`** field provides aggregate counts of component, connection, and boundary changes.
- Detailed modifications are listed in **`changes.components`**, **`changes.connections`**, and **`changes.boundaries`**, including specific field paths via JSON Pointer notation.
- The **`identity`** field maps receipt IDs to model elements, while **`view`** suggests visualization presets.
- **`limitations`** explicitly excludes runtime impact, causality, and mergeability assessments.
- **`validation`** reports internal consistency check results, ensuring model integrity.

## Frequently Asked Questions

### What file format does the architecture delta comparison receipt use?

The receipt uses standard **JSON** encoding with a defined schema version (indicated by the `schemaVersion` field). This format ensures broad interoperability with JavaScript, Python, Go, and other languages commonly used in CI/CD pipelines.

### How does the receipt distinguish between a moved component and a changed component?

The receipt uses the **`status`** field within `changes.components` entries. A **`"moved"`** status indicates positional changes (typically tracked in the `"/pos"` field), while **`"changed"`** indicates modifications to non-positional attributes like labels, types, or metadata (tracked in fields like `"/sublabel"`).

### Can the architecture delta comparison receipt determine if changes are safe to deploy?

**No.** The **`limitations`** field explicitly states that the receipt represents "Authored Architecture IR only" and does not infer runtime impact, risk, or mergeability. Consumers must implement separate safety checks; the receipt only provides the structural delta for analysis.

### Where can I find an example of a complete architecture delta comparison receipt?

The repository contains a fully populated example at **[`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json)**. This file demonstrates all top-level fields including metadata, summaries, detailed change listings, and validation results as implemented in the `tt-a1i/archify` codebase.