kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/HUB_ARCHITECTURE_DIAGRAM.md

9 KiB
Raw Blame History

Heritage Custodian Hub Architecture - Complete Structure

Bidirectional Linking Diagram

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

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)

# 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)

@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

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

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