Add class metadata slots to replace annotations with ontology-aligned predicates

- Add class_metadata_slots.yaml with slots for: - GLAMORCUBESFIXPHDNT custodian type classification (hc:custodianTypes) - Wikidata alignment (wdt:P31, skos:mappingRelation) - SKOS hierarchical relationships (skos:broader, skos:narrower) - Dual-class pattern linking (rdfs:seeAlso) - Specificity scoring for RAG (prov:generatedAtTime, prov:wasAttributedTo) - Collection holdings (rico:isOrWasHolderOf) - Add AcademicArchive_refactored.yaml demonstrating slot-based approach - Add migration guide documenting annotation-to-slot mappings Ontology sources: SKOS, PROV-O, Dublin Core, RiC-O, Wikidata
2026-01-06 11:16:49 +01:00 · 2026-01-06 11:16:49 +01:00 · bc562bd68d
commit bc562bd68d
parent 11983014bb
3 changed files with 1060 additions and 0 deletions
--- a/schemas/20251121/linkml/modules/classes/AcademicArchive_refactored.yaml
+++ b/schemas/20251121/linkml/modules/classes/AcademicArchive_refactored.yaml
@ -0,0 +1,303 @@
+# AcademicArchive Type - Refactored with Slots
+# 
+# This version replaces annotations with proper slots that map to
+# standard ontology predicates (SKOS, PROV-O, Dublin Core, RiC-O).
+#
+# Generation date: 2026-01-06
+# Replaces: Original AcademicArchive.yaml with extensive annotations
+
+id: https://nde.nl/ontology/hc/class/AcademicArchive
+name: AcademicArchive
+title: Academic Archive Type
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hc: https://nde.nl/ontology/hc/
+  schema: http://schema.org/
+  skos: http://www.w3.org/2004/02/skos/core#
+  rico: https://www.ica.org/standards/RiC/ontology#
+  wd: http://www.wikidata.org/entity/
+
+imports:
+  - linkml:types
+  - ./ArchiveOrganizationType
+  - ./CollectionType
+  - ./AcademicArchiveRecordSetTypes
+  - ../slots/class_metadata_slots
+  - ../slots/type_scope
+  - ../slots/holds_record_set_types
+
+default_prefix: hc
+
+classes:
+  AcademicArchive:
+    is_a: ArchiveOrganizationType
+    class_uri: schema:ArchiveOrganization
+    description: |
+      Archive of a higher education institution (university, college, polytechnic).
+      
+      **Dual-Class Pattern**:
+      This class represents the CUSTODIAN type (the archive organization).
+      For the collection type, see `AcademicArchiveRecordSetType` which maps to `rico:RecordSetType`.
+      
+      **Holdings** (linked via rico:isOrWasHolderOf):
+      Academic archives typically hold records classified under these RecordSetTypes:
+      - UniversityAdministrativeFonds - Governance, committee, policy records
+      - StudentRecordSeries - Enrollment, transcripts, graduation records
+      - FacultyPaperCollection - Personal papers of faculty members
+      - CampusDocumentationCollection - Photos, publications, ephemera
+    
+    # =========================================================================
+    # SLOTS - Replacing annotations with proper ontology-aligned slots
+    # =========================================================================
+    slots:
+      # Collection relationship (rico:isOrWasHolderOf)
+      - holds_record_set_types
+      
+      # GLAMORCUBESFIXPHDNT type classification
+      - custodian_types
+      - custodian_types_rationale
+      
+      # Wikidata alignment (replaces wikidata, wikidata_label annotations)
+      - wikidata_alignment
+      
+      # SKOS hierarchical relationships (replaces skos_broader annotation)
+      - skos_broader
+      - skos_broader_label
+      
+      # Dual-class pattern (replaces linked_collection_type, dual_class_pattern)
+      - dual_class_link
+      
+      # Specificity scoring for RAG (replaces specificity_* annotations)
+      - specificity_annotation
+      - template_specificity
+    
+    # Multilingual labels using LinkML's structured_aliases
+    structured_aliases:
+      - literal_form: Hochschularchiv
+        in_language: de
+      - literal_form: archivo académico
+        in_language: es
+      - literal_form: archives académiques
+        in_language: fr
+      - literal_form: archivio accademico
+        in_language: it
+      - literal_form: academisch archief
+        in_language: nl
+      - literal_form: arquivo acadêmico
+        in_language: pt
+    
+    # Subject keywords for discovery
+    keywords:
+      - administrative records
+      - governance records
+      - committee records
+      - policy records
+      - student records
+      - enrollment records
+      - graduation records
+      - academic transcripts
+      - faculty papers
+      - research documentation
+      - university publications
+      - ephemera
+      - campus photographs
+      - audiovisual materials
+      - campus life documentation
+    
+    # Slot usage with default values
+    slot_usage:
+      # Holdings relationship
+      holds_record_set_types:
+        description: |
+          Links this custodian type to the record set types it typically holds.
+          Uses RiC-O property rico:isOrWasHolderOf to express custodial relationship.
+          
+          **Academic Archive Holdings**:
+          - UniversityAdministrativeFonds - Governance, committee, policy records
+          - StudentRecordSeries - Enrollment, transcripts, graduation records
+          - FacultyPaperCollection - Personal papers of faculty members
+          - CampusDocumentationCollection - Photos, publications, ephemera
+        equals_expression: |
+          ["hc:UniversityAdministrativeFonds", "hc:StudentRecordSeries", "hc:FacultyPaperCollection", "hc:CampusDocumentationCollection"]
+      
+      # Custodian type classification
+      custodian_types:
+        equals_expression: '["A"]'
+      
+      custodian_types_rationale:
+        equals_string: "AcademicArchive is an archival institution - maps to ARCHIVE (A)"
+      
+      # Wikidata alignment
+      wikidata_alignment:
+        range: WikidataAlignment
+        inlined: true
+      
+      # SKOS broader concept
+      skos_broader:
+        equals_expression: '["wd:Q166118"]'
+      
+      skos_broader_label:
+        equals_string: "archive"
+      
+      # Dual-class pattern
+      dual_class_link:
+        range: DualClassLink
+        inlined: true
+      
+      # Specificity scores
+      specificity_annotation:
+        range: SpecificityAnnotation
+        inlined: true
+      
+      template_specificity:
+        range: TemplateSpecificityScores
+        inlined: true
+    
+    # =========================================================================
+    # ONTOLOGICAL MAPPINGS - Using LinkML built-in mapping predicates
+    # These map directly to SKOS predicates:
+    # - exact_mappings → skos:exactMatch
+    # - close_mappings → skos:closeMatch
+    # - broad_mappings → skos:broadMatch
+    # - narrow_mappings → skos:narrowMatch
+    # - related_mappings → skos:relatedMatch
+    # =========================================================================
+    
+    exact_mappings:
+      - wd:Q27032435  # Wikidata: academic archive (exact match)
+    
+    close_mappings:
+      - rico:CorporateBody  # RiC-O: archive as organizational agent
+      - skos:Concept  # SKOS: this is a concept in a classification scheme
+    
+    broad_mappings:
+      - wd:Q166118  # Wikidata: archive (broader parent concept)
+      - wd:Q124762372  # InstitutionalArchive - broader institutional scope
+    
+    narrow_mappings:
+      - wd:Q2496264  # UniversityArchive - more specific to universities
+    
+    related_mappings:
+      - wd:Q1065413  # InstitutionalRepository - digital publications focus (different function)
+    
+    # Editorial notes and cross-references
+    comments:
+      - "Custodian type class for academic/higher education archives"
+      - "Part of dual-class pattern: custodian type + rico:RecordSetType"
+      - "Parent institution is typically a university or college"
+      - "class_uri is schema:ArchiveOrganization - primary semantic meaning"
+      - "skos:broader relationship to wd:Q166118 (archive) expressed via skos_broader slot"
+    
+    see_also:
+      - wd:Q2496264  # UniversityArchive
+      - wd:Q124762372  # InstitutionalArchive
+      - wd:Q1065413  # InstitutionalRepository
+      - AcademicArchiveRecordSetType  # Linked collection type class
+
+  # ===========================================================================
+  # AcademicArchiveRecordSetType - Collection type (rico:RecordSetType)
+  # ===========================================================================
+  
+  AcademicArchiveRecordSetType:
+    is_a: CollectionType
+    class_uri: rico:RecordSetType
+    description: |
+      A rico:RecordSetType for classifying collections of academic and higher 
+      education institutional records within heritage institutions.
+      
+      **Dual-Class Pattern**:
+      This class represents the COLLECTION type (rico:RecordSetType).
+      For the custodian organization type, see `AcademicArchive`.
+      
+      **Scope**:
+      Used to classify record sets that contain academic institutional materials:
+      - University administrative fonds
+      - Student record series
+      - Faculty paper collections
+      - Campus documentation collections
+    
+    slots:
+      - type_scope
+      - custodian_types
+      - custodian_types_rationale
+      - wikidata_alignment
+      - dual_class_link
+      - specificity_annotation
+      - template_specificity
+    
+    # Multilingual labels for the collection type
+    structured_aliases:
+      - literal_form: Hochschularchivbestand
+        in_language: de
+      - literal_form: fondo de archivo académico
+        in_language: es
+      - literal_form: fonds d'archives académiques
+        in_language: fr
+      - literal_form: academisch archiefbestand
+        in_language: nl
+    
+    slot_usage:
+      type_scope:
+        range: TypeScopeEntry
+        multivalued: true
+        inlined_as_list: true
+        description: |
+          Structured scope definitions for AcademicArchiveRecordSetType.
+          Formally documents what types of record sets are classified under this type.
+      
+      custodian_types:
+        equals_expression: '["A"]'
+      
+      custodian_types_rationale:
+        equals_string: "AcademicArchiveRecordSetType classifies collections held by ARCHIVE (A) type custodians"
+      
+      wikidata_alignment:
+        range: WikidataAlignment
+        inlined: true
+      
+      dual_class_link:
+        range: DualClassLink
+        inlined: true
+      
+      specificity_annotation:
+        range: SpecificityAnnotation
+        inlined: true
+      
+      template_specificity:
+        range: TemplateSpecificityScores
+        inlined: true
+    
+    # Scope subclasses are defined in AcademicArchiveRecordSetTypes.yaml
+    comments:
+      - |
+        **Subclasses (concrete RecordSetTypes)**:
+        
+        This abstract type has four concrete subclasses defined in 
+        AcademicArchiveRecordSetTypes.yaml:
+        
+        1. UniversityAdministrativeFonds - Governance, committee, policy records
+        2. StudentRecordSeries - Enrollment, transcripts, graduation records
+        3. FacultyPaperCollection - Personal papers of faculty members
+        4. CampusDocumentationCollection - Photos, publications, ephemera
+        
+        Each subclass maps to rico:RecordSetType with appropriate broad_mappings 
+        to RiC-O organizational concepts (rico:Fonds, rico:Series, rico:Collection).
+    
+    # Mappings for collection type
+    exact_mappings:
+      - rico:RecordSetType  # Primary meaning - this IS a RecordSetType
+    
+    broad_mappings:
+      - wd:Q27032435  # Wikidata: academic archive (ontonym - broader concept)
+    
+    close_mappings:
+      - skos:Concept  # This is a concept in classification scheme
+    
+    see_also:
+      - AcademicArchive  # Linked custodian type
+      - rico:RecordSetType  # RiC-O standard
+      - UniversityAdministrativeFonds  # Subclass
+      - StudentRecordSeries  # Subclass
+      - FacultyPaperCollection  # Subclass
+      - CampusDocumentationCollection  # Subclass
--- a/schemas/20251121/linkml/modules/slots/ANNOTATION_TO_SLOT_MIGRATION.md
+++ b/schemas/20251121/linkml/modules/slots/ANNOTATION_TO_SLOT_MIGRATION.md
@ -0,0 +1,138 @@
+# Annotation-to-Slot Migration Guide
+
+This document maps the annotations previously used on classes to proper slots with ontology-aligned predicates.
+
+## Summary: Annotations → Slots
+
+| Annotation | New Slot | Slot URI | Ontology Source |
+|------------|----------|----------|-----------------|
+| `custodian_types` | `custodian_types` | `hc:custodianTypes` | Custom (GLAMORCUBESFIXPHDNT) |
+| `custodian_types_rationale` | `custodian_types_rationale` | `hc:custodianTypesRationale` | Custom |
+| `custodian_types_primary` | `custodian_types_primary` | `hc:custodianTypesPrimary` | Custom |
+| `wikidata` | `wikidata_entity_id` | `wdt:P31` | Wikidata |
+| `wikidata_label` | `wikidata_entity_label` | `rdfs:label` | RDFS |
+| `wikidata_mapping_type` | `wikidata_mapping_type` | `skos:mappingRelation` | SKOS |
+| `wikidata_mapping_note` | `wikidata_mapping_rationale` | `skos:note` | SKOS |
+| `skos_broader` | `skos_broader` | `skos:broader` | SKOS |
+| `skos_broader_label` | `skos_broader_label` | `rdfs:label` | RDFS |
+| `linked_collection_type` | `linked_class_name` | `rdfs:seeAlso` | RDFS |
+| `linked_custodian_type` | `linked_class_name` | `rdfs:seeAlso` | RDFS |
+| `dual_class_pattern` | `dual_class_role` | `hc:dualClassRole` | Custom |
+| `dual_class_pattern_note` | `link_rationale` | `skos:editorialNote` | SKOS |
+| `specificity_score` | `specificity_score` | `hc:specificityScore` | Custom |
+| `specificity_rationale` | `specificity_rationale` | `skos:note` | SKOS |
+| `specificity_annotation_timestamp` | `specificity_timestamp` | `prov:generatedAtTime` | PROV-O |
+| `specificity_annotation_agent` | `specificity_agent` | `prov:wasAttributedTo` | PROV-O |
+| `template_specificity` | `template_specificity` | `hc:templateSpecificity` | Custom |
+
+## Structured Objects
+
+Instead of flat annotations, we now use structured classes:
+
+### WikidataAlignment
+
+```yaml
+wikidata_alignment:
+  wikidata_entity_id: Q27032435
+  wikidata_entity_label: "academic archive"
+  wikidata_mapping_type: exact
+  wikidata_mapping_rationale: "Exact semantic match"
+```
+
+**Replaces annotations:**
+- `wikidata: Q27032435`
+- `wikidata_label: academic archive`
+- `wikidata_mapping_type: ontonym`
+- `wikidata_mapping_note: ...`
+
+### DualClassLink
+
+```yaml
+dual_class_link:
+  dual_class_role: custodian_type
+  linked_class_name: AcademicArchiveRecordSetType
+  link_rationale: "This class represents the CUSTODIAN type..."
+```
+
+**Replaces annotations:**
+- `linked_collection_type: AcademicArchiveRecordSetType`
+- `dual_class_pattern: custodian_type`
+- `dual_class_pattern_note: ...`
+
+### SpecificityAnnotation
+
+```yaml
+specificity_annotation:
+  specificity_score: 0.5
+  specificity_rationale: "Archive-related class."
+  specificity_timestamp: "2026-01-05T10:51:51Z"
+  specificity_agent: opencode-claude-sonnet-4
+```
+
+**Replaces annotations:**
+- `specificity_score: 0.5`
+- `specificity_rationale: ...`
+- `specificity_annotation_timestamp: ...`
+- `specificity_annotation_agent: ...`
+
+### TemplateSpecificityScores
+
+```yaml
+template_specificity:
+  archive_search_score: 0.25
+  museum_search_score: 0.55
+  library_search_score: 0.55
+  collection_discovery_score: 0.35
+  person_research_score: 0.55
+  location_browse_score: 0.55
+  identifier_lookup_score: 0.55
+  organizational_change_score: 0.55
+  digital_platform_score: 0.55
+  general_heritage_score: 0.55
+```
+
+**Replaces annotation:**
+- `template_specificity: { archive_search: 0.25, ... }`
+
+## Ontology Predicates Used
+
+| Prefix | Namespace | Used For |
+|--------|-----------|----------|
+| `skos:` | `http://www.w3.org/2004/02/skos/core#` | Concept relationships, notes |
+| `prov:` | `http://www.w3.org/ns/prov#` | Provenance (timestamps, agents) |
+| `rdfs:` | `http://www.w3.org/2000/01/rdf-schema#` | Labels |
+| `rico:` | `https://www.ica.org/standards/RiC/ontology#` | Archival relationships |
+| `wdt:` | `http://www.wikidata.org/prop/direct/` | Wikidata properties |
+| `hc:` | `https://nde.nl/ontology/hc/` | Custom heritage custodian properties |
+
+## SKOS Predicates Detail
+
+| Predicate | Usage |
+|-----------|-------|
+| `skos:broader` | Hierarchical parent concept |
+| `skos:narrower` | Hierarchical child concepts |
+| `skos:related` | Associative relationships |
+| `skos:exactMatch` | Exact semantic match (LinkML `exact_mappings`) |
+| `skos:closeMatch` | Close semantic match (LinkML `close_mappings`) |
+| `skos:broadMatch` | Broader match in different scheme (LinkML `broad_mappings`) |
+| `skos:narrowMatch` | Narrower match in different scheme (LinkML `narrow_mappings`) |
+| `skos:relatedMatch` | Related match in different scheme (LinkML `related_mappings`) |
+| `skos:note` | General notes |
+| `skos:editorialNote` | Editorial/rationale notes |
+| `skos:scopeNote` | Scope definitions |
+
+## PROV-O Predicates Detail
+
+| Predicate | Usage |
+|-----------|-------|
+| `prov:generatedAtTime` | Timestamp when annotation was created |
+| `prov:wasAttributedTo` | Agent that created the annotation |
+
+## Benefits of Slot-Based Approach
+
+1. **Semantic Interoperability**: Slot URIs map to standard ontology predicates
+2. **Validation**: LinkML validates slot values (types, patterns, ranges)
+3. **Structured Data**: Complex annotations become typed objects
+4. **Discoverability**: Slots are documented in schema, annotations are opaque
+5. **Code Generation**: Slots generate proper class attributes in Python/TypeScript
+6. **RDF Export**: Slots produce valid RDF triples with correct predicates
--- a/schemas/20251121/linkml/modules/slots/class_metadata_slots.yaml
+++ b/schemas/20251121/linkml/modules/slots/class_metadata_slots.yaml
@ -0,0 +1,619 @@
+# Class Metadata Slots
+# Slots for expressing class-level metadata that was previously in annotations
+#
+# These slots replace annotations with proper ontology-aligned predicates:
+# - SKOS for concept relationships (broader, narrower, related)
+# - Wikidata for entity linking
+# - PROV-O for provenance and attribution
+# - Dublin Core for descriptive metadata
+# - Custom HC slots for domain-specific metadata
+#
+# Generation date: 2026-01-06
+
+id: https://nde.nl/ontology/hc/slots/class_metadata
+name: class_metadata_slots
+title: Class Metadata Slots
+
+prefixes:
+  linkml: https://w3id.org/linkml/
+  hc: https://nde.nl/ontology/hc/
+  skos: http://www.w3.org/2004/02/skos/core#
+  wd: http://www.wikidata.org/entity/
+  wdt: http://www.wikidata.org/prop/direct/
+  dcterms: http://purl.org/dc/terms/
+  prov: http://www.w3.org/ns/prov#
+  pav: http://purl.org/pav/
+  rico: https://www.ica.org/standards/RiC/ontology#
+  owl: http://www.w3.org/2002/07/owl#
+  rdfs: http://www.w3.org/2000/01/rdf-schema#
+  schema: http://schema.org/
+
+default_prefix: hc
+
+imports:
+  - linkml:types
+
+# =============================================================================
+# ENUMS
+# =============================================================================
+
+enums:
+  CustodianTypeCodeEnum:
+    description: |
+      Single-letter codes for GLAMORCUBESFIXPHDNT custodian taxonomy.
+      Used to classify heritage custodian institutions by primary type.
+    permissible_values:
+      G:
+        description: Gallery - Art gallery or exhibition space
+        meaning: hc:Gallery
+      L:
+        description: Library - Public, academic, or specialized library
+        meaning: hc:Library
+      A:
+        description: Archive - Government, corporate, or personal archive
+        meaning: hc:Archive
+      M:
+        description: Museum - Art, history, science, or other museum
+        meaning: hc:Museum
+      O:
+        description: Official Institution - Government heritage agency
+        meaning: hc:OfficialInstitution
+      R:
+        description: Research Center - Research institute or documentation center
+        meaning: hc:ResearchCenter
+      C:
+        description: Corporation - Corporate heritage collection
+        meaning: hc:Corporation
+      U:
+        description: Unknown - Institution type cannot be determined
+        meaning: hc:Unknown
+      B:
+        description: Botanical/Zoo - Botanical garden or zoological park
+        meaning: hc:BotanicalZoo
+      E:
+        description: Education Provider - Educational institution with collections
+        meaning: hc:EducationProvider
+      S:
+        description: Collecting Society - Specialized collecting society
+        meaning: hc:CollectingSociety
+      F:
+        description: Features - Physical landscape features with heritage significance
+        meaning: hc:Features
+      I:
+        description: Intangible Heritage Group - Organizations preserving intangible heritage
+        meaning: hc:IntangibleHeritageGroup
+      X:
+        description: Mixed - Multiple types combined
+        meaning: hc:Mixed
+      P:
+        description: Personal Collection - Private personal collection
+        meaning: hc:PersonalCollection
+      H:
+        description: Holy Sites - Religious heritage sites and institutions
+        meaning: hc:HolySites
+      D:
+        description: Digital Platform - Digital heritage platforms and repositories
+        meaning: hc:DigitalPlatform
+      N:
+        description: NGO - Non-governmental heritage organization
+        meaning: hc:NGO
+      T:
+        description: Taste/Smell - Culinary and olfactory heritage institution
+        meaning: hc:TasteSmell
+      "*":
+        description: Universal - Applies to all custodian types
+        meaning: hc:Universal
+
+  DualClassPatternEnum:
+    description: |
+      Role in the dual-class pattern for heritage ontology.
+      Distinguishes between custodian types (organizations) and collection types (materials).
+    permissible_values:
+      custodian_type:
+        description: |
+          This class represents the CUSTODIAN type (the organization).
+          Maps to cpov:PublicOrganisation or schema:Organization.
+      collection_type:
+        description: |
+          This class represents the COLLECTION type (rico:RecordSetType).
+          Maps to rico:RecordSetType for classifying record sets.
+
+  WikidataMappingTypeEnum:
+    description: |
+      Type of mapping relationship to Wikidata entity.
+      Indicates semantic relationship between this class and the Wikidata concept.
+    permissible_values:
+      exact:
+        description: Exact semantic match - concepts are interchangeable
+        meaning: skos:exactMatch
+      close:
+        description: Close semantic match - concepts are similar but not identical
+        meaning: skos:closeMatch
+      broad:
+        description: Wikidata entity is broader/more general
+        meaning: skos:broadMatch
+      narrow:
+        description: Wikidata entity is narrower/more specific
+        meaning: skos:narrowMatch
+      related:
+        description: Associative relationship, not hierarchical
+        meaning: skos:relatedMatch
+      ontonym:
+        description: |
+          The Wikidata entity describes a broader concept (the organization type)
+          rather than the specific record set type being defined. Common in 
+          dual-class patterns where Wikidata lacks separate entities for 
+          collection types vs custodian types.
+
+# =============================================================================
+# CLASSES FOR STRUCTURED METADATA
+# =============================================================================
+
+classes:
+  WikidataAlignment:
+    class_uri: hc:WikidataAlignment
+    description: |
+      Structured metadata for Wikidata entity alignment.
+      Replaces fragmented annotations with a proper structured object.
+      
+      **Example**:
+      ```yaml
+      wikidata_alignment:
+        entity_id: Q27032435
+        entity_label: "academic archive"
+        mapping_type: exact
+        mapping_rationale: "AcademicArchive is semantically equivalent to Q27032435"
+      ```
+    slots:
+      - wikidata_entity_id
+      - wikidata_entity_label
+      - wikidata_mapping_type
+      - wikidata_mapping_rationale
+    annotations:
+      specificity_score: 0.3
+      specificity_rationale: "Universal utility for Wikidata alignment metadata"
+
+  DualClassLink:
+    class_uri: hc:DualClassLink
+    description: |
+      Structured metadata for dual-class pattern linking.
+      Connects custodian types to their corresponding collection types and vice versa.
+      
+      **Pattern**:
+      - Custodian type (organization) ↔ Collection type (rico:RecordSetType)
+      - E.g., AcademicArchive (custodian) ↔ AcademicArchiveRecordSetType (collection)
+    slots:
+      - dual_class_role
+      - linked_class_name
+      - link_rationale
+    annotations:
+      specificity_score: 0.4
+      specificity_rationale: "Structural pattern for heritage ontology class linking"
+
+  SpecificityAnnotation:
+    class_uri: hc:SpecificityAnnotation
+    description: |
+      Structured metadata for RAG retrieval specificity scoring.
+      Documents how specific/general a class is for different search templates.
+      
+      **Scoring Semantics** (LOWER = more broadly relevant):
+      - 0.00-0.20: Universal (HeritageCustodian, Location)
+      - 0.20-0.40: Broadly useful (Collection, Identifier)
+      - 0.40-0.60: Moderately specific (ChangeEvent, PersonProfile)
+      - 0.60-0.80: Fairly specific (Archive, Museum, Library)
+      - 0.80-1.00: Highly specific (LinkedInConnectionExtraction)
+    slots:
+      - specificity_score
+      - specificity_rationale
+      - specificity_timestamp
+      - specificity_agent
+      - template_specificity
+    annotations:
+      specificity_score: 0.2
+      specificity_rationale: "Meta-class for specificity annotations"
+
+  TemplateSpecificityScores:
+    class_uri: hc:TemplateSpecificityScores
+    description: |
+      Per-template specificity scores for RAG context filtering.
+      Allows different relevance weights for different conversation templates.
+      
+      **Templates**:
+      - archive_search: Archival institution queries
+      - museum_search: Museum and gallery queries
+      - library_search: Library and bibliographic queries
+      - collection_discovery: Collection exploration
+      - person_research: Staff and personnel queries
+      - location_browse: Geographic browsing
+      - identifier_lookup: Identifier resolution
+      - organizational_change: Change event queries
+      - digital_platform: Digital systems queries
+      - general_heritage: Fallback for unclassified queries
+    slots:
+      - archive_search_score
+      - museum_search_score
+      - library_search_score
+      - collection_discovery_score
+      - person_research_score
+      - location_browse_score
+      - identifier_lookup_score
+      - organizational_change_score
+      - digital_platform_score
+      - general_heritage_score
+    annotations:
+      specificity_score: 0.3
+      specificity_rationale: "Template-specific relevance scoring"
+
+# =============================================================================
+# SLOTS - GLAMORCUBESFIXPHDNT CUSTODIAN TYPE CLASSIFICATION
+# =============================================================================
+
+slots:
+  # ---------------------------------------------------------------------------
+  # Custodian Type Classification
+  # ---------------------------------------------------------------------------
+  
+  custodian_types:
+    slot_uri: hc:custodianTypes
+    description: |
+      GLAMORCUBESFIXPHDNT custodian type codes that this class applies to.
+      Use ["*"] for universal applicability across all custodian types.
+      
+      **Codes**: G, L, A, M, O, R, C, U, B, E, S, F, I, X, P, H, D, N, T
+      **Mnemonic**: Galleries, Libraries, Archives, Museums, Official institutions,
+                    Research centers, Corporations, Unknown, Botanical/zoos,
+                    Education providers, Societies, Features, Intangible heritage,
+                    miXed, Personal collections, Holy sites, Digital platforms,
+                    NGOs, Taste/smell heritage
+    range: CustodianTypeCodeEnum
+    multivalued: true
+    inlined_as_list: true
+    examples:
+      - value: '["A"]'
+        description: "Applies to Archive type only"
+      - value: '["A", "L", "M"]'
+        description: "Applies to Archive, Library, and Museum types"
+      - value: '["*"]'
+        description: "Universal - applies to all custodian types"
+
+  custodian_types_rationale:
+    slot_uri: hc:custodianTypesRationale
+    description: |
+      Explanation of why specific custodian type codes were assigned.
+      Provides audit trail for type classification decisions.
+    range: string
+    examples:
+      - value: "AcademicArchive is an archival institution - maps to ARCHIVE (A)"
+        description: "Rationale for archive classification"
+
+  custodian_types_primary:
+    slot_uri: hc:custodianTypesPrimary
+    description: |
+      The primary custodian type when multiple types apply.
+      Used for mixed-type institutions to identify the dominant function.
+    range: CustodianTypeCodeEnum
+    examples:
+      - value: "A"
+        description: "Primary type is Archive"
+
+  # ---------------------------------------------------------------------------
+  # Wikidata Alignment (replaces wikidata, wikidata_label annotations)
+  # ---------------------------------------------------------------------------
+
+  wikidata_entity_id:
+    slot_uri: wdt:P31
+    description: |
+      Wikidata entity ID (Q-number) for this class.
+      Links to the corresponding Wikidata concept.
+      
+      **Predicate**: Uses wdt:P31 (instance of) pattern from Wikidata.
+    range: string
+    pattern: "^Q[0-9]+$"
+    examples:
+      - value: "Q27032435"
+        description: "academic archive"
+      - value: "Q166118"
+        description: "archive"
+
+  wikidata_entity_label:
+    slot_uri: rdfs:label
+    description: |
+      Human-readable label for the linked Wikidata entity.
+      Stored for display purposes to avoid repeated API calls.
+    range: string
+    examples:
+      - value: "academic archive"
+        description: "Label for Q27032435"
+
+  wikidata_mapping_type:
+    slot_uri: skos:mappingRelation
+    description: |
+      Type of semantic mapping relationship to the Wikidata entity.
+      Indicates how closely this class aligns with the Wikidata concept.
+    range: WikidataMappingTypeEnum
+    examples:
+      - value: "exact"
+        description: "Exact semantic match"
+      - value: "ontonym"
+        description: "Wikidata describes broader concept"
+
+  wikidata_mapping_rationale:
+    slot_uri: skos:note
+    description: |
+      Explanation of the Wikidata mapping relationship.
+      Documents why a particular mapping type was chosen.
+    range: string
+    examples:
+      - value: "The Wikidata entity Q27032435 describes the broader concept of 'academic archive' (the organization), not specifically the record set type."
+        description: "Ontonym mapping rationale"
+
+  wikidata_alignment:
+    slot_uri: hc:wikidataAlignment
+    description: |
+      Structured Wikidata alignment metadata.
+      Combines entity ID, label, mapping type, and rationale in one object.
+    range: WikidataAlignment
+    inlined: true
+
+  # ---------------------------------------------------------------------------
+  # SKOS Hierarchical Relationships (replaces skos_broader annotation)
+  # ---------------------------------------------------------------------------
+
+  skos_broader:
+    slot_uri: skos:broader
+    description: |
+      SKOS broader (parent) concept in a concept hierarchy.
+      Used for taxonomic relationships between heritage custodian types.
+      
+      **Example**: AcademicArchive skos:broader wd:Q166118 (archive)
+    range: uriorcurie
+    multivalued: true
+    examples:
+      - value: "wd:Q166118"
+        description: "archive (broader concept)"
+
+  skos_broader_label:
+    slot_uri: rdfs:label
+    description: |
+      Human-readable label for the broader concept.
+      Stored for display to avoid repeated lookups.
+    range: string
+    examples:
+      - value: "archive"
+        description: "Label for wd:Q166118"
+
+  skos_narrower:
+    slot_uri: skos:narrower
+    description: |
+      SKOS narrower (child) concepts in a concept hierarchy.
+      Used for taxonomic relationships to more specific types.
+      
+      **Example**: archive skos:narrower AcademicArchive
+    range: uriorcurie
+    multivalued: true
+    examples:
+      - value: "hc:UniversityArchive"
+        description: "More specific university archive type"
+
+  skos_related:
+    slot_uri: skos:related
+    description: |
+      SKOS related concepts (associative, non-hierarchical).
+      Used for concepts that are related but not in a parent-child relationship.
+    range: uriorcurie
+    multivalued: true
+    examples:
+      - value: "wd:Q1065413"
+        description: "Institutional repository (related but different function)"
+
+  # ---------------------------------------------------------------------------
+  # Dual-Class Pattern (replaces linked_collection_type, dual_class_pattern)
+  # ---------------------------------------------------------------------------
+
+  dual_class_role:
+    slot_uri: hc:dualClassRole
+    description: |
+      Role of this class in the dual-class pattern.
+      Either 'custodian_type' (organization) or 'collection_type' (record set).
+    range: DualClassPatternEnum
+    examples:
+      - value: "custodian_type"
+        description: "This class represents the organization"
+      - value: "collection_type"
+        description: "This class represents the record set type"
+
+  linked_class_name:
+    slot_uri: rdfs:seeAlso
+    description: |
+      Name of the linked class in the dual-class pattern.
+      If this is a custodian_type, links to the collection_type and vice versa.
+    range: string
+    examples:
+      - value: "AcademicArchiveRecordSetType"
+        description: "Linked collection type for AcademicArchive custodian"
+      - value: "AcademicArchive"
+        description: "Linked custodian type for AcademicArchiveRecordSetType"
+
+  link_rationale:
+    slot_uri: skos:editorialNote
+    description: |
+      Editorial note explaining the dual-class pattern linkage.
+      Documents the relationship between custodian and collection types.
+    range: string
+    examples:
+      - value: "This class represents the CUSTODIAN type. See linked_class_name for the corresponding rico:RecordSetType."
+        description: "Custodian type link explanation"
+
+  dual_class_link:
+    slot_uri: hc:dualClassLink
+    description: |
+      Structured dual-class pattern metadata.
+      Combines role, linked class, and rationale in one object.
+    range: DualClassLink
+    inlined: true
+
+  # ---------------------------------------------------------------------------
+  # Specificity Scoring for RAG (replaces specificity_* annotations)
+  # ---------------------------------------------------------------------------
+
+  specificity_score:
+    slot_uri: hc:specificityScore
+    description: |
+      Specificity score for RAG retrieval filtering (0.0-1.0).
+      LOWER scores = more broadly relevant; HIGHER scores = more specific.
+      
+      **Score Ranges**:
+      - 0.00-0.20: Universal (HeritageCustodian, Location)
+      - 0.20-0.40: Broadly useful (Collection, Identifier)
+      - 0.40-0.60: Moderately specific (ChangeEvent, PersonProfile)
+      - 0.60-0.80: Fairly specific (Archive, Museum, Library)
+      - 0.80-1.00: Highly specific (LinkedInConnectionExtraction)
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    examples:
+      - value: 0.5
+        description: "Moderately specific class"
+      - value: 0.2
+        description: "Broadly useful class"
+
+  specificity_rationale:
+    slot_uri: skos:note
+    description: |
+      Explanation for the assigned specificity score.
+      Documents reasoning for the score value.
+    range: string
+    examples:
+      - value: "Archive-related class with moderate specificity"
+        description: "Rationale for 0.5 score"
+
+  specificity_timestamp:
+    slot_uri: prov:generatedAtTime
+    description: |
+      ISO 8601 timestamp when the specificity annotation was created.
+      Enables temporal tracking of annotation changes.
+    range: datetime
+    examples:
+      - value: "2026-01-05T10:51:51Z"
+        description: "Annotation timestamp"
+
+  specificity_agent:
+    slot_uri: prov:wasAttributedTo
+    description: |
+      Agent (human or AI) that created the specificity annotation.
+      Uses standard agent identifier format.
+    range: string
+    examples:
+      - value: "opencode-claude-sonnet-4"
+        description: "AI agent identifier"
+      - value: "manual-human-curator"
+        description: "Human curator identifier"
+
+  specificity_annotation:
+    slot_uri: hc:specificityAnnotation
+    description: |
+      Structured specificity annotation metadata.
+      Combines score, rationale, timestamp, and agent.
+    range: SpecificityAnnotation
+    inlined: true
+
+  # Per-template specificity scores
+  
+  template_specificity:
+    slot_uri: hc:templateSpecificity
+    description: |
+      Per-template specificity scores for context-aware RAG filtering.
+      Allows different relevance weights for different conversation templates.
+    range: TemplateSpecificityScores
+    inlined: true
+
+  archive_search_score:
+    slot_uri: hc:archiveSearchScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for archival institution queries
+
+  museum_search_score:
+    slot_uri: hc:museumSearchScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for museum and gallery queries
+
+  library_search_score:
+    slot_uri: hc:librarySearchScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for library and bibliographic queries
+
+  collection_discovery_score:
+    slot_uri: hc:collectionDiscoveryScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for collection exploration
+
+  person_research_score:
+    slot_uri: hc:personResearchScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for staff and personnel queries
+
+  location_browse_score:
+    slot_uri: hc:locationBrowseScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for geographic browsing
+
+  identifier_lookup_score:
+    slot_uri: hc:identifierLookupScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for identifier resolution
+
+  organizational_change_score:
+    slot_uri: hc:organizationalChangeScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for change event queries
+
+  digital_platform_score:
+    slot_uri: hc:digitalPlatformScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for digital systems queries
+
+  general_heritage_score:
+    slot_uri: hc:generalHeritageScore
+    range: float
+    minimum_value: 0.0
+    maximum_value: 1.0
+    description: Specificity score for general heritage queries (fallback)
+
+  # ---------------------------------------------------------------------------
+  # Collection Holdings Relationship (rico:isOrWasHolderOf)
+  # ---------------------------------------------------------------------------
+
+  holds_record_set_types:
+    slot_uri: rico:isOrWasHolderOf
+    description: |
+      Links a custodian type to the record set types it typically holds.
+      Uses RiC-O property rico:isOrWasHolderOf to express custodial relationship.
+      
+      **Example** (AcademicArchive holdings):
+      - UniversityAdministrativeFonds - Governance, committee, policy records
+      - StudentRecordSeries - Enrollment, transcripts, graduation records
+      - FacultyPaperCollection - Personal papers of faculty members
+      - CampusDocumentationCollection - Photos, publications, ephemera
+    range: uriorcurie
+    multivalued: true
+    examples:
+      - value: '["hc:UniversityAdministrativeFonds", "hc:StudentRecordSeries", "hc:FacultyPaperCollection", "hc:CampusDocumentationCollection"]'
+        description: "Academic archive typical holdings"