# CertaintyLevel class
# Structured class for expressing certainty/confidence levels with notes
#
# Generation date: 2026-01-18
# Rule compliance: 0 (LinkML single source of truth), 38 (slot centralization), 53 (slot_fixes.yaml)
# Migration: Replaces certainty_level + certainty_note bespoke slots
#
# Created per slot_fixes.yaml revisions:
# - certainty_level → has_or_had_level + CertaintyLevel
# - certainty_note → has_or_had_note + Note (within CertaintyLevel)

id: https://nde.nl/ontology/hc/class/CertaintyLevel
name: certainty_level_class
title: Certainty Level Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  crm: http://www.cidoc-crm.org/cidoc-crm/
  rico: https://www.ica.org/standards/RiC/ontology#
  skos: http://www.w3.org/2004/02/skos/core#
  prov: http://www.w3.org/ns/prov#

default_prefix: hc

imports:
  - linkml:types
  - ../metadata
  - ../slots/level_value
  - ../slots/has_or_had_note
  - ./Note
  - ../slots/specificity_annotation
  - ../slots/has_or_had_score
  - ./SpecificityAnnotation
  - ./TemplateSpecificityScore
  - ./TemplateSpecificityType
  - ./TemplateSpecificityTypes

classes:
  CertaintyLevel:
    class_uri: rico:ConfidenceLevel
    description: |
      A structured representation of certainty/confidence level with explanatory notes.
      
      **Purpose**:
      CertaintyLevel encapsulates both the level of certainty (CERTAIN, PROBABLE,
      POSSIBLE, UNCERTAIN) and any notes explaining the certainty assessment.
      Used primarily in provenance research to document confidence in ownership
      transfer claims.
      
      **Ontological Alignment**:
      - **Primary**: `rico:ConfidenceLevel` - RiC-O confidence level
      - **Close**: `crm:P141_assigned` - CIDOC-CRM attribute assignment
      
      **Standard Values for level_value**:
      - CERTAIN: Documentary evidence confirms the claim
      - PROBABLE: Strong circumstantial evidence supports the claim
      - POSSIBLE: Reasonable inference from available context
      - UNCERTAIN: Speculative or unverified claim
      
      **Use Cases**:
      - Provenance event certainty (ProvenanceEvent)
      - Attribution confidence (artwork authorship)
      - Dating confidence (temporal assertions)
      - Identification confidence (person/place identification)
      
      **Replaces** (per slot_fixes.yaml):
      - `certainty_level` (string) → has_or_had_level with CertaintyLevel class
      - `certainty_note` (string) → has_or_had_note with Note class (within CertaintyLevel)
      
    exact_mappings:
      - rico:ConfidenceLevel
    
    close_mappings:
      - crm:P141_assigned
      - prov:qualifiedAssociation
    
    slots:
      - level_value
      - has_or_had_note
      - specificity_annotation
      - has_or_had_score
    
    slot_usage:
      level_value:
        description: |
          The certainty/confidence level value.
          Standard values: CERTAIN, PROBABLE, POSSIBLE, UNCERTAIN.
        range: string
        required: true
        examples:
          - value: CERTAIN
            description: Documentary evidence confirms claim
          - value: PROBABLE
            description: Strong circumstantial evidence
          - value: POSSIBLE
            description: Reasonable inference
          - value: UNCERTAIN
            description: Speculative/unverified
      has_or_had_note:
        description: |
          Notes explaining the certainty assessment.
          Use Note class with note_type: "certainty" for certainty-specific notes.
        range: Note
        multivalued: true
        inlined: true
        required: false
        examples:
          - value:
              note_type: certainty
              note_content: "Confirmed by sale catalogue and receipt"
            description: Documentary evidence note
          - value:
              note_type: certainty
              note_content: "Inferred from stylistic analysis and collection history"
            description: Circumstantial evidence note
          - value:
              note_type: certainty
              note_content: "Provenance gap 1933-1945 requires further research"
            description: Research gap note
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: Certainty documentation applicable to all custodian types.
      custodian_types_primary: null
      specificity_score: 0.4
      specificity_rationale: Moderately specific class for provenance and attribution certainty.
    
    examples:
      - value: |
          level_value: CERTAIN
          has_or_had_note:
            - note_type: certainty
              note_content: "Confirmed by sale catalogue and receipt"
              note_date: "2025-06-15"
        description: "Certain provenance event with documentary evidence"
      - value: |
          level_value: PROBABLE
          has_or_had_note:
            - note_type: certainty
              note_content: "Van Ruijven was Vermeer's patron; likely acquired directly from artist"
        description: "Probable ownership based on historical relationship"
      - value: |
          level_value: UNCERTAIN
          has_or_had_note:
            - note_type: certainty
              note_content: "Provenance gap 1933-1945 requires further research"
            - note_type: certainty
              note_content: "Documentation incomplete; collector fled Vienna 1938"
        description: "Uncertain Nazi-era provenance requiring research"