glam/MERMAID_GENERATORS_EXPLAINED.md

Mermaid Diagram Generators - Source and Purpose

Your Questions Answered

Q1: Were these solely generated by the LinkML repo?

NO - You have TWO sources:

File Type	Generator	Source
21 × .md files	gen-mermaid-class-diagram	✅ LinkML official (from LinkML repo)
1 × .mmd file (working)	owl_to_mermaid.py	❌ Custom script (local project)
1 × .mmd ER diagram	gen-erdiagram	✅ LinkML official (from LinkML repo)

Details:

1. LinkML Official Generators (installed via pip install linkml):

   • gen-mermaid-class-diagram → Creates 21 .md files (one per class)
   • gen-erdiagram → Creates 1 .mmd ER diagram (all classes)

2. Custom Project Script (in scripts/owl_to_mermaid.py):

   • Parses OWL/Turtle RDF
   • Generates single .mmd file with all classes
   • Workaround for when LinkML generators don't meet specific needs

---

Q2: Which represents the total ontology overview?

Answer: The Entity-Relationship Diagram is the total overview:

schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd

Why this is the "total ontology overview":

• ✅ Shows ALL 35 classes in one diagram
• ✅ Shows ALL properties for each class
• ✅ Shows relationships between classes
• ✅ Generated directly from 01_custodian_name_modular.yaml
• ✅ Single comprehensive view (not 21 separate files)

Generated by: gen-erdiagram -f mermaid 01_custodian_name_modular.yaml

---

Complete Breakdown

Source: 01_custodian_name_modular.yaml

This schema file generates THREE types of Mermaid outputs:

1. ER Diagram ✅ TOTAL ONTOLOGY OVERVIEW

Generator: gen-erdiagram -f mermaid (LinkML official)

Output: Single comprehensive diagram

schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd

Size: 8KB, 173 lines, 35 classes

What it shows:

• All classes as entities
• All properties per class
• Relationships between classes
• Property types (date, string, etc.)

Example content:

erDiagram
Custodian {
    uriorcurie hc_id  
    datetime created  
    datetime modified  
}
CustodianLegalStatus {
    date dissolution_date  
    string reconstruction_method  
}
... (33 more classes)

Use case: This is your "total ontology overview" - open this in Mermaid Live Editor or GitHub to see everything at once.

---

2. Individual Class Diagrams (21 × .md files)

Generator: gen-mermaid-class-diagram -d output_dir (LinkML official)

Output: 21 Markdown files with embedded Mermaid diagrams

schemas/20251121/uml/mermaid/Custodian.md
schemas/20251121/uml/mermaid/CustodianLegalStatus.md
schemas/20251121/uml/mermaid/CustodianName.md
... (18 more)

What it shows:

• One class per file
• Properties for that class
• Relationships to OTHER classes (with clickable links)
• Cardinality (0..1, 1, *, etc.)

Example content (Custodian.md):

```mermaid
 classDiagram
    class Custodian
      Custodian : hc_id
      Custodian : created
      Custodian : modified
      Custodian --> "*" CustodianAppellation : appellations
      Custodian --> "0..1" CustodianLegalStatus : legal_status
` ``

Use case: Interactive exploration - click between related classes, focus on one class at a time. Best for GitHub documentation.

---

3. Comprehensive Class Diagram (1 × .mmd file) ⚠️ Custom

Generator: owl_to_mermaid.py (custom script, NOT LinkML)

Output: Single .mmd file with all classes

schemas/20251121/uml/mermaid/custodian_multi_aspect_20251122_155319.mmd

Size: 1.6KB

What it shows:

• All classes in classDiagram syntax (NOT ER diagram)
• Inheritance relationships (subClassOf)
• No properties (class names only)

Example content:

classDiagram
    class Custodian {
    }
    class CustodianLegalStatus {
    }
    ... (35 classes with inheritance arrows)

Use case: Quick overview of class hierarchy. Less detailed than ER diagram.

Note: Recent runs produced empty files (0 bytes) - only the 155319 timestamp works.

---

Comparison Table

Diagram Type	Generator	Source	Classes	Properties	Relationships	File Count	Total Overview?
ER Diagram	gen-erdiagram	LinkML	35	✅ All	✅ Yes	1	✅ YES
Individual .md	gen-mermaid-class-diagram	LinkML	1 per file	✅ Per class	✅ Yes	21	❌ No (fragmented)
Comprehensive .mmd	owl_to_mermaid.py	Custom	35	❌ No	✅ Inheritance	1	⚠️ Partial (no properties)

---

Recommended Usage

For "Total Ontology Overview" → Use ER Diagram

# View in Mermaid Live Editor
cat schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd

# Copy content to: https://mermaid.live

# Or push to GitHub and view in browser (auto-renders)

This is the definitive "total ontology overview" because:

• ✅ Shows ALL classes
• ✅ Shows ALL properties
• ✅ Shows ALL relationships
• ✅ Single file, comprehensive view

---

For Interactive Exploration → Use Individual .md Files

# Navigate class by class
cat schemas/20251121/uml/mermaid/index_20251122_171316.md

# Open in VS Code or GitHub
code schemas/20251121/uml/mermaid/Custodian.md

Best for:

• GitHub documentation
• Clicking between related classes
• Focus on one class at a time

---

Generation Commands (for Reference)

1. Generate ER Diagram (Total Overview)

cd schemas/20251121/linkml
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

gen-erdiagram -f mermaid 01_custodian_name_modular.yaml \
  > ../uml/erdiagram/custodian_multi_aspect_${TIMESTAMP}.mmd

Output: custodian_multi_aspect_20251122_171249.mmd (8KB)

---

2. Generate Individual Class Diagrams

cd schemas/20251121/linkml

gen-mermaid-class-diagram -d ../uml/mermaid 01_custodian_name_modular.yaml

Output: 21 .md files in ../uml/mermaid/ (overwrites existing)

---

3. Generate Comprehensive Class Diagram (Custom)

TIMESTAMP=$(date +%Y%m%d_%H%M%S)

python3 scripts/owl_to_mermaid.py \
  schemas/20251121/rdf/custodian_multi_aspect_20251122_155319.owl.ttl \
  schemas/20251121/uml/mermaid/custodian_multi_aspect_${TIMESTAMP}.mmd

Output: Single .mmd file (class names + inheritance only)

---

Summary

Q1: Were these solely generated by the LinkML repo?

A1: NO - You have:

• ✅ LinkML official: gen-mermaid-class-diagram (21 .md files) + gen-erdiagram (1 ER .mmd)
• ❌ Custom script: owl_to_mermaid.py (1 comprehensive .mmd)

Q2: Which represents the total ontology overview?

A2: The ER Diagram at:

schemas/20251121/uml/erdiagram/custodian_multi_aspect_20251122_171249.mmd

This is the definitive total overview showing all 35 classes with properties and relationships in a single diagram.

---

Key Takeaway: Use the ER diagram for total overview, use the 21 .md files for interactive exploration.