# Archify Delta JSON Output Format: Complete Structure and Examples

> Explore Archify Delta JSON output format. Understand schemaVersion, base/head metadata, summary, and detailed changes for components, connections, and boundaries with examples.

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

---

**Archify's Delta feature returns a structured JSON receipt with `schemaVersion`, `base`/`head` metadata, a `summary` of changes, and detailed `changes` arrays for components, connections, and boundaries.**

The JSON output format for Delta comparisons in Archify provides a machine-readable artifact that captures every difference between two architectural snapshots. This format powers both programmatic analysis and the visual delta views rendered by the tool. The core implementation lives in `archify/delta/architecture-delta.mjs`, where the `compareArchitecture` function constructs and validates this receipt.

## Core Function: `compareArchitecture`

The entry point for generating Delta JSON is the `compareArchitecture` function in **`archify/delta/architecture-delta.mjs`**. It accepts three parameters:

```javascript
compareArchitecture(baseSnapshot, headSnapshot, evidence)

```

The function performs input validation, builds stable indexes for all entities, and returns a single JSON object. This receipt serves as the canonical representation of architectural differences.

## Top-Level JSON Structure

The Delta JSON output contains these fields:

| Field | Type | Purpose |
|-------|------|---------|
| `schemaVersion` | `number` | Fixed at `1` — version of the JSON schema |
| `ok` | `boolean` | Always `true` on successful comparison |
| `command` | `string` | Always `"compare"` for delta operations |
| `type` | `string` | Always `"architecture"` for Archify artifacts |
| `comparatorVersion` | `number` | Internal algorithm version (`COMPARATOR_VERSION`) |
| `canonicalVersion` | `number` | Canonical serialization format version |
| `completeness` | `string` | Currently always `"complete"` |
| `proofLevel` | `string` | `"revision-pinned"` or `"authored"` |

### Snapshot Metadata: `base` and `head`

Both fields share the same structure, capturing minimal metadata from each snapshot:

```json
{
  "title": "Checkout Platform – Before",
  "rawSha256": "abc123...",
  "semanticSha256": "def456...",
  "bytes": 15234,
  "revision": "a1b2c3d4..."
}

```

Only `title` is required; the other fields appear when provenance data is available.

## Change Aggregation: The `summary` Object

The `summary` field provides rolled-up counts for quick scanning:

```json
{
  "components": { "added": 2, "changed": 1, "removed": 0, "moved": 0 },
  "connections": { "added": 0, "changed": 1, "removed": 0, "rerouted": 0 },
  "boundaries": { "added": 0, "changed": 0, "removed": 0, "geometryChanged": 0 },
  "presentationChanged": false,
  "provenanceChanged": true
}

```

- **`components`**, **`connections`**, **`boundaries`** — each contains counters for their respective change types
- **`presentationChanged`** — `true` if visual metadata differs between snapshots
- **`provenanceChanged`** — `true` if repository information diverges

## Detailed Changes: The `changes` Object

For programmatic processing, the `changes` object contains full per-entity change arrays:

```json
{
  "components": [
    {
      "id": "payment-gateway",
      "status": "added",
      "classifications": ["semantic"],
      "changedFields": [],
      "baseLabel": null,
      "headLabel": "Payment Gateway"
    }
  ],
  "connections": [ /* relationship change objects */ ],
  "boundaries": [ /* boundary change objects */ ]
}

```

Each change object follows this schema:

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Stable entity identifier |
| `status` | `string` | `added`, `removed`, `changed`, `moved`, `evidence-changed`, or `geometry-changed` |
| `classifications` | `array[string]` | Categories of change: `"semantic"`, `"evidence"`, `"geometry"` |
| `changedFields` | `array[string]` | JSON Pointer paths to modified fields, e.g., `"/label"` |
| `baseLabel` | `string|null` | Name in base snapshot |
| `headLabel` | `string|null` | Name in head snapshot |

## Identity and View Configuration

The `identity` object documents how entities are matched:

```json
{
  "components": "components[].id",
  "connections": "connections[].id (required)",
  "boundaries": "boundaries[].kind + boundaries[].label (derived)"
}

```

The **`view`** object specifies the visual preset:

```json
{ "visualPreset": "classic" }

```

## Limitations and `proofLevel`

The **`limitations`** array contains human-readable notes about delta scope:

```json
[
  "Authored Architecture IR only; no runtime impact, causality, risk, or mergeability is inferred.",
  "Boundary identity is conservatively derived from kind + label."
]

```

The **`proofLevel`** field indicates provenance strength:

- **`"revision-pinned"`** — both snapshots are provenance-verified
- **`"authored"`** — default when provenance is unverified

## Complete JSON Example

Here is a full Delta JSON output from `archify/delta/architecture-delta.mjs`:

```json
{
  "schemaVersion": 1,
  "ok": true,
  "command": "compare",
  "type": "architecture",
  "comparatorVersion": 1,
  "canonicalVersion": 1,
  "completeness": "complete",
  "proofLevel": "authored",
  "base": {
    "title": "Checkout Platform – Before",
    "revision": "a1b2c3d4..."
  },
  "head": {
    "title": "Checkout Platform – After",
    "revision": "d4c3b2a1..."
  },
  "summary": {
    "components": { "added": 2, "changed": 1, "removed": 0, "moved": 0 },
    "connections": { "added": 0, "changed": 1, "removed": 0, "rerouted": 0 },
    "boundaries": { "added": 0, "changed": 0, "removed": 0, "geometryChanged": 0 },
    "presentationChanged": false,
    "provenanceChanged": true
  },
  "changes": {
    "components": [],
    "connections": [],
    "boundaries": []
  },
  "identity": {
    "components": "components[].id",
    "connections": "connections[].id (required)",
    "boundaries": "boundaries[].kind + boundaries[].label (derived)"
  },
  "view": { "visualPreset": "classic" },
  "limitations": [
    "Authored Architecture IR only; no runtime impact, causality, risk, or mergeability is inferred.",
    "Boundary identity is conservatively derived from kind + label."
  ]
}

```

## Generating Delta JSON Programmatically

### Basic Usage in Node.js

```javascript
import { compareArchitecture } from './archify/delta/architecture-delta.mjs';
import fs from 'fs';

const base = JSON.parse(
  fs.readFileSync('examples/checkout-platform-delta.base.architecture.json')
);
const head = JSON.parse(
  fs.readFileSync('examples/checkout-platform-delta.head.architecture.json')
);

const receipt = compareArchitecture(base, head);
console.log(JSON.stringify(receipt, null, 2));

```

### Rendering Delta HTML with Embedded JSON

The receipt is embedded in HTML output for client-side tools:

```javascript
import {
  extractArchitectureSvg,
  buildDeltaSvg,
  renderArchitectureDeltaHtml,
} from './archify/delta/architecture-delta.mjs';
import fs from 'fs';

const baseHtml = fs.readFileSync('examples/checkout-platform-delta.base.html', 'utf8');
const headHtml = fs.readFileSync('examples/checkout-platform-delta.head.html', 'utf8');

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

const baseSvg = extractArchitectureSvg(baseHtml);
const headSvg = extractArchitectureSvg(headHtml);
const deltaSvg = buildDeltaSvg(baseSvg, headSvg, receipt);

const deltaHtml = renderArchitectureDeltaHtml({
  receipt,
  baseSvg,
  headSvg,
  deltaSvg,
  artifactCss: fs.readFileSync('archify/assets/archify.css', 'utf8'),
});

fs.writeFileSync('delta-output.html', deltaHtml);

```

The HTML output contains the receipt as a `<script type="application/json" id="archify-compare-receipt">` element, enabling JavaScript-based validation and animation.

## Key Source Files

| File | Purpose |
|------|---------|
| `archify/delta/architecture-delta.mjs` | Implements `compareArchitecture` and JSON receipt construction |
| `archify/test/architecture-delta.test.mjs` | Unit tests verifying Delta JSON structure |
| [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) | Sample HTML with embedded receipt |
| [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json) | Real-world Delta JSON example |

## Summary

- **Archify Delta JSON** is generated by `compareArchitecture` in `archify/delta/architecture-delta.mjs`
- **Fixed fields** include `schemaVersion: 1`, `ok: true`, `command: "compare"`, and `type: "architecture"`
- **Dynamic content** spans `base`/`head` metadata, `summary` counts, detailed `changes` arrays, and `limitations` notes
- **Entity matching** uses `components[].id`, `connections[].id`, and derived boundary identity
- **Embedded usage** places the receipt in HTML as `#archify-compare-receipt` for client-side tooling

## Frequently Asked Questions

### What determines the `proofLevel` value in Delta JSON?

The `proofLevel` is `"revision-pinned"` when both the base and head snapshots have provenance verification including revision data. Otherwise, it defaults to `"authored"`, indicating the comparison relies on authored content without cryptographic provenance guarantees.

### Can Delta JSON capture partial comparisons?

Currently, no. The `completeness` field is always `"complete"` as implemented in `archify/delta/architecture-delta.mjs`. The comparison covers the full snapshot rather than isolated subgraphs or filtered views.

### How are component changes classified in the JSON?

Each change carries a `classifications` array with values like `"semantic"` (logical differences), `"evidence"` (supporting metadata changes), or `"geometry"` (positional/visual changes). The `status` field provides the operation type, while `changedFields` uses JSON Pointer notation to pinpoint modified properties.

### Where can I find a real-world Delta JSON example?

The repository includes [`examples/checkout-platform-delta.receipt.json`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.receipt.json), which demonstrates the full structure with actual component, connection, and boundary changes between two snapshots of a checkout platform architecture.