365 lines
12 KiB
Markdown
365 lines
12 KiB
Markdown
# 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:
|
|
|
|
1. **GitHub/GitLab Markdown** - Automatic rendering in .md files
|
|
2. **Mermaid Live Editor** - https://mermaid.live
|
|
3. **VS Code Extension** - Markdown Preview Mermaid Support
|
|
4. **Obsidian** - Native Mermaid support
|
|
5. **Typora** - Built-in diagram rendering
|
|
6. **MkDocs** - With mermaid2 plugin
|
|
7. **Sphinx** - With sphinxcontrib-mermaid
|
|
|
|
**Command-line rendering**:
|
|
```bash
|
|
# 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**:
|
|
1. ❌ Conflicting URIs for slots defined in multiple modules (e.g., `created`)
|
|
2. ❌ Unknown CURIE prefix errors (linkml:types in isolated modules)
|
|
3. ❌ Generated diagrams are too verbose for documentation
|
|
|
|
**Benefits of manual Mermaid**:
|
|
1. ✅ Full control over layout and styling
|
|
2. ✅ Focus on key relationships (omit implementation details)
|
|
3. ✅ Add explanatory notes and color coding
|
|
4. ✅ Show real-world examples (not just schema structure)
|
|
5. ✅ Render perfectly in GitHub, GitLab, Obsidian, VS Code
|
|
|
|
---
|
|
|
|
## Usage in Documentation
|
|
|
|
### In AGENTS.md
|
|
```markdown
|
|
## 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
|
|
```markdown
|
|
## 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
|
|
```markdown
|
|
## 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
|
|
|
|
```mermaid
|
|
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** ✅
|