# Topic - Subject topic instance
#
# A Topic represents a specific subject topic assigned to a heritage resource.
# Uses TopicType for classification.
#
# Migration: topic slot → is_or_was_categorized_as with Topic class
# Generation date: 2026-01-15
# Rule compliance: 53 (no bespoke slots), 39 (RiC-O naming)

id: https://nde.nl/ontology/hc/class/Topic
name: Topic
title: Subject Topic

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  skos: http://www.w3.org/2004/02/skos/core#
  dcterms: http://purl.org/dc/terms/
  rico: https://www.ica.org/standards/RiC/ontology#

default_prefix: hc

imports:
  - linkml:types
  - ./TopicType
  - ./TopicTypes
  - ../slots/has_or_had_identifier
  - ../slots/has_or_had_label
  - ../slots/has_or_had_description
  - ../slots/has_or_had_type
  - ../slots/includes_or_included
  - ../slots/specificity_annotation
  - ../slots/has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
  - ./SpecificityAnnotation
  - ./TemplateSpecificityScore  # was: TemplateSpecificityScores - migrated per Rule 53 (2026-01-17)

  - ./TemplateSpecificityType

  - ./TemplateSpecificityTypes

classes:
  Topic:
    class_uri: skos:Concept
    description: |
      A subject topic instance assigned to a heritage resource.
      
      **DEFINITION**:
      
      Topic represents a SPECIFIC subject topic assignment (instance)
      as opposed to TopicType which represents the CATEGORY of topics.
      
      **CRITICAL: TYPE vs INSTANCE**
      
      | Aspect | TopicType | Topic (This Class) |
      |--------|-----------|-------------------|
      | **Nature** | Classification/category | Specific topic instance |
      | **Examples** | GENEALOGY, CIVIL_REGISTRY | "Civil Registry in Utrecht 1811-1900" |
      | **Properties** | Category metadata | Specific subject term, scope |
      | **Cardinality** | ~20-50 types | Many instances |
      
      **USAGE**:
      
      Topics are linked to heritage resources (finding aids, collections, etc.)
      via the is_or_was_categorized_as slot:
      
      ```yaml
      finding_aid:
        is_or_was_categorized_as:
          - has_or_had_type: GenealogyTopic
            has_or_had_label:
              - label_value: "Genealogy"
                language_code: "en"
          - has_or_had_type: CivilRegistryTopic
            has_or_had_label:
              - label_value: "Burgerlijke Stand"
                language_code: "nl"
      ```
      
      **MIGRATION**:
      
      Replaces bespoke `topic` slot (string list) with structured Topic class.
      Original slot: ../slots/topic.yaml (archived 2026-01-15)
      
      **ONTOLOGY ALIGNMENT**:
      
      - SKOS: skos:Concept (subject concept)
      - Dublin Core: dcterms:subject (subject of resource)
      - RiC-O: rico:hasOrHadSubject (subject relationship)
      
    exact_mappings:
      - skos:Concept
    close_mappings:
      - dcterms:subject
      - rico:hasOrHadSubject
    
    slots:
      - has_or_had_identifier
      - has_or_had_label
      - has_or_had_description
      - has_or_had_type
      - includes_or_included
      - specificity_annotation
      - has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
    
    slot_usage:
      has_or_had_label:
        required: true
        multivalued: true
        inlined: true
        description: |
          Human-readable label for this specific topic.
          Supports multilingual labels.
      has_or_had_type:
        range: TopicType
        description: |
          The type/category of this topic.
          Uses TopicType class hierarchy.
      has_or_had_description:
        description: |
          Detailed description of this specific topic's scope.
      includes_or_included:
        range: Topic
        multivalued: true
        inlined_as_list: true
        description: |
          Sub-topics included within this topic.
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: Subject topics are universal across all heritage custodian types.
      custodian_types_primary: A
      specificity_score: 0.45
      specificity_rationale: >-
        Broadly applicable - topic instances are common across all
        heritage resource types for subject classification.