# How Export-Registry JSON Sidecar Generation Works in Diagram‑Design

> Learn how export-registry JSON sidecar generation creates deterministic metadata files by parsing HTML with data-block-id attributes using the --registry flag in diagram-design.

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

---

**Export-registry JSON sidecar generation creates a deterministic `*.registry.json` metadata file by parsing HTML elements with `data-block-id` attributes when the `--registry` flag is passed to the export-diagram command.**

The **export-registry** feature in `cathrynlavery/diagram-design` adds machine-readable metadata companions to visual diagrams, enabling version-controlled diffing and automated downstream processing. Unlike raster exports, this process operates entirely on static HTML parsing without invoking Playwright or rendering engines. This article explains the complete generation pipeline, from CLI invocation to the final JSON schema, based on the reference implementation in the repository.

## What Is the Export-Registry Sidecar?

The sidecar file serves as a structured extraction of embedded diagram metadata. It captures the **Traceable block decomposition** pattern encoded in HTML attributes, producing a JSON file named `<basename>.registry.json` adjacent to the source HTML. According to [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), this artifact contains a top-level `source` field identifying the origin file and a `blocks` array representing every traceable node in document order.

## Prerequisites and Activation

The generation process triggers exclusively when users append the `--registry` flag to the export command:

```bash
diagram-design:export-diagram diagram.html --registry

```

The feature is **independent of image export flags** (`--svg-only`, `--png-only`) and can be combined with them to produce both visual and metadata artifacts simultaneously. If the source HTML lacks any `data-block-id` attributes, the command refuses execution and returns a clear error message rather than generating an empty file.

## JSON Schema Structure

The generated sidecar follows a strict two-field schema defined in [`export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-registry.md):

- **`source`**: The filename of the input HTML document.
- **`blocks`**: An ordered array of objects, where each object maps the `data-block-*` attributes of a single node.

For example, an HTML element like:

```html
<div data-block-id="PAY-001"
     data-block-name="Payment Gateway"
     data-block-output="Settled transaction record">

```

Produces a corresponding JSON entry:

```json
{
  "id": "PAY-001",
  "name": "Payment Gateway",
  "output": "Settled transaction record"
}

```

The `data-block-` prefix is stripped during extraction, but attribute values are preserved verbatim without trimming or case normalization.

## Step-by-Step Generation Process

The export procedure follows six deterministic steps as implemented in the diagram-design core:

1. **Read Source HTML** – Load the target HTML file into memory.
2. **Locate Traceable Nodes** – Query for all elements carrying `data-block-id` attributes.
3. **Extract Attributes** – Collect every `data-block-*` attribute present on qualifying nodes.
4. **Normalize Keys** – Remove the `data-block-` prefix from each attribute name to form the JSON keys.
5. **Preserve Document Order** – Assemble the `blocks` array in the exact sequence nodes appear in the HTML.
6. **Write Output** – Serialize to `<basename>.registry.json`, respecting any explicit `--output` path provided in the CLI.

This pipeline never modifies the source HTML, performs uniqueness checks, or resolves hierarchical parent relationships during the write phase.

## Edge Cases and Validation Boundaries

The export-registry generation operates as a **dumb extractor** with specific limitations documented in [`export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-registry.md):

- **Empty Registry Detection**: If no `data-block-id` attributes exist anywhere in the document, the command halts with an error and produces no output file.
- **No Structural Validation**: Duplicate IDs, missing parent references, and cyclic parent relationships are exported exactly as authored. The generation process does not filter or reject malformed semantic structures.
- **No Metadata Enrichment**: Timestamps, generated IDs, and inferred relationships are never added to the output.
- **Attribute Literalism**: Values are extracted verbatim without normalization, ensuring the JSON reflects the exact state of the HTML attributes.

## Usage Examples

### Exporting Registry with Image Formats

Combine the registry flag with visual exports to generate complete artifact sets:

```bash

# Generate SVG and metadata sidecar

diagram-design:export-diagram diagram.html --svg-only --registry

# Generate only metadata without images

diagram-design:export-diagram diagram.html --registry

```

Both commands output [`diagram.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/diagram.registry.json) alongside the source file, or at the location specified by `--output`.

### Minimal Participating HTML

For a block to appear in the registry, it must include at least the `data-block-id` attribute:

```html
<section class="node"
         data-block-id="AUTH-042"
         data-block-name="Authentication Service"
         data-block-input="Credentials"
         data-block-impl="src/auth/service.ts">
  <!-- Content -->
</section>

```

The resulting JSON fragment maintains the attribute order and values exactly as they appear in the markup.

### Handling Non-Traceable Diagrams

Attempting to export a plain HTML file without block annotations results in explicit failure:

```bash
diagram-design:export-diagram plain-tree.html --registry

```

Output:

```

Error: No data-block-id attributes found – the requested diagram does not use the Traceable block decomposition pattern.

```

## Integration with Downstream Verification

Responsibility for data integrity checks lies outside the export process itself. The repository provides [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py) as a standalone validator that consumes the generated JSON to detect:

- Duplicate block IDs
- Missing parent references
- Cyclic parent relationships

This separation of concerns ensures that the export-registry generation remains fast and deterministic, while semantic validation can be performed as a distinct CI/CD step.

## Summary

- Export-registry generation creates `*.registry.json` sidecars solely when the `--registry` flag is active.
- The process extracts `data-block-*` attributes from HTML elements bearing `data-block-id`, preserving document order and verbatim values.
- Output files contain a `source` field and `blocks` array, with keys derived by stripping the `data-block-` prefix.
- No validation occurs during export; structural checks are delegated to [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py).
- Documents lacking traceable block annotations trigger an error rather than producing empty registry files.

## Frequently Asked Questions

### What happens if my HTML contains duplicate data-block-id values?

The export-registry generation exports duplicate IDs exactly as they appear in the HTML without filtering or raising errors. Uniqueness validation is intentionally excluded from the export process and must be performed afterward using [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py).

### Can I generate a registry file without exporting an image?

Yes. The `--registry` flag functions independently of raster export options. Running `diagram-design:export-diagram file.html --registry` produces only the JSON sidecar without invoking Playwright or generating SVG/PNG files.

### Where is the registry file placed when using the --output flag?

The sidecar respects the explicit `--output` path argument. If specified, the [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) file is written to the designated directory or filename alongside any other requested outputs, rather than defaulting to the source file's directory.

### Does the export process modify my original HTML file?

No. The generation process is read-only regarding the source document. It performs no write operations, attribute normalization, or metadata injection into the original HTML file.