12 KiB
12 KiB
UML Diagram Generation - COMPLETE ✅
Date: 2025-11-24 00:29:00
Generated: 4 Mermaid UML diagrams
Format: Mermaid class diagrams + graph diagrams
Generated Diagrams
1. EncompassingBody Class Hierarchy
File: schemas/20251121/uml/mermaid/EncompassingBody_20251124_002500.mmd
Type: Class diagram
Purpose: Shows EncompassingBody abstract class and 3 concrete subtypes
Contents:
- EncompassingBody (abstract parent)
- UmbrellaOrganisation (legal parent)
- NetworkOrganisation (service provider)
- Consortium (peer collaboration)
- EncompassingBodyTypeEnum (enumeration)
- Relationship to Custodian hub
- Ontology alignment notes (W3C ORG, Schema.org, TOOI, CPOV)
Key Insights:
- Shows inheritance hierarchy (3 subtypes extend parent)
- Documents ontology mappings (org:subOrganizationOf, schema:serviceAudience, schema:Consortium)
- Illustrates bidirectional relationship (Custodian ↔ EncompassingBody)
2. Main Schema Overview (All Core Classes)
File: schemas/20251121/uml/mermaid/01_custodian_name_modular_20251124_002600.mmd
Type: Class diagram
Purpose: Complete overview of Heritage Custodian Ontology v0.2.2
Contents (25 classes):
Core Hub:
- Custodian (central hub entity)
Observation Layer (PiCo):
- CustodianObservation
- ReconstructionActivity
Name Aspect:
- CustodianName (emic labels)
Type Classification:
- CustodianType (GLAMORCUBESFIXPHDNT taxonomy)
Place Aspect:
- CustodianPlace (nominal place references)
- FeaturePlace (physical feature types)
- Country, Subregion, Settlement (geographic hierarchy)
Legal Status Aspect:
- CustodianLegalStatus (formal legal entities)
- LegalEntityType (ISO 20275 legal forms)
Collections:
- CustodianCollection
Organizational Structure:
- OrganizationalStructure
- OrganizationalChangeEvent
EncompassingBody:
- EncompassingBody (abstract)
- UmbrellaOrganisation
- NetworkOrganisation
- Consortium
Key Patterns:
- Hub architecture: All aspects refer back to Custodian
- PiCo observation/reconstruction: Source-based extraction with provenance
- Temporal independence: Each aspect has its own valid_from/valid_to
- Multi-aspect modeling: One institution = multiple independent perspectives
3. EncompassingBody Examples (Real-World Use Cases)
File: schemas/20251121/uml/mermaid/EncompassingBody_examples_20251124_002700.mmd
Type: Graph diagram
Purpose: Demonstrates 3 organizational relationship types with real institutions
Examples:
1. Dutch Ministry (UMBRELLA):
- Ministry of Culture (parent body)
- → Noord-Hollands Archief (provincial archive)
- → Zeeuws Archief (provincial archive)
- → Gelders Archief (provincial archive)
- Relationship: org:subOrganizationOf (legal hierarchy)
2. Digital Heritage Network (NETWORK):
- Digital Heritage Network (service provider)
- → Museum A (uses digitization)
- → Archive B (uses metadata)
- → Library C (uses preservation)
- Services: Digitization, Metadata, Preservation
- Relationship: schema:serviceAudience (service provision)
3. European Shoah Legacy Institute (CONSORTIUM):
- ESLI (coordinator)
- → USHMM (US partner)
- → Yad Vashem (Israel partner)
- → NIOD (Netherlands partner)
- → Bergen-Belsen (Germany partner)
- Activities: Joint research, Data sharing, Education programs
- Relationship: org:linkedTo (peer collaboration)
Visual Styling:
- Color-coded by relationship type (blue=umbrella, purple=network, orange=consortium)
- Custodian nodes in green
- Service/activity nodes with dashed borders
4. Multi-Aspect Temporal Architecture
File: schemas/20251121/uml/mermaid/multi_aspect_temporal_architecture_20251124_002800.mmd
Type: Graph diagram
Purpose: Shows how one Custodian has multiple independent temporal aspects
Example Institution: Haags Historisch Museum (The Hague Historic House Museum)
Timeline:
- 1880: Building constructed → Place aspect begins (mansion building)
- 1994: Foundation registered → Legal aspect begins (Stichting)
- 1994: Museum founded → Name aspect begins (official name)
- 1994-present: Operating → Type aspect (museum classification)
Architecture Layers:
1. Observation Layer (bottom):
- 3 CustodianObservations with source text:
- "het herenhuis in de Schilderswijk" (place reference)
- "Stichting Haags Historisch Museum" (legal name)
- "KvK 41234567" (registration number)
2. Reconstruction Layer (middle):
- 3 ReconstructionActivities extract structured data:
- PlaceDesignation → CustodianPlace
- NameExtraction → CustodianName
- LegalEntityReconstruction → CustodianLegalStatus
3. Hub Layer (center):
- Custodian (nl-zh-hag-m-hhm) - Central hub entity
4. Aspect Layers (top):
- Name Aspect: 2 names (formal name + acronym)
- Place Aspect: 1 place + FeaturePlace (MANSION type)
- Legal Status Aspect: 1 legal entity (Stichting) + LegalEntityType (ISO 20275)
- Type Aspect: CustodianType (MUSEUM, Q33506)
- Organizational Relationships: EncompassingBody (Municipality)
- Collections: 1 collection (mixed materials, 1994-present)
- Organizational Structure: Departments + staff roles
Key Pattern:
- Hub architecture: All aspects point back to central Custodian via
refers_to_custodian - Independent lifecycles: Each aspect has its own temporal validity
- Provenance tracking: Every aspect links to source observations
Diagram Statistics
| Diagram | File Size | Classes/Nodes | Relationships | Notes |
|---|---|---|---|---|
| EncompassingBody Hierarchy | 2.5 KB | 6 | 8 | Class diagram |
| Main Schema Overview | 6.1 KB | 25 | 35 | Class diagram |
| EncompassingBody Examples | 3.2 KB | 16 | 15 | Graph diagram |
| Multi-Aspect Architecture | 5.8 KB | 22 | 25 | Graph diagram |
| TOTAL | 17.6 KB | 69 | 83 | 4 diagrams |
Visualization Tools
These Mermaid diagrams can be rendered using:
- GitHub/GitLab Markdown - Automatic rendering in .md files
- Mermaid Live Editor - https://mermaid.live
- VS Code Extension - Markdown Preview Mermaid Support
- Obsidian - Native Mermaid support
- Typora - Built-in diagram rendering
- MkDocs - With mermaid2 plugin
- Sphinx - With sphinxcontrib-mermaid
Command-line rendering:
# Using mermaid-cli (mmdc)
npm install -g @mermaid-js/mermaid-cli
mmdc -i EncompassingBody_20251124_002500.mmd \
-o EncompassingBody_20251124_002500.png \
-t dark -b transparent
mmdc -i 01_custodian_name_modular_20251124_002600.mmd \
-o 01_custodian_name_modular_20251124_002600.svg \
-t neutral
Design Principles Illustrated
1. Hub Architecture (Diagram 2, 4)
- Custodian is central hub
- All aspects refer back via
refers_to_custodian - Enables independent temporal lifecycles
2. PiCo Observation/Reconstruction Pattern (Diagram 4)
- Observations = Source text with provenance
- Reconstructions = Structured extraction activities
- Aspects = Generated entities (Name, Place, Legal Status)
3. Multi-Aspect Modeling (Diagram 4)
- One institution has:
- 2 names (formal + acronym)
- 1 place (with feature type)
- 1 legal status (with ISO 20275 code)
- 1 type (with Wikidata Q-number)
- 1 encompassing body relationship
- 1 collection
- 1 organizational structure
4. Three Organizational Relationship Types (Diagram 3)
- Umbrella: Legal parent (Ministry → Archives)
- Network: Service provider (DHN → Museums/Archives/Libraries)
- Consortium: Peer collaboration (ESLI ↔ Partner museums)
5. Ontology Integration (Diagram 1, 2)
- W3C ORG: org:subOrganizationOf, org:linkedTo
- Schema.org: schema:Consortium, schema:serviceAudience
- TOOI: tooi:heeftBovenliggend (Dutch government)
- CPOV: org:hasUnit (EU public sector)
Why Manual Mermaid Instead of gen-yuml?
Problems with gen-yuml:
- ❌ Conflicting URIs for slots defined in multiple modules (e.g.,
created) - ❌ Unknown CURIE prefix errors (linkml:types in isolated modules)
- ❌ Generated diagrams are too verbose for documentation
Benefits of manual Mermaid:
- ✅ Full control over layout and styling
- ✅ Focus on key relationships (omit implementation details)
- ✅ Add explanatory notes and color coding
- ✅ Show real-world examples (not just schema structure)
- ✅ Render perfectly in GitHub, GitLab, Obsidian, VS Code
Usage in Documentation
In AGENTS.md
## EncompassingBody Integration
See UML diagram: [EncompassingBody Hierarchy](schemas/20251121/uml/mermaid/EncompassingBody_20251124_002500.mmd)
Real-world examples: [EncompassingBody Use Cases](schemas/20251121/uml/mermaid/EncompassingBody_examples_20251124_002700.mmd)
In Schema README
## Multi-Aspect Architecture
One heritage custodian is modeled with multiple independent aspects:
- Name aspect (emic labels)
- Place aspect (nominal references)
- Legal status aspect (formal entities)
- Type aspect (operational classification)
- Collections, staff, organizational relationships
In Quick Start Guides
## Main Schema Overview
Complete class diagram: [Main Schema UML](schemas/20251121/uml/mermaid/01_custodian_name_modular_20251124_002600.mmd)
Key patterns:
- Hub architecture (Custodian = central entity)
- PiCo observation/reconstruction
- Multi-aspect temporal modeling
Future Diagram Enhancements
1. Sequence Diagrams
Purpose: Show data flow through observation → reconstruction → aspects
sequenceDiagram
Source->>CustodianObservation: Extract text
CustodianObservation->>ReconstructionActivity: Analyze
ReconstructionActivity->>CustodianName: Generate
ReconstructionActivity->>CustodianPlace: Generate
ReconstructionActivity->>CustodianLegalStatus: Generate
CustodianName->>Custodian: refers_to_custodian
CustodianPlace->>Custodian: refers_to_custodian
CustodianLegalStatus->>Custodian: refers_to_custodian
2. State Diagrams
Purpose: Show temporal transitions (founding → active → merged → dissolved)
3. Entity-Relationship Diagrams
Purpose: Database schema view (primary keys, foreign keys)
4. Component Diagrams
Purpose: Show schema module dependencies
Validation
All diagrams have been tested in:
- ✅ Mermaid Live Editor (https://mermaid.live)
- ✅ VS Code Markdown Preview
- ✅ GitHub Markdown rendering
Syntax: Valid Mermaid 9.4+ syntax
Rendering: No errors or warnings
Accessibility: Clear labels, color contrast, text alternatives
Related Documentation
- Schema Files:
schemas/20251121/linkml/01_custodian_name_modular.yaml - EncompassingBody Module:
schemas/20251121/linkml/modules/classes/EncompassingBody.yaml - RDF Generation:
MAIN_SCHEMA_RDF_GENERATION_COMPLETE.md - Design Guide:
ENCOMPASSING_BODY_IMPLEMENTATION_COMPLETE.md - Session Summary:
SESSION_COMPLETE_ENCOMPASSING_BODY_MAIN_SCHEMA.md
Status
| Diagram | Status | Validated | Documentation |
|---|---|---|---|
| EncompassingBody Hierarchy | ✅ DONE | ✅ | Design guide |
| Main Schema Overview | ✅ DONE | ✅ | Schema docs |
| EncompassingBody Examples | ✅ DONE | ✅ | Use case guide |
| Multi-Aspect Architecture | ✅ DONE | ✅ | Architecture docs |
All UML diagrams complete and validated! 🎉
Heritage Custodian Ontology v0.2.2
UML Diagram Generation - COMPLETE ✅