# How the Export Registry JSON Sidecar Captures Block Metadata

> Learn how the export registry JSON sidecar captures block metadata by parsing HTML attributes into a machine readable .registry.json file. Run diagram-design export with the registry flag.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-09

---

**The export registry JSON sidecar captures block metadata by parsing HTML `data-block-*` attributes and serializing them into a machine-readable [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) file when running the `diagram-design:export-diagram` command with the `--registry` flag.**

The `cathrynlavery/diagram-design` repository implements a deterministic metadata extraction workflow that persists diagram block attributes into a JSON sidecar. This export registry JSON sidecar serves as the machine-readable source of truth for traceable block decomposition, enabling downstream tooling and audit systems to consume rich structural metadata without parsing raw HTML.

## How the Export Registry Sidecar Generation Works

### Triggering the Export via CLI

The sidecar generation is explicitly triggered by invoking the `diagram-design:export-diagram` command with the `--registry` flag. This flag instructs the exporter to bypass image rasterization and focus solely on metadata extraction, as documented in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md).

```bash

# Export a diagram and produce the JSON sidecar

diagram-design:export-diagram path/to/diagram.html --registry

# Result: path/to/diagram.registry.json

```

### Parsing HTML Block Elements

The exporter parses the source diagram HTML file (provided as the first positional argument) and walks the DOM tree to identify block-level elements. According to **ADR 0010 – Traceable block decomposition**, these elements represent blocks in a Tree diagram structure, each annotated with specific `data-block-*` attributes.

### Extracting Metadata Attributes

For each block node discovered, the extractor reads a fixed set of HTML data attributes:

- `data-block-id` – Stable identifier for the block, used for badge rendering and cross-referencing
- `data-block-parent` – Identifier of the parent block (null for root-level blocks)
- `data-block-name` – Human-readable title of the block
- `data-block-input` – Short list of input ports (optional)
- `data-block-output` – Short list of output ports (optional)
- `data-block-constraint` – Design constraints attached to the block (optional)
- `data-block-assumption` – Operating assumptions for the block (optional)
- `data-block-impl` – Filesystem path or reference to the implementation that satisfies the block (optional)

### Serializing to JSON

The extracted attribute values are assembled into a JSON-serializable array structure containing one entry per block. The resulting file is written alongside the source diagram using the [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) suffix. Because the JSON is derived directly from the diagram HTML, it is **never hand-maintained**, eliminating drift between the visual diagram and its metadata representation.

## Export Registry JSON Structure and Example

Each block object in the registry array contains keys corresponding to the parsed `data-block-*` attributes. The following example from [`docs/adr/0010-block-registry-metadata-contract.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0010-block-registry-metadata-contract.md) illustrates the expected structure:

```json
[
  {
    "id": "PAY-001-02",
    "parent": "PAY-001",
    "name": "Fraud Screening",
    "input": "in",
    "output": "out",
    "constraint": "max-latency-200ms",
    "assumption": "high-volume-traffic",
    "impl": "src/fraud_scanner.py"
  },
  {
    "id": "PAY-001",
    "parent": null,
    "name": "Payment Service",
    "input": null,
    "output": "out",
    "constraint": null,
    "assumption": null,
    "impl": "src/payment_service.js"
  }
]

```

## Source Files and Validation

The implementation spans several key files in the repository:

- **[`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md)** – Defines the sidecar generation procedure and the requirement that the export runs only when explicitly prompted with `--registry`
- **[`docs/adr/0010-block-registry-metadata-contract.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0010-block-registry-metadata-contract.md)** – Specifies the complete contract for block metadata storage, including the mapping of `data-block-*` attributes to JSON keys
- **[`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)** – Documents the CLI interface and links to the reference implementation
- **[`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py)** – Validates generated [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) files against the ADR 0010 contract schema

## Summary

- The export registry JSON sidecar is generated via `diagram-design:export-diagram --registry`, creating a [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) file adjacent to the source HTML.
- The extraction process parses eight specific `data-block-*` HTML attributes including identifiers, hierarchy pointers, ports, constraints, assumptions, and implementation paths.
- The sidecar is strictly derived from the diagram source, ensuring metadata remains synchronized without manual maintenance.
- The JSON structure follows the contract defined in ADR 0010, validated by [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py).

## Frequently Asked Questions

### What CLI command generates the export registry JSON sidecar?

Run `diagram-design:export-diagram path/to/diagram.html --registry`. The `--registry` flag is required to trigger the metadata extraction pipeline instead of standard image export. The command emits a file named [`diagram.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/diagram.registry.json) in the same directory as the input HTML.

### Which HTML attributes are captured in the registry sidecar?

The exporter captures eight specific `data-block-*` attributes: `data-block-id`, `data-block-parent`, `data-block-name`, `data-block-input`, `data-block-output`, `data-block-constraint`, `data-block-assumption`, and `data-block-impl`. These map directly to JSON keys `id`, `parent`, `name`, `input`, `output`, `constraint`, `assumption`, and `impl` respectively.

### Is the registry sidecar manually maintained?

No. The [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) sidecar is strictly auto-generated from the diagram HTML and must never be edited by hand. This design ensures the metadata remains synchronized with the visual diagram structure, eliminating configuration drift between the source HTML and the exported metadata.

### How does the sidecar format support downstream tooling?

The JSON structure provides a machine-readable, schema-validated representation of block decomposition that tools can consume without HTML parsing. The `id` and `parent` fields establish hierarchy, while `impl` paths enable traceability from design blocks to source code, supporting automated auditing and documentation pipelines.