# Timestamp class
# A point in time with optional precision and calendar metadata
#
# Generation date: 2026-01-15
# Rule compliance: 0 (LinkML single source of truth), 38 (slot centralization), 53 (slot_fixes.yaml)
#
# This class supports 6 slot migrations per slot_fixes.yaml:
# - valid_to_geo
# - valid_to
# - valid_from_geo
# - valid_from
# - updated_at
# - unesco_inscription_year
#
# Ontological basis: OWL Time Instant (time:Instant)

id: https://nde.nl/ontology/hc/class/Timestamp
name: timestamp_class
title: Timestamp Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  time: http://www.w3.org/2006/time#
  xsd: http://www.w3.org/2001/XMLSchema#
  crm: http://www.cidoc-crm.org/cidoc-crm/
  schema: http://schema.org/

default_prefix: hc

imports:
  - linkml:types
  - ../metadata
  - ../slots/has_or_had_timestamp  # was: timestamp_value - migrated per Rule 53
  - ../slots/has_or_had_precision  # was: timestamp_precision - migrated per Rule 53
  # MIGRATED 2026-01-22: calendar_system → complies_or_complied_with + CalendarSystem
  - ../slots/complies_or_complied_with
  - ./CalendarSystem
  - ../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:
  Timestamp:
    class_uri: time:Instant
    description: |
      A point in time with optional precision and calendar metadata.
      
      **Purpose**:
      Timestamp provides a reusable class for representing temporal instants
      with explicit precision indicators. This supports EDTF-style partial
      dates (year-only, year-month, full date, datetime) and calendar system
      annotation for non-Gregorian dates.
      
      **Ontological Alignment**:
      - **Primary**: `time:Instant` - OWL Time instant
      - **Close**: `crm:E61_Time_Primitive` - CIDOC-CRM time primitive
      - **Related**: `xsd:dateTime` - XML Schema dateTime
      
      **Use Cases**:
      - Beginning/ending of time spans (TimeSpan.begin_of_the_begin, etc.)
      - Validity dates (valid_from, valid_to)
      - Update timestamps (updated_at, created_at)
      - Historical dates with varying precision
      
      **Precision Levels**:
      - year: "1995" (EDTF: "1995")
      - month: "1995-06" (EDTF: "1995-06")
      - day: "1995-06-15" (EDTF: "1995-06-15")
      - datetime: "1995-06-15T10:30:00" (full precision)
      
      **Replaces** (per slot_fixes.yaml):
      - `valid_to_geo` → TimeSpan.end_of_the_end: Timestamp
      - `valid_to` → TimeSpan.end_of_the_end: Timestamp
      - `valid_from_geo` → TimeSpan.begin_of_the_begin: Timestamp
      - `valid_from` → TimeSpan.begin_of_the_begin: Timestamp
      - `updated_at` → was_last_updated_at: TimeSpan
      - `unesco_inscription_year` → TimeSpan.begin_of_the_begin: Timestamp
      
    exact_mappings:
      - time:Instant
    
    close_mappings:
      - crm:E61_Time_Primitive
    
    related_mappings:
      - xsd:dateTime
      - schema:DateTime
    
    slots:
      - has_or_had_timestamp  # was: timestamp_value - migrated per Rule 53
      - has_or_had_precision  # was: timestamp_precision - migrated per Rule 53
      - complies_or_complied_with  # was: calendar_system - migrated 2026-01-22
      - specificity_annotation
      - has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
    
    slot_usage:
      has_or_had_timestamp:  # was: timestamp_value - migrated per Rule 53
        description: |
          The timestamp value as ISO 8601 string.
          Precision determined by string format:
          - "1995" = year precision
          - "1995-06" = month precision
          - "1995-06-15" = day precision
          - "1995-06-15T10:30:00Z" = full datetime
        range: string
        required: true
        pattern: "^-?\\d{4}(-\\d{2})?(-\\d{2})?(T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})?)?$"
      has_or_had_precision:  # was: timestamp_precision - migrated per Rule 53
        description: |
          Explicit precision level. Auto-derived from timestamp_value if not provided.
          Values: year, month, day, hour, minute, second, millisecond
        range: string
        required: false
        examples:
          - value: year
          - value: day
          - value: second
      complies_or_complied_with:
        description: |
          Calendar system for the timestamp. Default is Gregorian.
          MIGRATED 2026-01-22: Replaces calendar_system string with CalendarSystem class.
          For historical or non-Western dates, specify the calendar.
        range: CalendarSystem
        required: false
        inlined: true
        examples:
          - value:
              system_code: gregorian
              system_name: "Gregorian Calendar"
            description: Standard Gregorian calendar
          - value:
              system_code: julian
              system_name: "Julian Calendar"
            description: Julian calendar for historical dates
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: Generic timestamp class applicable to all types.
      custodian_types_primary: null
      specificity_score: 0.15
      specificity_rationale: Very broadly applicable generic class for temporal points.
    
    examples:
      - value: |
          has_or_had_timestamp: "1995"
          has_or_had_precision: year
        description: "Year-only timestamp (e.g., founding year)"
      - value: |
          has_or_had_timestamp: "2024-06-15"
          has_or_had_precision: day
          complies_or_complied_with:
            system_code: gregorian
            system_name: "Gregorian Calendar"
        description: "Full date timestamp with calendar system"
      - value: |
          has_or_had_timestamp: "2024-06-15T14:30:00Z"
          has_or_had_precision: second
          complies_or_complied_with:
            system_code: gregorian
        description: "Full datetime timestamp"