# Custodian Multi-Aspect Refactoring
Date: 2025-11-22  
Status: 🚨 CRITICAL ARCHITECTURE REFINEMENT  
Priority: HIGH - Multi-aspect entity modeling

## Summary

Refine the observation-reconstruction pattern to properly model heritage custodians as **multi-aspect entities** with three independent facets:

1. **CustodianLegalStatus** - Formal legal entity (precise, registered)
2. **CustodianName** - Emic label (ambiguous, contextual)
3. **CustodianPlace** - Nominal place designation (not coordinates!)

All three aspects are **possible outputs** of ReconstructionActivity and **independently identify** the Custodian hub.

---

## Architectural Principles

### 1. Custodian as Multi-Aspect Hub

The Custodian class is an **aggregation hub** for three independent aspects:

```
CustodianObservation (Evidence)
        ↓ prov:used
ReconstructionActivity (Process)
        ↓ prov:wasGeneratedBy (multiple possible outputs)
        ├─→ CustodianLegalStatus (formal legal entity)
        ├─→ CustodianName (emic label)
        └─→ CustodianPlace (nominal place reference)
                ↓ refers_to_custodian
            Custodian (hub)
```

**Key Insight**: ReconstructionActivity MAY generate 0, 1, 2, or all 3 aspects depending on available evidence.

### 2. CustodianLegalStatus (formerly CustodianReconstruction)

**Purpose**: Represent the FORMAL LEGAL ENTITY with precise definition.

**Characteristics**:
- Precisely defined through legal registration
- Has formal legal form (ISO 20275 codes)
- Has registered legal name
- Has KvK/company registration number
- **Less ambiguous** than CustodianName

**Rename Rationale**:
- "Reconstruction" implies the entire process, not just legal status
- "LegalStatus" clarifies this is about FORMAL REGISTRATION
- Distinguishes from other aspects (name, place)

**Example**:
```yaml
CustodianLegalStatus:
  legal_name: "Stichting Rijksmuseum"
  legal_form: "http://purl.org/legal/LegalForm/Stichting"  # ISO 20275
  registration_number: "KvK 41215100"
  registration_date: "1995-01-01"
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804
```

### 3. CustodianName (refined definition)

**Purpose**: Represent the EMIC LABEL - how the custodian identifies itself publicly.

**Characteristics**:
- Ambiguous (context-dependent)
- May vary by audience/medium
- NOT the legal name
- Preferred public-facing label

**Example**:
```yaml
CustodianName:
  emic_name: "Rijksmuseum"
  name_language: "nl"
  endorsement_source: "Museum website, signage"
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804
```

### 4. CustodianPlace (NEW CLASS)

**Purpose**: Represent NOMINAL PLACE DESIGNATION - how the custodian is identified by place reference.

**CRITICAL**: This is NOT geographic coordinates! This is a **nominal reference** to a place as a way of identifying the custodian.

**Characteristics**:
- Nominal (name-based) place reference
- May be vague or contextual
- Historical place names
- Different levels of specificity

**Examples**:

```yaml
# Example 1: Building nickname as place reference
CustodianPlace:
  place_name: "het herenhuis in de Schilderswijk"
  place_specificity: NEIGHBORHOOD
  place_language: "nl"
  refers_to_custodian: hc:nl-zh-hag-m-xyz

# Example 2: Just "the mansion"
CustodianPlace:
  place_name: "the mansion"
  place_specificity: BUILDING
  place_language: "en"
  refers_to_custodian: hc:gb-lon-lon-m-abc

# Example 3: Museum as place designation
CustodianPlace:
  place_name: "Rijksmuseum"
  place_specificity: BUILDING
  place_language: "nl"
  place_note: "Used as place reference, not institution name"
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804
```

**Ontology Alignment**:
- `crm:E53_Place` - CIDOC-CRM place entity
- `schema:Place` - Schema.org place
- NOT `geo:Point` (that's for coordinates in separate Location class!)

**Distinction from Location Class**:

| CustodianPlace | Location |
|----------------|----------|
| Nominal reference | Geographic coordinates |
| "the mansion in the Schilderswijk" | lat: 52.0705, lon: 4.2894 |
| Emic/contextual | Precise/measured |
| May be ambiguous | Unambiguous |
| Identifies custodian | Locates custodian |

---

## Observation Linking - CRITICAL CHANGE

### Current (WRONG)

```yaml
CustodianObservation:
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804  # ❌ Direct link!
```

**Problem**: Observation by itself CANNOT guarantee successful identification of Custodian. Only the ReconstructionActivity can determine if identification succeeds.

### Corrected (RIGHT)

```yaml
CustodianObservation:
  # ❌ NO refers_to_custodian link!
  # Observation must go through ReconstructionActivity first
  
ReconstructionActivity:
  used: [obs-001, obs-002]
  # Activity attempts to generate outputs...
  
CustodianLegalStatus:
  was_generated_by: activity-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804  # ✅ Generated output links to hub
  
CustodianName:
  was_generated_by: activity-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804  # ✅ Generated output links to hub
  
CustodianPlace:
  was_generated_by: activity-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804  # ✅ Generated output links to hub
```

**Rationale**:
- Observation is RAW EVIDENCE (input)
- Only AFTER ReconstructionActivity can we know if custodian is identified
- Activity may fail → No custodian identification
- Activity may succeed → Generated aspects link to custodian

---

## ReconstructionActivity Outcomes

### Scenario 1: Full Success - All Three Aspects ✅✅✅

```yaml
# INPUT: Rich evidence
CustodianObservation:
  - id: obs-001
    observed_name: "Stichting Rijksmuseum"
    observation_source: "KvK registration"
  - id: obs-002
    observed_name: "Rijksmuseum"
    observation_source: "Museum website"
  - id: obs-003
    observed_name: "the museum on Museumplein"
    observation_source: "Archival letter, 1920"

# PROCESS: High-confidence reconstruction
ReconstructionActivity:
  id: act-001
  used: [obs-001, obs-002, obs-003]
  confidence_score: 0.95

# OUTPUT 1: Legal status
CustodianLegalStatus:
  legal_name: "Stichting Rijksmuseum"
  legal_form: "Stichting"
  was_derived_from: [obs-001]
  was_generated_by: act-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804

# OUTPUT 2: Emic name
CustodianName:
  emic_name: "Rijksmuseum"
  was_derived_from: [obs-002]
  was_generated_by: act-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804

# OUTPUT 3: Place designation
CustodianPlace:
  place_name: "het museum op het Museumplein"
  was_derived_from: [obs-003]
  was_generated_by: act-001
  refers_to_custodian: hc:nl-nh-ams-m-rm-q190804

# HUB: All three aspects identify the same custodian
Custodian:
  hc_id: hc:nl-nh-ams-m-rm-q190804
  preferred_label: <link to CustodianName>
  legal_status: <link to CustodianLegalStatus>
  place_designation: <link to CustodianPlace>
```

### Scenario 2: Partial Success - Name Only ✅

```yaml
# INPUT: Limited evidence
CustodianObservation:
  - id: obs-004
    observed_name: "Museum van de Twintigste Eeuw"
    observation_source: "Exhibition catalog"

# PROCESS: Low confidence
ReconstructionActivity:
  id: act-002
  used: [obs-004]
  confidence_score: 0.45

# OUTPUT: Only name (no legal status, no place)
CustodianName:
  emic_name: "Museum van de Twintigste Eeuw"
  was_derived_from: [obs-004]
  was_generated_by: act-002
  refers_to_custodian: hc:nl-ut-utr-m-mtwe

# HUB: Only name aspect available
Custodian:
  hc_id: hc:nl-ut-utr-m-mtwe
  preferred_label: <link to CustodianName>
  legal_status: null  # Unknown
  place_designation: null  # Unknown
```

### Scenario 3: Place-Only Success ✅

```yaml
# INPUT: Archival reference to place
CustodianObservation:
  - id: obs-005
    observed_name: "het herenhuis in de Schilderswijk"
    observation_source: "Notarial deed, 1850"

# PROCESS: Place-focused reconstruction
ReconstructionActivity:
  id: act-003
  used: [obs-005]
  confidence_score: 0.75

# OUTPUT: Only place designation
CustodianPlace:
  place_name: "het herenhuis in de Schilderswijk"
  place_language: "nl"
  place_specificity: NEIGHBORHOOD
  was_derived_from: [obs-005]
  was_generated_by: act-003
  refers_to_custodian: hc:nl-zh-hag-m-xyz

# HUB: Only place aspect available
Custodian:
  hc_id: hc:nl-zh-hag-m-xyz
  preferred_label: null
  legal_status: null
  place_designation: <link to CustodianPlace>
```

### Scenario 4: Complete Failure ❌

```yaml
# INPUT: Ambiguous observation
CustodianObservation:
  - id: obs-006
    observed_name: "Stedelijk Museum"
    observation_source: "Vague reference"

# PROCESS: Failed disambiguation
ReconstructionActivity:
  id: act-004
  used: [obs-006]
  confidence_score: 0.15
  justification: "Cannot determine which Stedelijk Museum - requires manual review"

# OUTPUT: Nothing (activity failed)
# - No CustodianLegalStatus
# - No CustodianName
# - No CustodianPlace
# - No Custodian identified
```

---

## Required Changes

### 1. Rename CustodianReconstruction → CustodianLegalStatus ✅

**Files to modify**:
- `modules/classes/CustodianReconstruction.yaml` → `modules/classes/CustodianLegalStatus.yaml`
- Update `class_uri` to reflect legal status focus
- Update documentation emphasizing formal legal entity

**New description**:
```yaml
CustodianLegalStatus:
  class_uri: org:FormalOrganization
  description: >-
    Formal legal entity representing a heritage custodian.
    
    CRITICAL: CustodianLegalStatus is ONE ASPECT of a custodian - the LEGAL dimension.
    
    Characteristics:
    - Precisely defined through legal registration
    - Has formal legal form (ISO 20275 codes)
    - Has registered legal name
    - Has KvK/company registration number
    - LESS AMBIGUOUS than CustodianName
    
    Example distinction:
    - CustodianLegalStatus: "Stichting Rijksmuseum" (legal entity)
    - CustodianName: "Rijksmuseum" (emic label)
    - CustodianPlace: "het museum op het Museumplein" (place reference)
    
    All three aspects refer to the SAME Custodian hub.
```

### 2. Create CustodianPlace Class ✅

**New file**: `modules/classes/CustodianPlace.yaml`

```yaml
id: https://nde.nl/ontology/hc/class/custodian-place
name: CustodianPlace
title: Custodian Place Class

imports:
  - linkml:types
  - Custodian
  - ReconstructionActivity
  - TimeSpan

classes:
  CustodianPlace:
    class_uri: crm:E53_Place
    description: >-
      Nominal place designation used to identify a heritage custodian.
      
      CRITICAL: This is NOT geographic coordinates! This is a NOMINAL REFERENCE
      to a place as a way of identifying the custodian.
      
      CustodianPlace represents how people refer to a custodian through place:
      - "het herenhuis in de Schilderswijk" (neighborhood reference)
      - "the mansion" (generic building reference)
      - "Rijksmuseum" (building name as place, not institution name)
      
      Distinction from Location class:
      - CustodianPlace: Nominal, contextual, may be ambiguous
      - Location: Geographic coordinates, precise, unambiguous
      
      Example:
      - CustodianPlace: "the mansion in the Schilderswijk, Den Haag"
      - Location: lat 52.0705, lon 4.2894, city "Den Haag"
      
      Ontology alignment:
      - crm:E53_Place (CIDOC-CRM place entity)
      - schema:Place (Schema.org place)
      
      Generated by ReconstructionActivity, refers to Custodian hub.
    
    exact_mappings:
      - crm:E53_Place
      - schema:Place
    
    close_mappings:
      - dcterms:Location
    
    slots:
      - place_name
      - place_language
      - place_specificity
      - place_note
      - was_derived_from
      - was_generated_by
      - refers_to_custodian
      - valid_from
      - valid_to
    
    slot_usage:
      place_name:
        slot_uri: crm:P87_is_identified_by
        description: "Nominal place designation"
        range: string
        required: true
      
      place_language:
        slot_uri: dcterms:language
        description: "Language of place name"
        range: string
        required: false
      
      place_specificity:
        description: "Level of place specificity"
        range: PlaceSpecificityEnum
        required: false
      
      place_note:
        slot_uri: skos:note
        description: "Contextual notes about place reference"
        range: string
        required: false
      
      was_derived_from:
        slot_uri: prov:wasDerivedFrom
        description: "CustodianObservation(s) from which this place designation was derived"
        range: CustodianObservation
        multivalued: true
        required: true
      
      was_generated_by:
        slot_uri: prov:wasGeneratedBy
        description: "ReconstructionActivity that generated this place designation"
        range: ReconstructionActivity
        required: false
      
      refers_to_custodian:
        slot_uri: dcterms:references
        description: "The Custodian hub that this place designation identifies"
        range: Custodian
        required: true
      
      valid_from:
        slot_uri: schema:validFrom
        description: "Start of validity period for this place designation"
        range: date
        required: false
      
      valid_to:
        slot_uri: schema:validThrough
        description: "End of validity period for this place designation"
        range: date
        required: false
```

**New enum**: PlaceSpecificityEnum

```yaml
# modules/enums/PlaceSpecificityEnum.yaml
id: https://nde.nl/ontology/hc/enum/place-specificity
name: PlaceSpecificityEnum
title: Place Specificity Enumeration

enums:
  PlaceSpecificityEnum:
    description: "Level of specificity for place designations"
    permissible_values:
      BUILDING:
        description: "Specific building reference"
        meaning: crm:E24_Physical_Human-Made_Thing
      STREET:
        description: "Street-level reference"
      NEIGHBORHOOD:
        description: "Neighborhood or district reference"
      CITY:
        description: "City-level reference"
      REGION:
        description: "Regional reference"
      VAGUE:
        description: "Vague or unspecified location"
```

### 3. Remove refers_to_custodian from CustodianObservation ✅

**File**: `modules/classes/CustodianObservation.yaml`

**Change**:
```yaml
# REMOVE this slot from CustodianObservation:
slots:
  - refers_to_custodian  # ❌ DELETE

slot_usage:
  refers_to_custodian:  # ❌ DELETE entire slot_usage
    ...
```

**Update description**:
```yaml
CustodianObservation:
  description: >-
    Source-based evidence of a heritage custodian's existence.
    
    CRITICAL: CustodianObservation does NOT directly link to Custodian!
    - Observations are RAW EVIDENCE (input to ReconstructionActivity)
    - Only ReconstructionActivity can determine if custodian is successfully identified
    - Generated outputs (LegalStatus/Name/Place) link to Custodian, not observations
    
    PROV-O Flow:
      CustodianObservation → prov:used → ReconstructionActivity
      ReconstructionActivity → prov:wasGeneratedBy → CustodianLegalStatus/Name/Place
      CustodianLegalStatus/Name/Place → refers_to_custodian → Custodian
```

### 4. Update Custodian Hub Links ✅

**File**: `modules/classes/Custodian.yaml`

**Add slots**:
```yaml
slots:
  - hc_id
  - preferred_label  # → CustodianName (already added)
  - legal_status  # NEW → CustodianLegalStatus
  - place_designation  # NEW → CustodianPlace
  - appellations
  - identifiers
  - created
  - modified

slot_usage:
  legal_status:
    slot_uri: org:hasRegisteredOrganization
    description: >-
      The formal legal entity representing this custodian.
      
      Links to CustodianLegalStatus with legal name, legal form, registration number.
      
      May be null if legal status not yet reconstructed.
    range: CustodianLegalStatus
    required: false
  
  place_designation:
    slot_uri: crm:P53_has_former_or_current_location
    description: >-
      Nominal place designation used to identify this custodian.
      
      Links to CustodianPlace with contextual place reference.
      
      Example: "het herenhuis in de Schilderswijk" (not coordinates!)
      
      May be null if place designation not yet reconstructed.
    range: CustodianPlace
    required: false
```

---

## Implementation Checklist

### Phase 1: Rename CustodianReconstruction
- [ ] Rename file: `CustodianReconstruction.yaml` → `CustodianLegalStatus.yaml`
- [ ] Update class name throughout file
- [ ] Update `class_uri` to `org:FormalOrganization`
- [ ] Update description emphasizing legal dimension
- [ ] Find and replace all references in other files

### Phase 2: Create CustodianPlace
- [ ] Create `modules/classes/CustodianPlace.yaml`
- [ ] Create `modules/enums/PlaceSpecificityEnum.yaml`
- [ ] Add imports to main schema

### Phase 3: Remove Observation→Custodian Link
- [ ] Remove `refers_to_custodian` slot from CustodianObservation
- [ ] Update CustodianObservation documentation
- [ ] Verify no other files reference this link

### Phase 4: Update Custodian Hub
- [ ] Add `legal_status` slot (→ CustodianLegalStatus)
- [ ] Add `place_designation` slot (→ CustodianPlace)
- [ ] Update hub documentation

### Phase 5: Update Examples
- [ ] Create multi-aspect success example (all 3 outputs)
- [ ] Create partial success examples (1-2 outputs)
- [ ] Create failure example (no outputs)
- [ ] Update UML diagrams

### Phase 6: Documentation
- [ ] Update PROV-O flow documentation
- [ ] Create multi-aspect modeling guide
- [ ] Update ontology alignment documentation
- [ ] Create CustodianPlace vs Location distinction guide

---

## Key Ontology Alignments

### CustodianLegalStatus
- `org:FormalOrganization` - W3C Organization Ontology
- `cpov:RegisteredOrganization` - CPOV
- `tooi:Overheidsorganisatie` - TOOI (Dutch)

### CustodianPlace
- `crm:E53_Place` - CIDOC-CRM place
- `schema:Place` - Schema.org place
- `dcterms:Location` - Dublin Core location

### CustodianName
- `skos:Concept` - SKOS concept
- `schema:name` - Schema.org name
- `foaf:name` - FOAF name

---

## References

- CIDOC-CRM E53 Place: http://www.cidoc-crm.org/html/cidoc_crm_v7.1.3.html#E53
- W3C Org Ontology: https://www.w3.org/TR/vocab-org/
- PROV-O: https://www.w3.org/TR/prov-o/

---

**Status**: 🔄 Ready for implementation  
**Priority**: HIGH - Fundamental multi-aspect modeling  
**Impact**: Renames class, adds new class, removes observation link, updates hub