From 20374b903231a53abb879ee2f9fa9e16e5b08801 Mon Sep 17 00:00:00 2001 From: kempersc Date: Wed, 7 Jan 2026 22:05:21 +0100 Subject: [PATCH] Archive monolithic class_metadata_slots before modular refactoring --- ...ss_metadata_slots_monolithic_20260107.yaml | 721 ++++++++++++++++++ 1 file changed, 721 insertions(+) create mode 100644 schemas/20251121/linkml/archive/refactored/class_metadata_slots_monolithic_20260107.yaml diff --git a/schemas/20251121/linkml/archive/refactored/class_metadata_slots_monolithic_20260107.yaml b/schemas/20251121/linkml/archive/refactored/class_metadata_slots_monolithic_20260107.yaml new file mode 100644 index 0000000000..1482380daa --- /dev/null +++ b/schemas/20251121/linkml/archive/refactored/class_metadata_slots_monolithic_20260107.yaml @@ -0,0 +1,721 @@ +# 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: + # NOTE: CustodianTypeCodeEnum has been REPLACED by CustodianType class hierarchy + # See: ../classes/CustodianType.yaml and its subclasses (ArchiveOrganizationType, + # MuseumType, LibraryType, etc.) + # + # The custodian_types slot now references CustodianType class instead of an enum. + # Single-letter codes (GLAMORCUBESFIXPHDNT) are derived from class hierarchy. + + 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: | + References to CustodianType subclasses that this class applies to. + + **Class Hierarchy** (replaces CustodianTypeCodeEnum): + - ArchiveOrganizationType (A) + - BioCustodianType (B) + - CommercialOrganizationType (C) + - DigitalPlatformType (D) + - EducationProviderType (E) + - FeatureCustodianType (F) + - GalleryType (G) + - HolySacredSiteType (H) + - IntangibleHeritageGroupType (I) + - LibraryType (L) + - MuseumType (M) + - NonProfitType (N) + - OfficialInstitutionType (O) + - PersonalCollectionType (P) + - ResearchOrganizationType (R) + - HeritageSocietyType (S) + - TasteScentHeritageType (T) + - UnspecifiedType (U) + - MixedCustodianType (X) + + **Format**: Use CustodianType class URIs like 'hc:ArchiveOrganizationType'. + All schemas have been migrated from legacy single-letter codes to proper URIs. + range: uriorcurie + multivalued: true + inlined_as_list: true + examples: + - value: 'hc:ArchiveOrganizationType' + description: "Applies to Archive type only" + - value: '["hc:ArchiveOrganizationType", "hc:LibraryType", "hc:MuseumType"]' + description: "Applies to Archive, Library, and Museum types" + + custodian_types_rationale: + slot_uri: hc:custodianTypesRationale + description: | + Explanation of why specific custodian types were assigned. + Provides audit trail for type classification decisions. + range: string + examples: + - value: "AcademicArchive is an archival institution - maps to ArchiveOrganizationType" + 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. + References a CustodianType subclass. + range: uriorcurie + examples: + - value: "hc:ArchiveOrganizationType" + 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) + # --------------------------------------------------------------------------- + + # NOTE: holds_record_set_types is defined in ./holds_record_set_types.yaml + # DO NOT duplicate here - import that file instead + + # --------------------------------------------------------------------------- + # RiC-O RecordSet Metadata (for RecordSetType classes) + # --------------------------------------------------------------------------- + + # NOTE: rico_record_set_type is defined in ../slots/rico_record_set_type.yaml + # DO NOT duplicate here - import that file instead + + rico_organizational_principle: + slot_uri: rico:hasOrHadAllMembersWithOrganizationalPrinciple + description: | + The organizational principle by which records in this set are arranged. + From RiC-O vocabulary. + range: string + examples: + - value: "Provenance" + description: "Organized by creator/origin" + - value: "Subject" + description: "Organized by topic" + + rico_organizational_principle_uri: + slot_uri: rico:hasOrHadAllMembersWithOrganizationalPrinciple + description: | + URI for the RiC-O organizational principle. + range: string + examples: + - value: "rico:OrganizationalPrincipleProvenance" + description: "RiC-O provenance principle" + + rico_has_or_had_holder: + slot_uri: rico:hasOrHadHolder + description: | + The custodian type(s) that typically hold this type of record set. + Inverse of rico:isOrWasHolderOf. + range: string + multivalued: true + examples: + - value: "hc:AcademicArchive" + description: "Held by academic archives" + + rico_has_or_had_holder_note: + slot_uri: rico:scopeAndContent + description: | + Note explaining the typical custodial relationship for this record set type. + range: string + + rico_note: + slot_uri: rico:scopeAndContent + description: | + General RiC-O scope and content note for this class. + range: string + + # --------------------------------------------------------------------------- + # Multilingual Labels (SKOS) + # --------------------------------------------------------------------------- + + label_de: + slot_uri: skos:prefLabel + description: German language label for this class + range: string + annotations: + language: de + + label_es: + slot_uri: skos:prefLabel + description: Spanish language label for this class + range: string + annotations: + language: es + + label_fr: + slot_uri: skos:prefLabel + description: French language label for this class + range: string + annotations: + language: fr + + label_nl: + slot_uri: skos:prefLabel + description: Dutch language label for this class + range: string + annotations: + language: nl + + label_it: + slot_uri: skos:prefLabel + description: Italian language label for this class + range: string + annotations: + language: it + + label_pt: + slot_uri: skos:prefLabel + description: Portuguese language label for this class + range: string + annotations: + language: pt + + # --------------------------------------------------------------------------- + # Scope and Classification Metadata + # --------------------------------------------------------------------------- + + # NOTE: scope_includes and scope_excludes are defined in ./type_scope.yaml + # DO NOT duplicate here + + custodian_only: + slot_uri: hc:custodianOnly + description: | + If true, this class represents only a custodian type with no + corresponding rico:RecordSetType collection class. + range: boolean + + # NOTE: custodian_type is defined in ./custodian_type.yaml + # DO NOT duplicate here + + organizational_level: + slot_uri: hc:organizationalLevel + description: | + Administrative/organizational level of this institution type. + Examples: national, regional, provincial, municipal, local + range: string + examples: + - value: "national" + description: "National-level institution" + - value: "municipal" + description: "City/town-level institution" + + geographic_restriction: + slot_uri: hc:geographicRestriction + description: | + Geographic scope or restriction for this class. + Used when a class is specific to certain countries or regions. + range: string + examples: + - value: "France" + description: "Specific to France" + - value: "German-speaking countries" + description: "Germany, Austria, Switzerland" + + # --------------------------------------------------------------------------- + # Notes and Documentation + # --------------------------------------------------------------------------- + + privacy_note: + slot_uri: skos:note + description: | + Note about privacy considerations for this type of record/institution. + range: string + + preservation_note: + slot_uri: skos:note + description: | + Note about preservation considerations for this type of record/institution. + range: string + + legal_note: + slot_uri: skos:note + description: | + Note about legal considerations (access, copyright, retention) for this class. + range: string