From bc562bd68d6131c3cf974de55885ab928ee0aff1 Mon Sep 17 00:00:00 2001 From: kempersc Date: Tue, 6 Jan 2026 11:16:49 +0100 Subject: [PATCH] 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 --- .../classes/AcademicArchive_refactored.yaml | 303 +++++++++ .../slots/ANNOTATION_TO_SLOT_MIGRATION.md | 138 ++++ .../modules/slots/class_metadata_slots.yaml | 619 ++++++++++++++++++ 3 files changed, 1060 insertions(+) create mode 100644 schemas/20251121/linkml/modules/classes/AcademicArchive_refactored.yaml create mode 100644 schemas/20251121/linkml/modules/slots/ANNOTATION_TO_SLOT_MIGRATION.md create mode 100644 schemas/20251121/linkml/modules/slots/class_metadata_slots.yaml diff --git a/schemas/20251121/linkml/modules/classes/AcademicArchive_refactored.yaml b/schemas/20251121/linkml/modules/classes/AcademicArchive_refactored.yaml new file mode 100644 index 0000000000..1ac5bef5f8 --- /dev/null +++ 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 diff --git a/schemas/20251121/linkml/modules/slots/ANNOTATION_TO_SLOT_MIGRATION.md b/schemas/20251121/linkml/modules/slots/ANNOTATION_TO_SLOT_MIGRATION.md new file mode 100644 index 0000000000..9d2d4c3c34 --- /dev/null +++ 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 diff --git a/schemas/20251121/linkml/modules/slots/class_metadata_slots.yaml b/schemas/20251121/linkml/modules/slots/class_metadata_slots.yaml new file mode 100644 index 0000000000..8008fdc653 --- /dev/null +++ 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"