# Understanding the Block Registry Metadata System in Diagram-Design

> Explore diagram-design's block registry metadata system. Discover how it catalogs reusable components for CLI export, validation, and marketplace publishing.

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

---

**Diagram-Design uses a JSON-based block registry metadata system to catalog reusable diagram components, enabling CLI export via the `--registry` flag, automated validation through Python scripts, and marketplace publishing to plugin-specific JSON files.**

The block registry metadata system in cathrynlavery/diagram-design serves as the central authority for defining, validating, and distributing reusable diagram elements. This machine-readable catalog drives the tool's extensible architecture by standardizing how blocks declare their interfaces, properties, and categorization across exports and marketplace distributions.

## What Is the Block Registry Metadata System?

The block registry metadata system is a structured JSON catalog that describes every available block within the Diagram-Design ecosystem. Each entry represents a reusable diagram component with strict schema requirements enforced by automated verification tools.

The registry structure centers around a top-level `blocks` array containing individual block definitions. 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 system supplies the CLI with the information needed to reconstruct projects and populate the marketplace with validated components.

### Core Schema Fields

Every block entry in the registry contains standardized metadata fields:

- **id**: Unique identifier string for the block
- **name**: Human-readable display name
- **description**: Detailed explanation of block functionality
- **category**: Classification group for UI organization
- **icon**: Reference to the block's visual icon asset
- **inputs**: Array of input port definitions with type specifications
- **outputs**: Array of output port definitions with type specifications
- **defaultProperties**: Default configuration values
- **example**: Usage example or template data

The registry file itself includes metadata headers such as `version` and `generatedAt` timestamps to track schema evolution and export timing.

## Exporting Block Registries via CLI

Diagram-Design provides native CLI support for registry extraction through the `--registry` flag. This functionality allows developers to dump the current project's block definitions into a portable JSON file suitable for version control or marketplace submission.

To export a diagram's block registry, execute:

```bash
diagram-design export my-diagram.dd --registry ./my-registry.json

```

This command processes the internal block definitions and writes a structured JSON file containing the complete metadata catalog. The output follows the schema documented in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), producing a file structure similar to:

```json
{
  "version": "1.0",
  "generatedAt": "2026-09-11T14:23:00Z",
  "blocks": [
    {
      "id": "pie-chart",
      "name": "Pie Chart",
      "description": "A simple pie chart block",
      "category": "Charts",
      "icon": "pie.svg",
      "inputs": [{ "name": "data", "type": "array<number>" }],
      "outputs": [{ "name": "svg", "type": "string" }],
      "defaultProperties": {}
    }
  ]
}

```

## Validating Registry Integrity

The repository includes automated verification through [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py), a Python utility that enforces registry quality standards. This script runs automatically in CI pipelines (configured in [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml)) to prevent malformed block definitions from entering the main branch.

### Verification Checks

The verifier performs three critical assertions:

1. **Unique ID validation**: Ensures no duplicate `id` values exist across the `blocks` array
2. **Required field presence**: Confirms every entry contains mandatory keys including `id`, `name`, and `category`
3. **Schema type conformance**: Validates that optional fields match expected data types (e.g., `inputs` must be an array of objects)

Run the verifier locally against any registry file:

```bash
python scripts/verify-block-registry.py ./my-registry.json

```

The script exits silently on success or prints detailed error messages (such as "Duplicate block ID: `pie-chart`") when validation fails.

## Publishing to the Marketplace

Block registries serve as the distribution mechanism for the Diagram-Design plugin marketplace. Published blocks reside in hidden plugin directories as JSON metadata files.

The primary marketplace storage locations include:

- [`.factory-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/marketplace.json): Core factory plugin registry
- [`.codex-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/marketplace.json): Extended codex plugin registry

These files mirror the export registry schema, allowing seamless integration between local development exports and public marketplace distribution. When publishing blocks, developers submit their validated registry entries to these marketplace JSON files, making components available for installation across the ecosystem.

## Consuming Registry Data Programmatically

Registry files enable programmatic block discovery and integration. Load and iterate through block definitions using standard JSON parsing:

```python
import json
import pathlib

# Load exported registry

registry_path = pathlib.Path('my-registry.json')
registry = json.loads(registry_path.read_text())

# Process block definitions

for block in registry['blocks']:
    print(f"{block['id']}: {block['name']} ({block['category']})")
    # Access input/output specifications

    inputs = block.get('inputs', [])
    outputs = block.get('outputs', [])

```

This approach supports automated documentation generation, dynamic block loading, and third-party tool integration.

## Summary

- **Block registry metadata system**: A JSON-based catalog defining reusable diagram components with standardized fields including `id`, `name`, `category`, `inputs`, and `outputs`
- **CLI export**: Use `diagram-design export --registry <path>` to generate registry files from current projects
- **Automated validation**: The [`scripts/verify-block-registry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-block-registry.py) script enforces unique IDs, required fields, and schema compliance in CI pipelines
- **Marketplace integration**: Registry entries publish to [`.factory-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/marketplace.json) and similar plugin-specific JSON files for ecosystem distribution
- **Programmatic access**: Standard JSON parsing enables custom tooling and dynamic block discovery

## Frequently Asked Questions

### What format does the block registry metadata system use?

The system uses JSON files with a top-level `blocks` array containing individual block objects. Each object requires `id`, `name`, and `category` fields, with optional specifications for `inputs`, `outputs`, `icon`, and `defaultProperties`. The schema is documented in [`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md).

### How do I validate my block registry before submitting to the marketplace?

Run `python scripts/verify-block-registry.py <registry.json>` locally to check for duplicate IDs, missing required fields, and type conformance. This mirrors the CI verification step defined in [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) and prevents malformed entries from breaking the marketplace.

### Can I export block definitions from existing diagrams?

Yes. Use the CLI command `diagram-design export <diagram-file> --registry <output.json>` to extract block metadata from any `.dd` diagram file into a portable registry format compatible with the marketplace schema.

### Where are published blocks stored in the repository?

Published block metadata resides in plugin-specific marketplace JSON files such as [`.factory-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/marketplace.json) and [`.codex-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/marketplace.json), located in hidden plugin directories at the repository root. These files use the same schema as CLI-exported registries.