kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/SESSION_SUMMARY_20251122_CUSTODIAN_MULTI_ASPECT.md
kempersc 8907aa6213 feat: Refactor Heritage Custodian Ontology to Multi-Aspect Model 
- Implemented three independent aspects for custodians: CustodianLegalStatus, CustodianName, and CustodianPlace.
- Renamed CustodianReconstruction to CustodianLegalStatus and updated all references.
- Created new components for CustodianPlace and PlaceSpecificityEnum.
- Removed direct links from CustodianObservation to Custodian, aligning with PROV-O standards.
- Generated comprehensive example instance demonstrating the new architecture.
- Updated documentation to reflect changes and provide guidance on multi-aspect modeling.
- Added React hook for managing IndexedDB operations, including storing and loading transformation results.
- Created complete YAML example for Rijksmuseum, illustrating the integration of all three aspects.
2025-11-22 15:40:17 +01:00

298 lines
11 KiB
Markdown
Raw Blame History

# Session Summary: Custodian Multi-Aspect Refactoring
**Date**: 2025-11-22
**Duration**: Full session
**Participants**: User + AI Assistant
**Status**: ✅ COMPLETE IMPLEMENTATION
---
## What We Accomplished
### Phase 1: Critical PROV-O Fixes (Earlier Session)
1. ✅ Moved `confidence_score` from result (CustodianReconstruction) → process (ReconstructionActivity)
2. ✅ Changed CustodianName from inheritance (is_a) → derivation (prov:wasDerivedFrom)
3. ✅ Added `used` slot to ReconstructionActivity (links to CustodianObservation inputs)
4. ✅ Added `preferred_label` to Custodian hub (links to CustodianName)
**Result**: Proper PROV-O observation → activity → entity flow
---
### Phase 2: Multi-Aspect Architecture (This Session)
#### Major Conceptual Change
Refactored custodians from **monolithic reconstruction** to **three independent aspects**:
1. **CustodianLegalStatus** - Formal legal entity (precise, registered)
- Example: "Stichting Rijksmuseum" with KvK 41215422
2. **CustodianName** - Emic label (ambiguous, contextual)
- Example: "Rijksmuseum" (how it presents itself)
3. **CustodianPlace** - Nominal place designation (NOT coordinates!)
- Example: "het museum op het Museumplein" (place reference)
#### Implementation Steps
**1. Renamed Class** ✅
- `CustodianReconstruction.yaml` → `CustodianLegalStatus.yaml`
- Updated `class_uri` to `org:FormalOrganization`
- Clarified this represents ONE ASPECT (legal dimension)
**2. Created CustodianPlace Class** ✅
- New file: `modules/classes/CustodianPlace.yaml`
- `class_uri`: `crm:E53_Place` (CIDOC-CRM place entity)
- Created `PlaceSpecificityEnum` (BUILDING, STREET, NEIGHBORHOOD, CITY, REGION, VAGUE)
- Created 4 slot definitions (place_name, place_language, place_specificity, place_note)
**3. Removed Observation → Hub Link** ✅
- Deleted `refers_to_custodian` from CustodianObservation
- **CRITICAL**: Observations are INPUT to ReconstructionActivity, not assertions of identity
- Only generated aspects (LegalStatus/Name/Place) link to Custodian hub
**4. Updated Custodian Hub** ✅
- Added `legal_status` slot → CustodianLegalStatus
- Added `place_designation` slot → CustodianPlace
- Hub now aggregates THREE independent aspects
**5. Updated Main Schema** ✅
- Added imports for CustodianPlace, PlaceSpecificityEnum, all new slots
- Renamed all references: CustodianReconstruction → CustodianLegalStatus
- Updated documentation to reflect multi-aspect architecture
**6. Batch Updated 22+ Files** ✅
- All module files with CustodianReconstruction references updated
- `sed -i '' 's/CustodianReconstruction/CustodianLegalStatus/g'`
---
## Generated Artifacts
### Validation ✅
```bash
gen-owl -f ttl schemas/20251121/linkml/01_custodian_name_modular.yaml
```
- **Result**: 2,630 lines OWL/Turtle, no critical errors
- ✅ 34 CustodianLegalStatus references
- ✅ 15 CustodianPlace references
- ✅ 21 PlaceSpecificityEnum references
### RDF Serializations (4 formats) ✅
1. OWL/Turtle: `01_custodian_multi_aspect.owl.ttl` (160KB)
2. N-Triples: `01_custodian_multi_aspect.nt` (4KB)
3. JSON-LD: `01_custodian_multi_aspect.jsonld` (4KB)
4. RDF/XML: `01_custodian_multi_aspect.rdf` (4KB)
### UML Diagram ✅
- Mermaid: `01_custodian_multi_aspect.mmd` (745B)
### Example Instance ✅
- `multi_aspect_rijksmuseum_complete.yaml` (~200 lines)
- Demonstrates all three aspects working together
- Shows PROV-O observation → activity → entity flow
- Includes confidence measures and temporal validity
---
## Architecture Pattern
### Before (INCORRECT)
```
CustodianObservation → refers_to_custodian → Custodian
CustodianReconstruction → refers_to_custodian → Custodian
```
Problems:
- Observations directly asserted identity (they're just evidence!)
- Monolithic "Reconstruction" mixed legal, name, and place
- No way to model independent temporal change
### After (CORRECT)
```
CustodianObservation → prov:used → ReconstructionActivity
ReconstructionActivity → prov:wasGeneratedBy → LegalStatus/Name/Place
LegalStatus/Name/Place → refers_to_custodian → Custodian (hub)
```
Benefits:
- ✅ Observations are input (not assertions)
- ✅ Three independent aspects with distinct semantics
- ✅ Each aspect can change over time independently
- ✅ Source transparency (all aspects derive from observations)
- ✅ Proper PROV-O flow
---
## Key Principles Established
1. **Multi-Aspect Modeling**: Custodians have THREE independent aspects
- Legal status (precise, formal)
- Name (ambiguous, contextual)
- Place (nominal, may be vague)
2. **Observations Are Input**: CustodianObservation does NOT link to Custodian
- Only ReconstructionActivity determines identity
3. **Activity Generates Aspects**: ReconstructionActivity may generate 0-3 aspects
- Can have legal status without name (or vice versa)
- Informal groups may lack legal status
4. **Hub Aggregates Aspects**: Custodian links to all three aspects
- `legal_status` → CustodianLegalStatus
- `preferred_label` → CustodianName
- `place_designation` → CustodianPlace
5. **Nominal ≠ Geographic**: CustodianPlace (nominal) ≠ Location (coordinates)
- Place: "het herenhuis in de Schilderswijk"
- Location: lat 52.0705, lon 4.2894
---
## Files Affected (42+ files)
### New Files (8)
1. `modules/classes/CustodianPlace.yaml`
2. `modules/enums/PlaceSpecificityEnum.yaml`
3. `modules/slots/place_designation.yaml`
4. `modules/slots/place_name.yaml`
5. `modules/slots/place_language.yaml`
6. `modules/slots/place_specificity.yaml`
7. `modules/slots/place_note.yaml`
8. `examples/multi_aspect_rijksmuseum_complete.yaml`
### Renamed Files (1)
1. `modules/classes/CustodianReconstruction.yaml` → `CustodianLegalStatus.yaml`
### Modified Files (5)
1. `modules/classes/CustodianObservation.yaml` (removed refers_to_custodian)
2. `modules/classes/Custodian.yaml` (added legal_status + place_designation)
3. `modules/classes/CustodianName.yaml` (already updated)
4. `modules/classes/CustodianLegalStatus.yaml` (updated description)
5. `01_custodian_name_modular.yaml` (updated imports + documentation)
### Batch Updated (22+ files)
- All module files with CustodianReconstruction references
### Generated Artifacts (6 files)
1. `rdf/01_custodian_multi_aspect.owl.ttl`
2. `rdf/01_custodian_multi_aspect.nt`
3. `rdf/01_custodian_multi_aspect.jsonld`
4. `rdf/01_custodian_multi_aspect.rdf`
5. `uml/mermaid/01_custodian_multi_aspect.mmd`
6. `QUICK_STATUS_CUSTODIAN_SCHEMA_MOD_20251122.md`
---
## Documentation Created
1. **QUICK_STATUS_CUSTODIAN_SCHEMA_MOD_20251122.md** - Quick reference summary
2. **CUSTODIAN_MULTI_ASPECT_REFACTORING.md** - Complete implementation guide
3. **SESSION_SUMMARY_20251122_CUSTODIAN_MULTI_ASPECT.md** - This document
---
## Impact Assessment
### Breaking Changes ⚠️
1. **CustodianReconstruction class no longer exists** - renamed to CustodianLegalStatus
2. **CustodianObservation no longer links to Custodian** - removed refers_to_custodian
3. **Custodian hub structure changed** - added legal_status + place_designation slots
### Data Migration Required
- Update instances using CustodianReconstruction → CustodianLegalStatus
- Remove direct observation → custodian links
- Add legal_status and place_designation to custodian hubs
### Benefits
1. **Precision**: Clear separation of legal (precise) vs. name (ambiguous) vs. place (nominal)
2. **Flexibility**: Can have legal status without name (or vice versa)
3. **Temporal modeling**: Each aspect changes independently
4. **Source transparency**: All aspects derived from observations
5. **Ontology alignment**: Better CIDOC-CRM, PROV-O, W3C Org mapping
---
## Next Actions
### Immediate (Before Commit)
- [x] Schema validation - DONE
- [x] RDF generation - DONE
- [x] UML generation - DONE
- [x] Example instance - DONE
- [x] Documentation - DONE
### Short-term (This Week)
- [ ] Migrate existing example instances
- [ ] Create data migration script
- [ ] Update AGENTS.md with multi-aspect guidance
- [ ] Create multi-aspect modeling guide for users
### Medium-term (Next Sprint)
- [ ] Additional example instances (individuals, groups, governments)
- [ ] Update PROV-O alignment documentation
- [ ] Generate TypeDB schema from LinkML
- [ ] Create Mermaid visualization of PROV-O flow
### Long-term (Future Phases)
- [ ] Implement Collection aspect (fourth aspect)
- [ ] Add Event aspect (organizational change events)
- [ ] Create Person aspect (staff, curators via PiCo)
- [ ] Full TOOI, CPOV, CIDOC-CRM integration
---
## Lessons Learned
1. **Ontology design requires iterative refinement** - Started with monolithic "Reconstruction", evolved to multi-aspect
2. **PROV-O patterns matter** - Observations are INPUT (not assertions), activities generate entities
3. **Separation of concerns improves clarity** - Legal ≠ Name ≠ Place (each has distinct semantics)
4. **LinkML modular architecture enables rapid iteration** - Changed 8+ files but validated immediately
5. **Example instances are critical** - Complete Rijksmuseum example demonstrates all three aspects
6. **RDF generation from LinkML works well** - Generated 4 RDF formats with single command
7. **Documentation is essential** - Created 3 documents to ensure next agent can continue work
---
## Handoff to Next Session
### Current State
✅ Schema fully implemented and validated
✅ RDF and UML generated
✅ Complete example instance created
✅ All documentation written
### Ready For
1. Data migration (existing instances → multi-aspect pattern)
2. Additional example instances
3. User-facing modeling guide
4. TypeDB schema generation
### Key Files to Review
1. `QUICK_STATUS_CUSTODIAN_SCHEMA_MOD_20251122.md` - Quick reference
2. `CUSTODIAN_MULTI_ASPECT_REFACTORING.md` - Implementation guide
3. `schemas/20251121/examples/multi_aspect_rijksmuseum_complete.yaml` - Complete example
4. `schemas/20251121/linkml/modules/classes/` - Class definitions
### Questions to Consider
1. Should we create a fourth aspect for Collections?
2. How should organizational change events integrate with aspects?
3. Should Person aspect follow PiCo pattern or multi-aspect pattern?
4. How to visualize multi-aspect temporal change in UML?
---
**Session Status**: ✅ COMPLETE
**Next Session**: Data migration + additional examples
**Schema Version**: 0.1.0 (modular LinkML)
**Impact**: Breaking change - Multi-aspect architecture
---
**Key Takeaway**: The Heritage Custodian Ontology now properly models custodians as multi-aspect entities with three independent facets (legal status, name, place), all derived from observations through formal reconstruction activities. This provides the foundation for nuanced, temporally-aware, source-transparent heritage metadata.
Reference in a new issue View git blame Copy permalink