# StorageCondition Class - Observed condition reports for storage facilities
# 
# Represents ACTUAL observed conditions (what IS), which may differ
# from StorageConditionPolicy (what SHOULD BE).
# 
# Based on PiCo observation pattern: observations from multiple sources
# can report different conditions for the same storage facility.
# 
# Generation date: 2025-11-29
# 
id: https://nde.nl/ontology/hc/class/StorageCondition
name: storage_condition_class
title: Storage Condition Observation Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  crm: http://www.cidoc-crm.org/cidoc-crm/
  premis: http://www.loc.gov/premis/rdf/v3/
  prov: http://www.w3.org/ns/prov#
  schema: http://schema.org/
  dcterms: http://purl.org/dc/terms/
  pico: https://personsincontext.org/model#

default_prefix: hc

imports:
  - linkml:types
  - ./Storage
  - ./TimeSpan
  - ../enums/StorageConditionStatusEnum
  - ../enums/StorageObserverTypeEnum
  - ../slots/supersedes
  - ../slots/confidence_score
  - ../slots/observation_date

classes:
  StorageCondition:
    class_uri: prov:Activity
    description: |
      An observation-based report of actual storage conditions.
      
      **DEFINITION**:
      
      StorageCondition represents a specific assessment or observation of
      a storage facility's actual state at a point in time. Multiple
      observations can exist for the same storage facility, from different
      observers with potentially different findings.
      
      **CRITICAL DISTINCTION**:
      
      - **StorageCondition** (THIS CLASS): What IS - actual observed state
      - **StorageConditionPolicy**: What SHOULD BE - designed/intended conditions
      
      The gap between policy and observed condition is often significant
      and represents a critical transparency concern.
      
      **PiCo OBSERVATION PATTERN**:
      
      Following the Person in Context (PiCo) ontology pattern, observations
      are NOT assertions of truth but reports from specific observers with
      their own perspectives and potential biases.
      
      A journalist discovering white ants in a storage facility creates an
      observation with:
      - observer_type: JOURNALIST
      - condition_status: CRITICAL
      - category: PEST_CONTROL
      - observation_notes: "White ants discovered in main document depot"
      
      This observation exists ALONGSIDE any official self-assessment, without
      requiring reconciliation of conflicting reports.
      
      **PROV-O ALIGNMENT**:
      
      `prov:Activity` - "An activity is something that occurs over a period
      of time and acts upon or with entities; it may include consuming,
      processing, transforming, modifying, relocating, using, or generating
      entities."
      
      The observation activity:
      - `prov:wasAssociatedWith` → observer (prov:Agent)
      - `prov:used` → storage facility being observed
      - `prov:atTime` → observation timestamp
      - `prov:generated` → this condition report
      
      **RELATIONSHIP TO STORAGE CLASS**:
      
      ```
      Storage
        │
        ├── storage_conditions[] → StorageCondition (THIS CLASS)
        │     ├── Observation 1: Internal staff, 2024-06 → GOOD
        │     ├── Observation 2: Journalist, 2024-09 → CRITICAL (pest issue)
        │     └── Observation 3: Government inspector, 2024-10 → POOR
        │
        └── condition_policy → StorageConditionPolicy (what SHOULD be)
      ```
      
      **USE CASES**:
      
      1. **Regular Internal Assessment**:
         - observer_type: INTERNAL_STAFF
         - is_official_assessment: true
         - category_assessments: Temperature=GOOD, Humidity=GOOD
         
      2. **Investigative Journalism**:
         - observer_type: JOURNALIST
         - is_official_assessment: false
         - observation_notes: "Photographs show water damage in basement storage"
         - evidence_documentation: [URLs to published article]
         
      3. **Government Inspection**:
         - observer_type: GOVERNMENT_INSPECTOR
         - is_official_assessment: true (regulatory authority)
         - compliance_status: "NON_COMPLIANT"
         - remediation_required: true
         
      4. **Automated Monitoring**:
         - observer_type: AUTOMATED_SYSTEM
         - category: TEMPERATURE
         - measurement_value: "23.5°C"
         - threshold_exceeded: true
    
    exact_mappings:
      - prov:Activity
    
    close_mappings:
      - crm:E7_Activity
      - premis:Event
      - pico:Observation
    
    slots:
      - condition_id
      - refers_to_storage
      - observation_date
      - observation_period
      - observer_type
      - observer_name
      - observer_affiliation
      - is_official_assessment
      - overall_status
      - category_assessments
      - observation_notes
      - evidence_documentation
      - measurement_data
      - compliance_status
      - remediation_required
      - remediation_notes
      - follow_up_date
      - confidence_score
      - supersedes
    
    slot_usage:
      condition_id:
        slot_uri: dcterms:identifier
        description: |
          Unique identifier for this condition observation.
          Format: URI following NDE Heritage Custodian ontology conventions.
        range: uriorcurie
        required: true
        identifier: true
        examples:
          - value: "https://nde.nl/ontology/hc/condition/rijksmuseum-depot-2024-q2"
            description: "Q2 2024 assessment of Rijksmuseum depot"
      
      refers_to_storage:
        slot_uri: prov:used
        description: |
          The storage facility being assessed.
          
          Links this observation to the Storage instance it describes.
          
          PROV-O: used indicates entities used in activity.
        range: Storage
        required: true
        examples:
          - value: "https://nde.nl/ontology/hc/storage/rijksmuseum-depot-amersfoort"
      
      observation_date:
        slot_uri: prov:atTime
        description: |
          Date when this observation was made.
          
          For automated systems: timestamp of data collection.
          For human observers: date of site visit or assessment.
          
          PROV-O: atTime specifies instant at which activity occurred.
        range: date
        required: true
        examples:
          - value: "2024-09-15"
      
      observation_period:
        slot_uri: crm:P4_has_time-span
        description: |
          Time period covered by this observation if not a point-in-time.
          
          Use for assessments covering a period (e.g., quarterly review)
          rather than a single site visit.
          
          CIDOC-CRM: P4_has_time-span for temporal extent.
        range: TimeSpan
        examples:
          - value: "Q2 2024 (April-June)"
      
      observer_type:
        slot_uri: prov:wasAssociatedWith
        description: |
          Type of observer who made this assessment.
          
          **CRITICAL**: Determines how to interpret the observation.
          - INTERNAL_STAFF may underreport issues
          - JOURNALIST may have discovered unreported problems
          - GOVERNMENT_INSPECTOR has regulatory authority
          - WHISTLEBLOWER may have insider knowledge
          
          PROV-O: wasAssociatedWith links activity to responsible agent.
        range: StorageObserverTypeEnum
        required: true
        examples:
          - value: "JOURNALIST"
          - value: "INTERNAL_STAFF"
          - value: "GOVERNMENT_INSPECTOR"
      
      observer_name:
        slot_uri: prov:wasAssociatedWith
        description: |
          Name of the individual or team who made this observation.
          
          May be anonymized for whistleblowers or confidential sources.
        range: string
        examples:
          - value: "Maria van der Berg"
          - value: "Collections Management Team"
          - value: "Anonymous (confidential source)"
      
      observer_affiliation:
        slot_uri: prov:actedOnBehalfOf
        description: |
          Organization the observer represents or works for.
          
          For journalists: newspaper/media outlet.
          For inspectors: government agency.
          For consultants: consulting firm.
          
          PROV-O: actedOnBehalfOf indicates delegated authority.
        range: string
        examples:
          - value: "De Volkskrant"
          - value: "Rijksdienst voor het Cultureel Erfgoed"
          - value: "ABC Conservation Consultants"
      
      is_official_assessment:
        slot_uri: prov:wasAttributedTo
        description: |
          Whether this is an official institutional assessment or external observation.
          
          TRUE = Official self-assessment or authorized inspection.
          FALSE = External/investigative observation not sanctioned by institution.
          
          **Important for interpretation**: Official assessments represent what
          the institution claims; external observations may contradict this.
        range: boolean
        required: true
        examples:
          - value: true
            description: "Official annual condition survey"
          - value: false
            description: "Journalist investigation"
      
      overall_status:
        slot_uri: premis:hasOutcome
        description: |
          Overall condition status based on this observation.
          
          Aggregate assessment across all categories observed.
          Individual category assessments may vary.
          
          PREMIS: hasOutcome for preservation action results.
        range: StorageConditionStatusEnum
        required: true
        examples:
          - value: "CRITICAL"
            description: "White ant infestation discovered"
          - value: "GOOD"
            description: "All parameters within acceptable ranges"
      
      category_assessments:
        slot_uri: schema:hasPart
        description: |
          Individual condition assessments for specific categories.
          
          Each entry maps a StorageConditionCategoryEnum to a status and notes.
          Not all categories need to be assessed in every observation.
          
          Structure: List of category assessment objects with:
          - category: StorageConditionCategoryEnum value
          - status: StorageConditionStatusEnum value
          - measurement: Optional measurement value
          - notes: Optional category-specific notes
        range: StorageConditionCategoryAssessment
        multivalued: true
        inlined_as_list: true
        examples:
          - value:
              - category: "TEMPERATURE"
                status: "GOOD"
                measurement: "19.5°C"
              - category: "PEST_CONTROL"
                status: "CRITICAL"
                notes: "White ants discovered in main depot area"
      
      observation_notes:
        slot_uri: dcterms:description
        description: |
          Free-text notes documenting the observation.
          
          Include:
          - What was observed
          - Context of the observation
          - Specific concerns or findings
          - Recommendations if any
        range: string
        examples:
          - value: >-
              During routine inspection, white ant damage discovered in south
              wall of main document storage. Approximately 50 linear meters
              of shelving affected. Evidence of active infestation - live
              insects observed. Immediate treatment recommended.
      
      evidence_documentation:
        slot_uri: prov:wasInfluencedBy
        description: |
          Links to supporting evidence for this observation.
          
          May include:
          - Photographs of conditions
          - Published articles (for journalism)
          - Official inspection reports
          - Sensor data exports
          - Video documentation
          
          PROV-O: wasInfluencedBy for supporting sources.
        range: uriorcurie
        multivalued: true
        examples:
          - value:
              - "https://www.volkskrant.nl/archive-pest-investigation-2024"
              - "https://archive.org/evidence/photos/depot-damage-20240915.zip"
      
      measurement_data:
        slot_uri: schema:value
        description: |
          Structured measurement data from sensors or instruments.
          
          JSON-LD compatible structure for environmental readings:
          - temperature_celsius
          - humidity_percent
          - lux_level
          - particulate_count
          - etc.
        range: string
        examples:
          - value: '{"temperature_celsius": 23.5, "humidity_percent": 58, "threshold_exceeded": true}'
      
      compliance_status:
        slot_uri: dcterms:conformsTo
        description: |
          Compliance status with referenced standards.
          
          Values: COMPLIANT, NON_COMPLIANT, PARTIALLY_COMPLIANT, NOT_ASSESSED
          
          Dublin Core: conformsTo for standards compliance.
        range: string
        examples:
          - value: "NON_COMPLIANT"
            description: "Does not meet EN 16893:2018 requirements"
      
      remediation_required:
        slot_uri: schema:potentialAction
        description: |
          Whether remediation action is required based on this observation.
          
          TRUE = Issues found that require corrective action.
          FALSE = No immediate action needed.
        range: boolean
        examples:
          - value: true
            description: "Pest treatment required immediately"
      
      remediation_notes:
        slot_uri: schema:description
        description: |
          Notes on required or recommended remediation actions.
        range: string
        examples:
          - value: >-
              1. Engage licensed pest control immediately
              2. Quarantine affected materials
              3. Survey adjacent storage areas
              4. Install additional monitoring traps
              5. Report to Heritage Inspectorate within 48 hours
      
      follow_up_date:
        slot_uri: schema:scheduledTime
        description: |
          Scheduled date for follow-up assessment.
          
          May be set for:
          - Verification of remediation
          - Regular monitoring cycle
          - Compliance re-inspection
        range: date
        examples:
          - value: "2024-12-01"
            description: "Post-treatment verification inspection"
      
      confidence_score:
        slot_uri: prov:value
        description: |
          Confidence score (0.0-1.0) in the accuracy of this observation.
          
          Factors affecting confidence:
          - Observer expertise (professionals higher)
          - Access level (full access higher)
          - Evidence quality (documentation higher)
          - Measurement calibration (verified higher)
        range: float
        minimum_value: 0.0
        maximum_value: 1.0
        examples:
          - value: 0.95
            description: "Government inspector with full access"
          - value: 0.75
            description: "Journalist with limited access"
      
      supersedes:
        slot_uri: prov:wasRevisionOf
        description: |
          Previous condition observation that this one supersedes or updates.
          
          Use when a new observation corrects or updates a previous one
          from the same observer type.
          
          PROV-O: wasRevisionOf for updated versions.
        range: StorageCondition
        examples:
          - value: "https://nde.nl/ontology/hc/condition/rijksmuseum-depot-2024-q1"
    
    comments:
      - "Observations are NOT assertions of truth - they are reports from specific observers"
      - "Multiple observations may exist for same storage with conflicting findings"
      - "Gap between observed conditions and policy conditions is critical transparency metric"
      - "External observations (journalists, researchers) may reveal unreported issues"
      - "Official assessments vs external investigations treated equally as data"
      - "Automated system observations provide objective measurements but require calibration"
    
    see_also:
      - "http://www.w3.org/ns/prov#Activity"
      - "https://www.loc.gov/premis/rdf/v3/Event"
    
    examples:
      - value:
          condition_id: "https://nde.nl/ontology/hc/condition/depot-pest-investigation-2024"
          refers_to_storage: "https://nde.nl/ontology/hc/storage/national-archive-depot-b"
          observation_date: "2024-09-15"
          observer_type: "JOURNALIST"
          observer_name: "Jan de Vries"
          observer_affiliation: "De Volkskrant"
          is_official_assessment: false
          overall_status: "CRITICAL"
          category_assessments:
            - category: "PEST_CONTROL"
              status: "CRITICAL"
              notes: "White ants discovered in main document depot"
          observation_notes: >-
            Investigative visit revealed active termite infestation in south
            section of Document Depot B. Approximately 50 linear meters of
            historical documents at risk. Institution was unaware of extent
            of damage until contacted for comment.
          evidence_documentation:
            - "https://www.volkskrant.nl/archive-pest-crisis-2024"
          remediation_required: true
          confidence_score: 0.85
        description: "Journalist investigation discovering unreported pest infestation"
      
      - value:
          condition_id: "https://nde.nl/ontology/hc/condition/rijksmuseum-q2-2024"
          refers_to_storage: "https://nde.nl/ontology/hc/storage/rijksmuseum-depot-amersfoort"
          observation_date: "2024-06-30"
          observation_period:
            start_date: "2024-04-01"
            end_date: "2024-06-30"
          observer_type: "INTERNAL_STAFF"
          observer_name: "Collections Management Team"
          observer_affiliation: "Rijksmuseum"
          is_official_assessment: true
          overall_status: "GOOD"
          category_assessments:
            - category: "TEMPERATURE"
              status: "EXCELLENT"
              measurement: "18.5°C average"
            - category: "HUMIDITY"
              status: "GOOD"
              measurement: "48% RH average"
            - category: "PEST_CONTROL"
              status: "GOOD"
              notes: "No pest activity detected in monitoring traps"
            - category: "SECURITY"
              status: "EXCELLENT"
          observation_notes: "Quarterly facilities review. All parameters within policy ranges."
          compliance_status: "COMPLIANT"
          remediation_required: false
          confidence_score: 0.90
        description: "Official quarterly internal assessment"

  # Helper class for category-level assessments
  StorageConditionCategoryAssessment:
    class_uri: hc:StorageConditionCategoryAssessment
    description: |
      Individual category assessment within a StorageCondition observation.
      
      Allows granular reporting of different condition categories with
      independent status levels.
    
    slots:
      - assessment_category
      - category_status
      - category_measurement
      - category_notes
    
    slot_usage:
      assessment_category:
        slot_uri: dcterms:type
        description: Category being assessed (from StorageConditionCategoryEnum)
        range: string
        required: true
      
      category_status:
        slot_uri: premis:hasOutcome
        description: Status for this specific category
        range: StorageConditionStatusEnum
        required: true
      
      category_measurement:
        slot_uri: schema:value
        description: Measurement value if applicable (e.g., "19.5°C", "48% RH")
        range: string
      
      category_notes:
        slot_uri: dcterms:description
        description: Notes specific to this category assessment
        range: string

# Slot definitions
slots:
  condition_id:
    description: Unique identifier for condition observation
    range: uriorcurie
  
  refers_to_storage:
    description: Storage facility being assessed
    range: Storage
  
  # NOTE: observation_date imported from global slot ../slots/observation_date.yaml
  
  observation_period:
    description: Time period covered by observation
    range: TimeSpan
  
  observer_type:
    description: Type of observer (from enum)
    range: StorageObserverTypeEnum
  
  observer_name:
    description: Name of observer
    range: string
  
  observer_affiliation:
    description: Observer's organizational affiliation
    range: string
  
  is_official_assessment:
    description: Whether this is an official institutional assessment
    range: boolean
  
  overall_status:
    description: Overall condition status
    range: StorageConditionStatusEnum
  
  category_assessments:
    description: Individual category assessments
    range: StorageConditionCategoryAssessment
    multivalued: true
  
  observation_notes:
    description: Free-text observation notes
    range: string
  
  evidence_documentation:
    description: Links to supporting evidence
    range: uriorcurie
    multivalued: true
  
  measurement_data:
    description: Structured measurement data
    range: string
  
  compliance_status:
    description: Compliance status with standards
    range: string
  
  remediation_required:
    description: Whether remediation is required
    range: boolean
  
  remediation_notes:
    description: Notes on required remediation
    range: string
  
  follow_up_date:
    description: Scheduled follow-up date
    range: date
  
  # NOTE: confidence_score imported from global slot ../slots/confidence_score.yaml
  
  # Category assessment slots
  assessment_category:
    description: Category being assessed
    range: string
  
  category_status:
    description: Status for this category
    range: StorageConditionStatusEnum
  
  category_measurement:
    description: Measurement value for category
    range: string
  
  category_notes:
    description: Notes for this category
    range: string