# Heritage Custodian Hub Architecture - Complete Structure

## Bidirectional Linking Diagram

```mermaid
graph TB
    Hub[Custodian Hub<br/>E39_Actor<br/>hc_id: https://nde.nl/ontology/hc/...]
    
    subgraph Appellations
        App1[CustodianAppellation<br/>E41_Appellation<br/>Name: Rijksmuseum<br/>Type: OFFICIAL]
        App2[CustodianAppellation<br/>E41_Appellation<br/>Name: Rijks<br/>Type: VERNACULAR]
        App3[CustodianAppellation<br/>E41_Appellation<br/>Name: The Rijksmuseum<br/>Type: TRANSLATION]
    end
    
    subgraph Identifiers
        Id1[CustodianIdentifier<br/>E42_Identifier<br/>ISIL: NL-AmRMA]
        Id2[CustodianIdentifier<br/>E42_Identifier<br/>Wikidata: Q190804]
        Id3[CustodianIdentifier<br/>E42_Identifier<br/>VIAF: 148691498]
    end
    
    Hub -->|crm:P1_is_identified_by| App1
    Hub -->|crm:P1_is_identified_by| App2
    Hub -->|crm:P1_is_identified_by| App3
    
    App1 -.->|crm:P1i_identifies| Hub
    App2 -.->|crm:P1i_identifies| Hub
    App3 -.->|crm:P1i_identifies| Hub
    
    Hub -->|crm:P48_has_preferred_identifier| Id1
    Hub -->|crm:P48_has_preferred_identifier| Id2
    Hub -->|crm:P48_has_preferred_identifier| Id3
    
    Id1 -.->|crm:P48i_is_preferred_identifier_of| Hub
    Id2 -.->|crm:P48i_is_preferred_identifier_of| Hub
    Id3 -.->|crm:P48i_is_preferred_identifier_of| Hub
    
    style Hub fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
    style App1 fill:#fff4e6,stroke:#ff9800,stroke-width:2px
    style App2 fill:#fff4e6,stroke:#ff9800,stroke-width:2px
    style App3 fill:#fff4e6,stroke:#ff9800,stroke-width:2px
    style Id1 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style Id2 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style Id3 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
```

## LinkML Schema Structure

```yaml
Custodian:
  class_uri: crm:E39_Actor
  abstract: true  # Hub - minimal entity
  slots:
    - hc_id                    # Persistent identifier
    - appellations             # crm:P1_is_identified_by (multivalued)
    - identifiers              # crm:P48_has_preferred_identifier (multivalued)
    - created                  # Database record metadata
    - modified

CustodianAppellation:
  class_uri: crm:E41_Appellation
  slots:
    - appellation_value        # The actual name string
    - appellation_language     # ISO 639-1 code
    - appellation_type         # OFFICIAL, VERNACULAR, HISTORICAL, TRANSLATION
    - identifies_custodian     # crm:P1i_identifies (inverse)

CustodianIdentifier:
  class_uri: crm:E42_Identifier
  slots:
    - identifier_scheme        # ISIL, Wikidata, VIAF, KvK, ROR
    - identifier_value         # The actual identifier string
    - identifies_custodian     # crm:P48i_is_preferred_identifier_of (inverse)
```

## Example Instance (Rijksmuseum)

```yaml
# Custodian hub
- hc_id: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
  
  # Forward properties (Hub → Appellations/Identifiers)
  appellations:
    - appellation_value: "Rijksmuseum"
      appellation_language: "nl"
      appellation_type: OFFICIAL
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
    
    - appellation_value: "Rijks"
      appellation_language: "nl"
      appellation_type: VERNACULAR
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
    
    - appellation_value: "The Rijksmuseum"
      appellation_language: "en"
      appellation_type: TRANSLATION
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
  
  identifiers:
    - identifier_scheme: "ISIL"
      identifier_value: "NL-AmRMA"
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
    
    - identifier_scheme: "Wikidata"
      identifier_value: "Q190804"
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
    
    - identifier_scheme: "VIAF"
      identifier_value: "148691498"
      identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
```

## RDF Serialization (Turtle)

```turtle
@prefix crm: <http://www.cidoc-crm.org/cidoc-crm/> .
@prefix hc: <https://nde.nl/ontology/hc/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

# Custodian hub
hc:nl-nh-ams-m-rm-q190804 a crm:E39_Actor ;
    crm:P1_is_identified_by hc:appellation/rijksmuseum-official ,
                             hc:appellation/rijks-vernacular ,
                             hc:appellation/rijksmuseum-en ;
    crm:P48_has_preferred_identifier hc:identifier/nl-amrma ,
                                      hc:identifier/q190804 ,
                                      hc:identifier/viaf148691498 .

# Appellations
hc:appellation/rijksmuseum-official a crm:E41_Appellation ;
    rdf:value "Rijksmuseum" ;
    crm:P1i_identifies hc:nl-nh-ams-m-rm-q190804 .

hc:appellation/rijks-vernacular a crm:E41_Appellation ;
    rdf:value "Rijks" ;
    crm:P1i_identifies hc:nl-nh-ams-m-rm-q190804 .

hc:appellation/rijksmuseum-en a crm:E41_Appellation ;
    rdf:value "The Rijksmuseum" ;
    crm:P1i_identifies hc:nl-nh-ams-m-rm-q190804 .

# Identifiers
hc:identifier/nl-amrma a crm:E42_Identifier ;
    skos:inScheme "ISIL" ;
    skos:notation "NL-AmRMA" ;
    crm:P48i_is_preferred_identifier_of hc:nl-nh-ams-m-rm-q190804 .

hc:identifier/q190804 a crm:E42_Identifier ;
    skos:inScheme "Wikidata" ;
    skos:notation "Q190804" ;
    crm:P48i_is_preferred_identifier_of hc:nl-nh-ams-m-rm-q190804 .

hc:identifier/viaf148691498 a crm:E42_Identifier ;
    skos:inScheme "VIAF" ;
    skos:notation "148691498" ;
    crm:P48i_is_preferred_identifier_of hc:nl-nh-ams-m-rm-q190804 .
```

## SPARQL Query Example

### Find all appellations for a custodian

```sparql
PREFIX crm: <http://www.cidoc-crm.org/cidoc-crm/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX hc: <https://nde.nl/ontology/hc/>

SELECT ?appellation ?value ?type
WHERE {
  hc:nl-nh-ams-m-rm-q190804 crm:P1_is_identified_by ?appellation .
  ?appellation rdf:value ?value .
  OPTIONAL { ?appellation crm:P2_has_type ?type }
}
```

### Find custodian by ISIL code

```sparql
PREFIX crm: <http://www.cidoc-crm.org/cidoc-crm/>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?custodian ?identifier
WHERE {
  ?identifier a crm:E42_Identifier ;
              skos:inScheme "ISIL" ;
              skos:notation "NL-AmRMA" ;
              crm:P48i_is_preferred_identifier_of ?custodian .
}
```

## Design Principles

### 1. Bidirectionality
Both forward and inverse properties are implemented for navigability in both directions:
- **Forward**: Custodian → Appellation/Identifier (user queries "what are the names/IDs?")
- **Inverse**: Appellation/Identifier → Custodian (system queries "which custodian does this name/ID identify?")

### 2. CIDOC-CRM Compliance
Uses standard cultural heritage ontology properties:
- **E41_Appellation**: Textual identifiers (names, labels, titles)
- **E42_Identifier**: Formal reference codes (ISIL, Wikidata, VIAF)
- **P1_is_identified_by / P1i_identifies**: Name-based identification
- **P48_has_preferred_identifier / P48i_is_preferred_identifier_of**: Formal identifier assignment

### 3. Multivalued Relationships
A custodian can have:
- **Multiple appellations**: Official names, vernacular names, historical names, translations
- **Multiple identifiers**: ISIL, Wikidata, VIAF, KvK, ROR, etc.

### 4. Optional Inverse
The `identifies_custodian` slot is **not required** because:
- Inverse can be computed from forward property
- Allows flexibility in data entry
- Inverse is primarily for system use (query optimization)

### 5. Type Safety
Each component is strongly typed:
- Appellations use `AppellationTypeEnum` (OFFICIAL, VERNACULAR, HISTORICAL, TRANSLATION)
- Identifiers use structured `identifier_scheme` + `identifier_value` pairs
- Language codes follow ISO 639-1

## Benefits

✅ **Semantic Web Ready**: Full RDF/OWL serialization with CIDOC-CRM alignment  
✅ **Bidirectional Navigation**: Query in both directions efficiently  
✅ **Cultural Heritage Standards**: Uses CIDOC-CRM as lingua franca  
✅ **Multilingual Support**: Language-tagged appellations  
✅ **External Linking**: Multiple identifier schemes for cross-dataset references  
✅ **Hub Pattern**: Keeps Custodian hub minimal and stable

## Files

**Schema**: `/schemas/20251121/linkml/01_custodian_name_modular.yaml`  
**Classes**: 
- `/schemas/20251121/linkml/modules/classes/Custodian.yaml`
- `/schemas/20251121/linkml/modules/classes/Appellation.yaml` (→ CustodianAppellation)
- `/schemas/20251121/linkml/modules/classes/Identifier.yaml` (→ CustodianIdentifier)

**Slots**:
- `/schemas/20251121/linkml/modules/slots/appellations.yaml` (forward)
- `/schemas/20251121/linkml/modules/slots/identifiers.yaml` (forward)
- `/schemas/20251121/linkml/modules/slots/identifies_custodian.yaml` (inverse)

**Documentation**:
- `APPELLATION_IDENTIFIER_REFACTORING_20251122.md` (detailed changelog)
- `QUICK_STATUS_APPELLATION_IDENTIFIER_COMPLETE.md` (quick summary)
- `HUB_ARCHITECTURE_DIAGRAM.md` (this file)

---

**Status**: ✅ Complete  
**Date**: 2025-11-22  
**Next**: Regenerate RDF, update UML diagrams, create example instances