How the Export Registry JSON Sidecar Captures Block Metadata

The export registry JSON sidecar captures block metadata by parsing HTML data-block-* attributes and serializing them into a machine-readable .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.

# 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 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 illustrates the expected structure:

[
  {
    "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 – 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 – Specifies the complete contract for block metadata storage, including the mapping of data-block-* attributes to JSON keys
• commands/export-diagram.md – Documents the CLI interface and links to the reference implementation
• scripts/verify-block-registry.py – Validates generated .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 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.

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

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