erd-studio

ERD Studio — AI Data Modeling Guide

ERD Studio uses a central model store architecture. Model definitions are YAML files in .erd-studio/logical-models/. Domain JSON files reference models by name and define relationships and layout.

Architecture Overview

.erd-studio/
├── logical-models/           ← Central model definitions (YAML, one per model)
│   ├── dim_customer.yml
│   ├── dim_project.yml
│   └── fct_sale.yml
├── silver/
│   ├── customer-360.json     ← Domain file (model references + relationships + layout)
│   └── orders.json
└── gold/
    └── reporting.json

Key principle: Models are defined ONCE in logical-models/ and referenced from multiple domain files. Editing a model from any domain updates the shared definition.

Model Library (Sidebar)

The Model Library panel in the ERD Studio sidebar shows all YAML files in logical-models/. Use it to understand the difference between "model definition exists" and "model is referenced by a domain":

• Referenced models show how many domains use them (e.g. "2 domains")
• Orphaned models show a warning icon and "(unused)" — these exist as .yml files but are not in any domain's logical.models[] array

Important for AI agents: Before saying a model "already exists in the ERD", check whether it is referenced by the target domain's logical.models[] array — not just whether the .yml file exists. A model file in logical-models/ may be unused (orphaned) or only referenced by other domains.

Domain File Structure

File: .erd-studio/{layer}/{domain}.json

{
  "schemaVersion": 5,
  "domain": "customer-360",
  "layer": "silver",
  "description": "Customer domain — master data and transaction history",
  "modelFolder": "models/silver",
  "stubColumns": ["dim_project"],
  "logical": {
    "models": ["dim_customer", "fct_sale", "dim_product", "dim_project"],
    "relationships": []
  },
  "viewConfig": {}
}

Field	Required	Description
schemaVersion	Yes	Must be 5
domain	Yes	Domain slug (matches filename without .json)
layer	Yes	Layer name matching parent directory (e.g. silver, gold)
description	No	Human-readable domain description
modelFolder	No	Filter for "Add Existing Model" dialog (e.g. models/silver)
stubColumns	No	Model names whose physical-only columns are suppressed in sync comparison. Use for conformed dimensions and reference tables included only to anchor relationships — they define a few key columns (PK/NK) but not the full physical column set. Missing-column discrepancies are hidden; extra and type-mismatch discrepancies on defined columns still surface.
logical.models	Yes	Array of model name strings (references to logical-models/*.yml)
logical.relationships	Yes	Array of relationship objects
viewConfig	Yes	Root-level view settings. The extension auto-assigns positions for new models