# UpdateFrequency - Structured frequency/periodicity for data updates
# Created per slot_fixes.yaml migration for: update_frequency
# Creation date: 2026-01-14
#
# REVISION FROM slot_fixes.yaml (lines 1893-1910):
#   - label: has_or_had_frequency (slot)
#   - label: UpdateFrequency (class) ← THIS FILE
#   - link_branch 1: has_or_had_quantity → Quantity
#   - link_branch 2: has_or_had_time_interval → TimeInterval

id: https://nde.nl/ontology/hc/classes/UpdateFrequency
name: UpdateFrequency
title: UpdateFrequency

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  dcterms: http://purl.org/dc/terms/
  dcat: http://www.w3.org/ns/dcat#
  schema: http://schema.org/
  time: http://www.w3.org/2006/time#

imports:
  - linkml:types
  - ./Quantity
  - ./TimeInterval
  - ../slots/has_or_had_quantity
  - ../slots/has_or_had_time_interval

default_range: string

classes:
  UpdateFrequency:
    description: >-
      Structured representation of how often a device, system, or data source
      sends updates or refreshes data.
      
      **WHY A DEDICATED CLASS?**
      
      Update frequency is more than a simple string - it has:
      - **Quantity**: How many updates (e.g., "5" in "every 5 minutes")
      - **Time Interval**: The period (e.g., "minutes" in "every 5 minutes")
      - **Trigger-based**: Some updates are event-driven, not time-based
      
      **SLOT_FIXES.YAML REVISION** (lines 1893-1910):
      - Branch 1: has_or_had_quantity → Quantity (numeric value)
      - Branch 2: has_or_had_time_interval → TimeInterval (duration)
      
      **ONTOLOGY MAPPING**:
      - class_uri: dcterms:Frequency (Dublin Core)
      - Dublin Core `accrualPeriodicity` uses Frequency for collection update rates
      
      **USE CASES**:
      - IoT sensors: "Every 5 minutes", "Hourly", "Real-time"
      - Data feeds: "Daily", "Weekly", "Monthly"
      - Event-driven: "On proximity trigger", "On change"
      
      **EXAMPLES**:
      - Climate sensor: 5 updates per minute
      - Beacon: On proximity trigger (no time interval)
      - Database sync: Daily at midnight
      
    class_uri: dcterms:Frequency
    
    exact_mappings:
      - dcterms:Frequency
      - dcat:frequency
    
    close_mappings:
      - schema:Schedule
    
    related_mappings:
      - time:TemporalEntity
    
    slots:
      - has_or_had_quantity
      - has_or_had_time_interval
    
    attributes:
      frequency_description:
        range: string
        description: >-
          Human-readable description of the update frequency.
          Examples: "Every 5 minutes", "Hourly", "Real-time", "On proximity trigger"
      
      is_event_driven:
        range: boolean
        description: >-
          True if updates are triggered by events rather than time intervals.
          Examples: beacon proximity triggers, change detection, user actions.
        ifabsent: "false"
      
      trigger_type:
        range: string
        description: >-
          Type of event that triggers updates (when is_event_driven is true).
          Examples: "proximity", "change", "request", "threshold"
    
    slot_usage:
      has_or_had_quantity:
        range: Quantity
        inlined: true
        description: >-
          The numeric quantity component of the frequency.
          For "every 5 minutes", this would be a Quantity with value 5.
        examples:
          - value: |
              has_or_had_quantity:
                numeric_value: 5
                has_or_had_measurement_unit:
                  has_or_had_symbol: "updates"
            description: 5 updates per interval
      
      has_or_had_time_interval:
        range: TimeInterval
        inlined: true
        description: >-
          The time interval/period component of the frequency.
          For "every 5 minutes", this would be a TimeInterval representing minutes.
        examples:
          - value: |
              has_or_had_time_interval:
                duration_value: "PT1M"
                duration_description: "per minute"
            description: Per-minute interval
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: >-
        Update frequency applicable to all custodian types with IoT or data systems.
      custodian_types_primary: "*"
      specificity_score: 0.35
      specificity_rationale: >-
        Moderate specificity - relevant to custodians with digital/IoT infrastructure.
    
    examples:
      - value: |
          UpdateFrequency:
            frequency_description: "Every 5 minutes"
            has_or_had_quantity:
              numeric_value: 5
            has_or_had_time_interval:
              duration_value: "PT1M"
              duration_description: "minute"
        description: Climate sensor updating every 5 minutes.
      
      - value: |
          UpdateFrequency:
            frequency_description: "Hourly"
            has_or_had_quantity:
              numeric_value: 1
            has_or_had_time_interval:
              duration_value: "PT1H"
              duration_description: "hour"
        description: Hourly update frequency.
      
      - value: |
          UpdateFrequency:
            frequency_description: "On proximity trigger"
            is_event_driven: true
            trigger_type: "proximity"
        description: Event-driven beacon updates (no time interval).
      
      - value: |
          UpdateFrequency:
            frequency_description: "Real-time"
            is_event_driven: true
            trigger_type: "continuous"
        description: Real-time streaming updates.
    
    comments:
      - Created from slot_fixes.yaml migration (2026-01-14)
      - Replaces simple string update_frequency slot
      - Supports both time-based and event-driven frequencies
      - Uses Dublin Core Frequency class for semantic alignment