Archify Delta JSON Output Format: Complete Structure and Examples

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:

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:

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

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

{
  "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`
headLabel	`string	null`

Identity and View Configuration

The identity object documents how entities are matched:

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

The view object specifies the visual preset:

{ "visualPreset": "classic" }

Limitations and proofLevel

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

[
  "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:

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

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:

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	Sample HTML with embedded receipt
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, which demonstrates the full structure with actual component, connection, and boundary changes between two snapshots of a checkout platform architecture.

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