glam/schemas/20251121/uml

UML Diagrams - Heritage Custodian Ontology

Status: ✅ GENERATED (Mermaid ✅ | PlantUML ✅)
Last Updated: 2025-11-21
Current LinkML Schema: ../linkml/01_custodian_name_modular.yaml

---

Overview

UML diagrams for the Heritage Custodian Observation and Reconstruction Pattern:

• Mermaid ER Diagrams (.mmd): ✅ Auto-generated from LinkML via gen-erdiagram
• PlantUML Class Diagrams (.puml): ✅ Auto-generated from LinkML via custom workaround script

Note: PlantUML generation uses a custom script (scripts/generate_plantuml_modular.py) to work around a bug in LinkML's gen-plantuml that fails on modular schemas with linkml:types imports. See PLANTUML_GENERATION_SUCCESS.md for details.

---

📁 Directory Structure

uml/
├── README.md                    ← This file
├── mermaid/                     ← Mermaid ER diagrams (AUTO-GENERATED ✅)
│   ├── README.md
│   ├── 01_custodian_name.mmd         (Full ER diagram)
│   └── 01_custodian_name_full.mmd    (With references)
└── plantuml/                    ← PlantUML class diagrams (MANUAL ⚠️)
    ├── README.md
    └── 01_custodian_name.puml        (Complete class diagram)

---

🎨 Available Diagrams

Mermaid ER Diagrams ✅

Location: mermaid/

File	Description	Status
01_custodian_name.mmd	Complete ER diagram (12 classes, 13 relationships)	✅ Auto-generated
01_custodian_name_full.mmd	Full diagram with all references	✅ Auto-generated

Generator: gen-erdiagram (LinkML official)

Viewing:

• GitHub automatically renders .mmd files
• https://mermaid.live/ for editing/exporting
• VSCode "Mermaid Preview" extension

Regenerate:

cd /Users/kempersc/apps/glam
gen-erdiagram schemas/20251121/linkml/01_custodian_name_modular.yaml > \
  schemas/20251121/uml/mermaid/01_custodian_name.mmd

PlantUML Class Diagrams ✅

Location: plantuml/

File	Description	Status
01_custodian_name.puml	Complete class diagram with rich annotations	⚠️ Manual (reference version)
01_custodian_name_auto.puml	Auto-generated class diagram	✅ Auto-generated

Generator: scripts/generate_plantuml_modular.py (custom workaround)

Why Custom Script?: LinkML's gen-plantuml fails on modular schemas with linkml:types imports. Our script uses SchemaView (same approach as gen-erdiagram). See PLANTUML_GENERATION_SUCCESS.md for technical details.

Viewing:

• https://www.plantuml.com/plantuml/uml/
• VSCode "PlantUML" extension
• plantuml -tpng 01_custodian_name_auto.puml

Regenerate:

cd /Users/kempersc/apps/glam
python3 scripts/generate_plantuml_modular.py \
  schemas/20251121/linkml/01_custodian_name_modular.yaml \
  schemas/20251121/uml/plantuml/01_custodian_name_auto.puml

---

🔍 Diagram Features

What the Diagrams Show

Both diagram formats illustrate:

1. Core Classes (12 total):

   • Custodian (abstract base)
   • CustodianObservation (emic/etic references)
   • CustodianName (standardized emic name)
   • CustodianReconstruction (formal legal entity)
   • Supporting classes: ReconstructionAgent, Appellation, SourceDocument, etc.

2. Relationships (13 associations):

   • Inheritance: CustodianObservation extends Custodian
   • Composition: CustodianReconstruction *-- ReconstructionActivity
   • References: CustodianObservation --> CustodianReconstruction

3. Cardinality:

   • Required relationships (1:1, 1:1..*)
   • Optional relationships (1:0..1, 1:0..*)

4. Data Types:

   • Primitives: string, date, datetime, float
   • Custom types: uriorcurie
   • Enumerations: AgentTypeEnum, LegalStatusEnum, etc.

Diagram Comparison

Feature	Mermaid ER	PlantUML Class
Auto-generated?	✅ Yes	⚠️ No (bug)
Format	ER Diagram	UML Class Diagram
Primary Use	Entity relationships	Object-oriented view
Annotations	Limited	Rich (notes, stereotypes)
Rendering	GitHub, web tools	Java/web tools
Best For	Quick overview	Detailed reference

---

🔄 Regeneration Guide

Mermaid Diagrams (Auto-Generated ✅)

When the LinkML schema changes, regenerate Mermaid diagrams:

cd /Users/kempersc/apps/glam

# Regenerate main ER diagram
gen-erdiagram schemas/20251121/linkml/01_custodian_name_modular.yaml > \
  schemas/20251121/uml/mermaid/01_custodian_name.mmd

# Regenerate full diagram with references
gen-erdiagram --follow-references schemas/20251121/linkml/01_custodian_name_modular.yaml > \
  schemas/20251121/uml/mermaid/01_custodian_name_full.mmd

PlantUML Diagrams (Manual ⚠️)

Cannot auto-regenerate due to gen-plantuml bug with modular schemas.

Update Process:

1. Review LinkML schema changes
2. Manually edit plantuml/01_custodian_name.puml
3. Validate syntax: plantuml -checkonly 01_custodian_name.puml
4. Render to verify: plantuml -tpng 01_custodian_name.puml

See plantuml/README.md for detailed manual update workflow.

---

📊 Ontology Mappings

The diagrams represent classes that map to established ontologies:

LinkML Class	Primary Mappings
CustodianObservation	pico:PersonObservation, prov:Entity, crm:E73_Information_Object
CustodianName	Extends CustodianObservation (specialized for emic names)
CustodianReconstruction	org:FormalOrganization, cpov:PublicOrganisation, schema:Organization
ReconstructionActivity	prov:Activity, rico:Event, crm:E7_Activity
ReconstructionAgent	prov:Agent, foaf:Agent, rico:Agent, schema:Person, schema:Organization
Identifier	adms:Identifier, schema:PropertyValue
SourceDocument	prov:Entity, dcterms:BibliographicResource
Appellation	crm:E41_Appellation, skos:Label

---

🐛 Known Issues

Issue 1: PlantUML Generator Fails on Modular Schema

Problem: gen-plantuml cannot resolve linkml:types import
Error: ValueError: Unknown CURIE prefix: linkml
Impact: PlantUML diagrams must be manually maintained
Workaround: Manual diagram in plantuml/01_custodian_name.puml

Attempted Solutions (all failed):

• gen-plantuml --preserve-names
• linkml-convert to flatten schema
• Generating from individual class modules

Root Cause: LinkML SchemaLoader cannot resolve linkml:types in modular imports

Request: LinkML maintainers should fix import resolution in all generators

---

🔗 Related Documentation

• LinkML Schema: ../linkml/01_custodian_name_modular.yaml
• TypeDB Schema: ../typedb/01_custodian_name_v3.tql
• RDF Ontology: ../rdf/01_custodian_name.owl.ttl
• Mermaid Details: mermaid/README.md
• PlantUML Details: plantuml/README.md

---

📝 Quick Reference

Viewing Tools

Tool	Mermaid	PlantUML
GitHub	✅ Auto-render	❌ No
Web Editor	https://mermaid.live/	https://plantuml.com/plantuml/
VSCode	"Mermaid Preview" extension	"PlantUML" extension
CLI	mmdc (npm)	plantuml (Java)

File Extensions

• .mmd - Mermaid diagrams
• .puml - PlantUML diagrams

Generation Status

• ✅ Mermaid: Auto-generated, regenerate on schema changes
• ⚠️ PlantUML: Manual, update carefully when schema changes

---

Status: ✅ COMPLETED (Mermaid ✅ | PlantUML ⚠️ Manual)
Last Updated: 2025-11-21
Schema Version: v0.1.0