glam/FOUR_ASPECT_ARCHITECTURE_QUICK_REF.md

# Four-Aspect Custodian Architecture - Quick Reference

**Last Updated**: 2025-11-22  
**Schema Version**: 0.3.0  

---

## Overview

Heritage custodian institutions are modeled as **multi-aspect entities** with four independent reconstruction outputs:

```
                        Custodian (hub)
                             │
            ┌────────────────┼────────────────┐
            │                │                │
    ┌───────▼────────┐  ┌────▼─────┐  ┌──────▼──────┐
    │ CustodianName  │  │Custodian │  │ Custodian   │
    │ (emic label)   │  │LegalStatus│  │   Place     │
    │                │  │(legal     │  │(nominal loc)│
    │ SKOS Concept   │  │entity)    │  │             │
    └────────────────┘  │           │  │CRM E53_Place│
                        │W3C ORG,   │  └─────────────┘
                        │TOOI, CPOV │
                        └───────────┘
                             │
                    ┌────────▼─────────┐
                    │CustodianCollection│
                    │(heritage materials)│
                    │                   │
                    │CRM E78, RiC-O,    │
                    │BIBFRAME           │
                    └───────────────────┘
```

---

## The Four Aspects

### 1. CustodianName (Emic Label)

**Purpose**: How heritage communities refer to the institution  
**Ontology**: SKOS Concept  
**Key Property**: `skos:prefLabel`

**Characteristics**:
- ✅ Ambiguous, contextual, vernacular
- ✅ Language-specific (multilingual support)
- ✅ Includes alternative names (`skos:altLabel`)
- ✅ Changes over time (name supersession)
- ❌ NOT a legal name (that's in LegalStatus)

**Example**:
```yaml
preferred_label:
  emic_name: "Rijksmuseum"
  name_language: "nl"
  alternative_names:
    - "National Museum" (English)
    - "Rijks Museum" (variant spelling)
```

---

### 2. CustodianLegalStatus (Legal Entity)

**Purpose**: Formal organizational entity with legal registration  
**Ontology**: W3C ORG FormalOrganization, TOOI, CPOV  
**Key Property**: `org:hasRegisteredOrganization`

**Characteristics**:
- ✅ Precise, registered, formal
- ✅ Includes legal form (ISO 20275 codes)
- ✅ Registration numbers (KvK, company numbers)
- ✅ Legal name (distinct from emic name)
- ✅ Hierarchical (parent/subsidiary relationships)

**Example**:
```yaml
legal_status:
  legal_entity_type:
    code: "8100"  # ISO 20275: Central government
  legal_name:
    full_name: "Rijksmuseum Amsterdam"
  legal_form:
    elf_code: "NL-GOV"
    local_name: "Rijksoverheid agentschap"
```

---

### 3. CustodianPlace (Nominal Location)

**Purpose**: Where people say the institution "is"  
**Ontology**: CIDOC-CRM E53_Place  
**Key Property**: `crm:P53_has_former_or_current_location`

**Characteristics**:
- ✅ Nominal reference (NOT coordinates)
- ✅ Can be vague ("Amsterdam", not lat/lon)
- ✅ Linguistic/cultural (e.g., "Milano" vs "Milan")
- ✅ Changes over time (relocations)
- ❌ NOT a postal address (that's in LegalStatus)

**Example**:
```yaml
place_designation:
  place_name: "Amsterdam"
  place_specificity: CITY
  place_note: "Museumstraat 1, 1071 XX"
```

---

### 4. CustodianCollection (Heritage Materials) ← NEW!

**Purpose**: Heritage materials managed by custodian (metonymic reference)  
**Ontology**: CIDOC-CRM E78_Curated_Holding, RiC-O RecordSet, BIBFRAME Collection  
**Key Property**: `crm:P46_is_composed_of`

**Characteristics**:
- ✅ Represents the "substance" of heritage work
- ✅ Multiple collection types (archival, museum, library)
- ✅ Independent lifecycle (materials span different time than custodian)
- ✅ Custody transfers (collections can move between custodians)
- ✅ Metonymic discourse ("The Rijksmuseum has a Rembrandt" = collection)

**Example**:
```yaml
has_collection:
  - collection_name: "Rijksmuseum Collection"
    collection_type:
      - "museum_objects"
      - "library_holdings"
    temporal_coverage: "1100-2000"  # Materials span 9 centuries
    extent: "1 million objects"
```

---

## Why Four Aspects?

### Independent Lifecycles

Each aspect can change **independently** without affecting others:

| Event | Name | LegalStatus | Place | Collection |
|-------|------|-------------|-------|------------|
| Name change | ✓ Changes | Unchanged | Unchanged | Unchanged |
| Legal reorganization | Unchanged | ✓ Changes | Unchanged | Unchanged |
| Relocation | Unchanged | Unchanged | ✓ Changes | Unchanged |
| Custody transfer | Unchanged | Unchanged | Unchanged | ✓ Changes |
| Merger | ✓ May change | ✓ Changes | ✓ May change | ✓ Collections merge |

**Example**: Noord-Hollands Archief
- **2001 merger**: Name changes, LegalStatus changes, Place changes (new building), Collections merge
- **Tracking**: Each aspect has `valid_from`/`valid_to` dates to model temporal changes

---

## Metonymic Discourse and Collection Aspect

### What is Metonymy?

Using one entity (custodian) to refer to a related entity (collection).

**Common Heritage Discourse**:
- "The Rijksmuseum has a Rembrandt" → The **collection** contains it
- "The British Library digitized manuscripts" → The **collection** was digitized
- "The National Archives preserves colonial records" → The **collection** preserves them

### Why Collections Need Separate Modeling

Before CustodianCollection, there was **no way to model**:

1. **Collection identity** - Collections have names distinct from custodians
   - Custodian: "Rijksmuseum"
   - Collection: "Rijksmuseum Collection" (general) + "Cuypers Library" (specific)

2. **Multiple collections** - One custodian can manage multiple collections
   - Rijksmuseum: Main museum collection + Cuypers Library + Asian Pavilion
   - British Library: General collection + Manuscripts + Sound Archive

3. **Custody transfers** - Collections move between custodians
   - Mondrian paintings moved from Museum Gemeente to Rijksmuseum
   - Colonial archives transferred from colonial offices to national archives

4. **Joint custody** - Multiple custodians can share management
   - Shared collections between state and municipal archives
   - Collaborative digital repositories

5. **Collection-level provenance** - Acquisition history distinct from custodian history
   - Custodian founded 1800
   - Collection materials span 1100-2000 (predates custodian by 700 years!)

---

## Slot Mapping Summary

### CustodianName Slots (11)
- `emic_name`, `name_language`, `standardized_name`
- `endorsement_source`, `name_authority`
- `alternative_names` (→ CustodianAppellation)
- `valid_from`, `valid_to`
- `supersedes`, `superseded_by`
- `refers_to_custodian`

### CustodianLegalStatus Slots (15+)
- `legal_entity_type`, `legal_name`, `legal_form`, `legal_status`
- `registration_authority`, `registration_numbers`
- `governance_structure`, `parent_custodian`
- `identifiers` (ISIL, KvK, etc.)
- `dissolution_date`, `reconstruction_method`
- `temporal_extent`, `refers_to_custodian`

### CustodianPlace Slots (7)
- `place_name`, `place_language`
- `place_specificity` (CITY, REGION, COUNTRY, etc.)
- `place_note`
- `valid_from`, `valid_to`
- `refers_to_custodian`

### CustodianCollection Slots (11) ← NEW!
- `collection_name`, `collection_description`
- `collection_type` (archival_records, museum_objects, etc.)
- `collection_scope`, `temporal_coverage`
- `extent`, `arrangement_system`, `provenance_note`
- `valid_from`, `valid_to`
- `refers_to_custodian`

---

## Collection Types Supported

| Type | Ontology | Use Case |
|------|----------|----------|
| **archival_records** | `rico:RecordSet` | Government records, family papers, organizational archives |
| **museum_objects** | `crm:E78_Curated_Holding` | Paintings, sculptures, artifacts, decorative arts |
| **library_holdings** | `bf:Collection` | Books, serials, manuscripts, rare books |
| **monuments** | `crm:E27_Site` | Built heritage, archaeological sites |
| **archaeological_materials** | `crm:E78_Curated_Holding` | Excavation finds, assemblages |
| **natural_history_specimens** | `crm:E78_Curated_Holding` | Biological specimens, geological samples |
| **digital_born** | `schema:Collection` | Born-digital archives, web archives |
| **photographs** | `crm:E78_Curated_Holding` | Photographic collections |
| **manuscripts** | `bf:Collection` | Handwritten documents, medieval codices |

**Note**: Collections can have **multiple types** (e.g., mixed archival + museum).

---

## Example: Complete Four-Aspect Record

```yaml
Custodian:
  hc_id: https://nde.nl/ontology/hc/cust/rijksmuseum
  
  # Aspect 1: Name
  preferred_label:
    emic_name: "Rijksmuseum"
    name_language: "nl"
  
  # Aspect 2: Legal Status
  legal_status:
    legal_entity_type:
      code: "8100"  # Central government
    legal_name:
      full_name: "Rijksmuseum Amsterdam"
  
  # Aspect 3: Place
  place_designation:
    place_name: "Amsterdam"
    place_specificity: CITY
  
  # Aspect 4: Collection (NEW!)
  has_collection:
    - collection_name: "Rijksmuseum Collection"
      collection_type:
        - "museum_objects"
        - "library_holdings"
      temporal_coverage: "1100-2000"
      extent: "1 million objects"
```

---

## Ontology Alignment at a Glance

| Aspect | Primary Ontology | Class URI |
|--------|------------------|-----------|
| **Name** | SKOS | `skos:Concept` |
| **LegalStatus** | W3C ORG | `org:FormalOrganization` |
| **Place** | CIDOC-CRM | `crm:E53_Place` |
| **Collection** | CIDOC-CRM | `crm:E78_Curated_Holding` |
|  | RiC-O | `rico:RecordSet` |
|  | BIBFRAME | `bf:Collection` |

---

## PiCo Observation/Reconstruction Pattern

All four aspects follow the **PiCo-inspired pattern**:

```
CustodianObservation (source data)
         ↓ prov:wasDerivedFrom
ReconstructionActivity (scholarly interpretation)
         ↓ prov:generated
CustodianName | CustodianLegalStatus | CustodianPlace | CustodianCollection
         ↓ prov:qualifiedAttribution
Custodian (hub - immutable URI)
```

**Key Insight**: The four aspects are **reconstructed interpretations** of source observations, not raw data.

---

## Implementation Checklist

When creating heritage custodian records, ensure:

- [ ] **Custodian hub** - Create unique `hc_id` URI
- [ ] **CustodianName** - Extract emic label with language
- [ ] **CustodianLegalStatus** - Document legal form and registration
- [ ] **CustodianPlace** - Record nominal location reference
- [ ] **CustodianCollection** - Model heritage materials ← NEW!
- [ ] **CustodianObservation** - Link each aspect to source observations
- [ ] **ReconstructionActivity** - Document scholarly method
- [ ] **Temporal validity** - Add `valid_from`/`valid_to` for all aspects
- [ ] **Identifiers** - Include ISIL, Wikidata, VIAF, URLs

---

## References

- **Schema**: `schemas/20251121/linkml/01_custodian_name_modular.yaml`
- **Collection Class**: `schemas/20251121/linkml/modules/classes/CustodianCollection.yaml`
- **Example**: `schemas/20251121/examples/rijksmuseum_with_collection.yaml`
- **Full Documentation**: `CUSTODIAN_COLLECTION_ADDITION_20251122.md`

---

## Key Takeaways

✅ **Four aspects** = Four independent lifecycles  
✅ **CustodianCollection** = Metonymic discourse modeling  
✅ **Multiple collection types** = Archival, museum, library support  
✅ **Custody transfers** = Collections can move between custodians  
✅ **Temporal validity** = Each aspect tracks its own `valid_from`/`valid_to`  
✅ **Ontology-aligned** = Maps to CIDOC-CRM, RiC-O, BIBFRAME, SKOS, W3C ORG

---

**Quick Reference Version**: 1.0  
**Generated**: 2025-11-22T18:30:00Z