Understanding the Block Registry Metadata System in Diagram-Design

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

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, producing a file structure similar to:

{
  "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, a Python utility that enforces registry quality standards. This script runs automatically in CI pipelines (configured in .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:

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: Core factory plugin registry
• .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:

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 script enforces unique IDs, required fields, and schema compliance in CI pipelines
• Marketplace integration: Registry entries publish to .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.

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 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 and .codex-plugin/marketplace.json, located in hidden plugin directories at the repository root. These files use the same schema as CLI-exported registries.

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