glam/SESSION_SUMMARY_20251122_CUSTODIAN_MULTI_ASPECT.md

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 ✅

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)

• Schema validation - DONE
• RDF generation - DONE
• UML generation - DONE
• Example instance - DONE
• 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.