glam/schemas/20251121

Heritage Custodian Ontology - Name Entity Module

Version: 0.1.0
Date: 2025-11-21
Status: Foundation Complete

---

🎯 Strategic Pivot: Top-Down Ontology Design

New Approach: Instead of enriching 2,453 Wikidata entities bottom-up (0.20% complete after 5 entries), we've pivoted to top-down ontology design starting with the most fundamental entity: Name (Nominal Reference).

Why This Approach?

1. Efficiency: Define abstract patterns once, apply to all 2,453 entities
2. Consistency: Single source of truth for ontological decisions
3. Traceability: Clear mapping from Wikidata hypernyms to formal ontology classes
4. Multi-format: Generate LinkML, RDF, TypeQL, UML from single design

---

📋 Core Design Decision: Name as Central Hub

The Problem

Initially, we considered splitting names into:

• Organization Name (for institutional identifiers)
• Place Name (for geographic identifiers)

This caused confusion: Is "Mansion House" a place name or an organization name? Both!

The Solution

Single Name Entity with multi-aspect references (via properties):

Name (Q1786933: "Mansion House")
  ├─ refers_to_place → Place (historic building in London)
  ├─ refers_to_organization → Organization (Lord Mayor's residence)
  ├─ refers_to_collection → Collection (Mansion House art collection)
  └─ hypernym → Concept (mansion, Q1802963)

Ontological Justification

1. Wikidata Q82799 Alignment

   • Q82799 defines "name" as a nominal reference (linguistic identifier)
   • Names are NOT the same as the entities they reference
   • "Mansion House" (name) ≠ Mansion House (building) ≠ Mansion House (organization)

2. SKOS Pattern

   • Names are skos:Concept - concepts in a knowledge organization system
   • SKOS provides hierarchical structure (skos:broader, skos:narrower)
   • Enables multilingual variants, alternative labels, temporal validity

3. CIDOC-CRM E41 Appellation

   • Cultural heritage domain standard for naming
   • E41_Appellation: "a sign by which someone or something is known"
   • Appellations are distinct from the entities they identify

4. Temporal Flexibility

   • Name changes don't require recreating Place, Organization, or Collection entities
   • Example: "Gemeentearchief Haarlem" (1910-2001) → "Noord-Hollands Archief" (2001-present)
   • Same organization, different names over time → Track via replaces property

5. Multi-Aspect Modeling

   • A single name can reference multiple aspects simultaneously
   • "Rijksmuseum" refers to:
     • Place: Museum building at Museumstraat 1, Amsterdam
     • Organization: Dutch national museum (Stichting Rijksmuseum)
     • Collection: 800,000+ art objects and historical artifacts
   • Each aspect has independent temporal lifecycle

---

📁 Module Structure

/schemas/20251121/linkml/01_name_entity.yaml

LinkML Schema (foundation for all other formats)

• Purpose: Machine-readable schema definition
• Features:
  • Class: Name (primary entity)
  • 20+ slots (properties)
  • SKOS alignment (skos:prefLabel, skos:broader, etc.)
  • Multi-aspect references (refers_to_place, refers_to_organization, refers_to_collection)
  • Temporal validity (valid_from, valid_to, replaces, replaced_by)
• Usage: Generate JSON Schema, SHACL, SQL DDL, Python dataclasses

/schemas/20251121/uml/mermaid/01_name_entity_hub.mmd

Mermaid Class Diagram (documentation, GitHub rendering)

• Purpose: Visual documentation for developers
• Features:
  • Class diagram with relationships
  • Forward references to Place, Organization, Collection
  • SKOS hierarchical relationships
  • Temporal name change tracking
• Rendering: GitHub automatically renders .mmd files

/schemas/20251121/uml/plantuml/01_name_entity_hub.puml

PlantUML Class Diagram (comprehensive UML)

• Purpose: Detailed UML modeling with rich annotations
• Features:
  • Full UML 2.5 class diagram syntax
  • Color-coded by ontology (SKOS=blue, CIDOC=orange, CPOV=purple)
  • Extensive notes explaining design rationale
  • Method signatures for future implementation
  • Cardinality constraints [0..1], [0..*], [1..1]
• Rendering: Use PlantUML server or CLI

/schemas/20251121/typeql/01_name_entity_hub.tql

TypeDB Schema (knowledge graph database)

• Purpose: Executable TypeDB schema for graph database
• Features:
  • Entity: name (PERA model)
  • Relations: broader-narrower, name-reference, name-succession
  • Attributes: 20+ properties
  • Reasoning Rules:
    • Transitive broader/narrower inference
    • Current name detection
    • Organization inference from place
• Usage: Load with typedb console --script 01_name_entity_hub.tql

/schemas/20251121/rdf/01_name_entity_hub.ttl

RDF/OWL Ontology (Semantic Web)

• Purpose: Web Ontology Language schema for Linked Data
• Features:
  • OWL Class: heritage:Name
  • OWL Properties: heritage:refersToPlace, etc.
  • SKOS integration (reuses SKOS properties)
  • SHACL constraints (cardinality, datatypes)
  • PROV-O integration (heritage:NameChange activity)
• Usage: Load into triple store (GraphDB, Virtuoso, Blazegraph)

---

🔗 Ontological Alignment Summary

Aspect	Primary Class	Secondary Classes	Namespace
Name (Hub)	skos:Concept	crm:E41_Appellation, wd:Q82799	SKOS, CIDOC-CRM, Wikidata
Place	crm:E27_Site	schema:Place, dbo:Place	CIDOC-CRM, Schema.org, DBpedia
Organization	cpov:PublicOrganisation	schema:Organization, crm:E39_Actor	CPOV, Schema.org, CIDOC-CRM
Collection	crm:E78_Curated_Holding	rico:RecordSet, bf:Collection	CIDOC-CRM, RiC-O, BIBFRAME
Hypernym	skos:Concept	-	SKOS
Name Change	prov:Activity	-	PROV-O

---

🛠️ Implementation Pattern

Multi-Aspect Modeling

LinkML Example:

- id: https://w3id.org/heritage/name/Q1786933
  prefLabel: Mansion House
  wikidata_id: Q1786933
  broader:
    - https://w3id.org/heritage/name/Q1802963  # mansion concept
  refers_to_place:
    - https://w3id.org/heritage/place/mansion-house-london
  refers_to_organization:
    - https://w3id.org/heritage/org/lord-mayor-residence
  refers_to_collection:
    - https://w3id.org/heritage/collection/mansion-house-art
  valid_from: "1753-11-01"

RDF/Turtle Example:

<https://w3id.org/heritage/name/Q1786933> a heritage:Name , skos:Concept ;
    heritage:wikidataId "Q1786933" ;
    skos:prefLabel "Mansion House"@en ;
    skos:altLabel "The Mansion House"@en ;
    skos:broader <https://w3id.org/heritage/name/Q1802963> ;
    heritage:refersToPlace <https://w3id.org/heritage/place/mansion-house-london> ;
    heritage:refersToOrganization <https://w3id.org/heritage/org/lord-mayor-residence> ;
    heritage:refersToCollection <https://w3id.org/heritage/collection/mansion-house-art> ;
    schema:validFrom "1753-11-01"^^xsd:date .

TypeQL Example:

$mansion-house isa name,
    has name-id "https://w3id.org/heritage/name/Q1786933",
    has wikidata-id "Q1786933",
    has pref-label "Mansion House",
    has valid-from 1753-11-01;

(referencing-name: $mansion-house, referenced-place: $place) isa name-reference;
(referencing-name: $mansion-house, referenced-organization: $org) isa name-reference;
(referencing-name: $mansion-house, referenced-collection: $coll) isa name-reference;
(specific-name: $mansion-house, hypernym-concept-role: $mansion-concept) isa hypernym-relationship;

---

📊 Mapping Wikidata Hypernyms to Name

Strategy

Instead of enriching individual Wikidata entities (Q1802963, Q3694, etc.), we now:

1. Extract unique hypernyms from hyponyms_curated.yaml

   • building (417 entries)
   • organisation (193 entries)
   • museum (133 entries)
   • archive (117 entries)
   • etc.

2. Create HypernymConcept entities for each hypernym

   - id: https://w3id.org/heritage/hypernym/building
     prefLabel: building
     wikidata_id: Q41176
     dbpedia_class: dbo:Building
   

3. Connect Names to Hypernyms via skos:broader

   - id: https://w3id.org/heritage/name/Q1802963
     prefLabel: mansion
     broader:
       - https://w3id.org/heritage/hypernym/building
   

4. Transitive reasoning (in TypeDB/OWL)

   • If "Mansion House" broader "mansion"
   • And "mansion" broader "building"
   • Then "Mansion House" broader "building" (inferred)

---

🔄 Temporal Name Chains

Example: Dutch Archive Merger

# Original name (1910-2001)
<https://w3id.org/heritage/name/gemeentearchief-haarlem> a heritage:Name ;
    skos:prefLabel "Gemeentearchief Haarlem"@nl ;
    schema:validFrom "1910-01-01"^^xsd:date ;
    schema:validUntil "2001-01-01"^^xsd:date ;
    heritage:replacedBy <https://w3id.org/heritage/name/noord-hollands-archief> .

# New name (2001-present)
<https://w3id.org/heritage/name/noord-hollands-archief> a heritage:Name ;
    skos:prefLabel "Noord-Hollands Archief"@nl ;
    schema:validFrom "2001-01-01"^^xsd:date ;
    heritage:replaces <https://w3id.org/heritage/name/gemeentearchief-haarlem> .

# Name Change Event
<https://w3id.org/heritage/event/nha-merger-2001> a heritage:NameChange , prov:Activity ;
    heritage:oldName <https://w3id.org/heritage/name/gemeentearchief-haarlem> ;
    heritage:newName <https://w3id.org/heritage/name/noord-hollands-archief> ;
    heritage:changeDate "2001-01-01"^^xsd:date ;
    heritage:changeType "MERGER" ;
    heritage:changeReason "Merger of Gemeentearchief Haarlem and Rijksarchief in Noord-Holland" .

# Organization persists (same entity, new name)
<https://w3id.org/heritage/org/nha> a heritage:Organization ;
    schema:name "Noord-Hollands Archief" ;  # Current name
    heritage:hasName <https://w3id.org/heritage/name/noord-hollands-archief> ;
    heritage:hadName <https://w3id.org/heritage/name/gemeentearchief-haarlem> ;
    schema:foundingDate "1910-01-01"^^xsd:date .

---

🎯 Next Steps

Immediate (Session 3)

1. Extract Unique Hypernyms from hyponyms_curated.yaml

   • Script: scripts/extract_hypernyms_taxonomy.py
   • Output: data/ontology/hypernym_taxonomy.yaml
   • Count unique hypernyms (building, organisation, museum, etc.)
   • Create HypernymConcept entities for each

2. Define Top-Level Hypernym Classes

   • Module: schemas/20251121/linkml/02_hypernym_taxonomy.yaml
   • Map hypernyms to ontology classes:
     • building → crm:E27_Site + dbo:Building
     • organisation → cpov:PublicOrganisation + schema:Organization
     • museum → schema:Museum + dbo:Museum + crm:E39_Actor
     • archive → rico:CorporateBody + dbo:Archive
     • etc.

3. Create Place Entity Module

   • Module: schemas/20251121/linkml/03_place_entity.yaml
   • Define Place class (spatial aspect)
   • Properties: geo, address, construction_date, etc.
   • Connect to Name via heritage:refersToPlace (inverse)

Medium-Term (This Week)

4. Create Organization Entity Module

   • Module: schemas/20251121/linkml/04_organization_entity.yaml
   • Define Organization class (custodian aspect)
   • Properties: founding_date, organization_type, parent_organization, etc.

5. Create Collection Entity Module

   • Module: schemas/20251121/linkml/05_collection_entity.yaml
   • Define Collection class (heritage materials aspect)
   • Properties: collection_type, item_count, accession_date, etc.

6. Generate Multi-Format Schemas

   • Use LinkML generators:
     • gen-json-schema → JSON Schema for validation
     • gen-shacl → SHACL shapes for RDF validation
     • gen-python → Python dataclasses for scripting
     • gen-owl → OWL ontology (alternative to manual TTL)
   • Update Mermaid, PlantUML, TypeQL for each module

Long-Term (Next Month)

7. Batch Convert Wikidata Entities to Name Instances

   • Script: scripts/convert_wikidata_to_names.py
   • Input: data/wikidata/GLAMORCUBEPSXHFN/hyponyms_curated_full.yaml
   • Output: data/instances/names/*.yaml (LinkML instances)
   • For each Wikidata entity:
     • Create Name entity with prefLabel from Wikidata label
     • Link to HypernymConcept via broader
     • Extract multilingual labels → altLabel
     • Add wikidata_id for provenance

8. Infer Place/Organization/Collection Aspects

   • Use hypernym patterns to infer multi-aspect references:
     • If hypernym = "building" → likely has Place aspect
     • If hypernym = "museum" → likely has Organization + Collection aspects
     • If hypernym = "archive" → likely has Organization + Collection aspects
   • Generate placeholder Place/Organization/Collection entities
   • Flag for manual enrichment

9. Load into TypeDB Knowledge Graph

   • Initialize TypeDB database
   • Load schema: 01_name_entity_hub.tql
   • Load instances: convert_yaml_to_typeql.py
   • Test reasoning rules (transitive broader, current name inference)

10. Create SPARQL Query Interface

    • Export to RDF triple store (GraphDB, Virtuoso)
    • Create SPARQL query templates:
      • "Find all museums in Amsterdam"
      • "Get name history for organization X"
      • "List collections by institution type"
    • Publish as Linked Open Data

---

📚 References

Standards & Vocabularies

• SKOS: W3C SKOS Reference
• CIDOC-CRM: CIDOC-CRM v7.1.3
• CPOV: Core Public Organisation Vocabulary
• Schema.org: schema.org
• PROV-O: W3C PROV-O
• LinkML: linkml.io
• TypeDB: typedb.com

Tools

• Mermaid: mermaid.js.org
• PlantUML: plantuml.com
• LinkML Generators: linkml.io/linkml/generators/index.html
• TypeDB Console: typedb.com/docs/console/overview

Project Files

• LinkML Schema: /schemas/20251121/linkml/01_name_entity.yaml
• Mermaid Diagram: /schemas/20251121/uml/mermaid/01_name_entity_hub.mmd
• PlantUML Diagram: /schemas/20251121/uml/plantuml/01_name_entity_hub.puml
• TypeQL Schema: /schemas/20251121/typeql/01_name_entity_hub.tql
• RDF/OWL Ontology: /schemas/20251121/rdf/01_name_entity_hub.ttl

---

Version: 0.1.0
Status: ✅ Foundation Complete - Ready for Hypernym Taxonomy Extraction
Next Session: Extract hypernyms and create top-level ontology classes