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

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, 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:

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:

• 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:

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

Produces a corresponding JSON entry:

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

• 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:

# 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 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:

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

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 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.
• 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.

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 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.

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