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
  - ../slots/has_description
  - ../slots/identified_by
  - ../slots/has_label
  - ../slots/has_score  # was: template_specificity
  - ../slots/has_type
  - ../slots/include
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 categorized_as slot:
      
      ```yaml
      finding_aid:
        has_type:
          - has_type: GenealogyTopic
            has_label:
              - label_value: "Genealogy"
                language_code: "en"
          - has_type: CivilRegistryTopic
            has_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:
      - identified_by
      - has_label
      - has_description
      - has_type
      - include
      - has_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
    
    slot_usage:
      has_label:
        required: true
        multivalued: true
      has_type:
      has_score:
#         range: string # uriorcurie
      has_description:
      include:
#         range: string
        multivalued: true
    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.