glam/schemas/20251121/linkml/modules/classes/ReconstructionActivity.yaml

# Heritage Custodian Reconstruction Activity Class
# Documents the entity resolution process that creates CustodianLegalStatus

id: https://nde.nl/ontology/hc/class/ReconstructionActivity
name: reconstruction-activity-class
title: ReconstructionActivity Class

imports:
  - linkml:types
  - ../metadata
  - ../enums/ReconstructionActivityTypeEnum
  - ReconstructionAgent
  - TimeSpan
  - CustodianObservation
  - ConfidenceMeasure

classes:
  
  ReconstructionActivity:
    class_uri: prov:Activity
    description: >-
      An activity that creates a CustodianLegalStatus by reconciling and 
      resolving multiple CustodianObservations into a single entity.
      
      This documents:
      - Entity resolution method (manual curation, algorithmic matching, etc.)
      - Responsible agent (person, custodian, software)
      - Temporal extent (start/end dates)
      - Provenance and justification      
    exact_mappings:
      - prov:Activity
    close_mappings:
      - rico:Activity
      - crm:E7_Activity
      - schema:Action
    related_mappings:
      - crm:E13_Attribute_Assignment
    
    slots:
      - id
      - activity_type
      - method
      - responsible_agent
      - temporal_extent
      - used
      - confidence_score
      - justification
    
    slot_usage:
      activity_type:
        slot_uri: prov:Activity
        description: >-
          Type of reconstruction activity (manual, algorithmic, hybrid, expert review).
          PROV-O: Activity type classification.          
        range: ReconstructionActivityTypeEnum
      method:
        slot_uri: dcterms:description
        description: >-
          Detailed method description for entity resolution.
          Dublin Core: description for methodology documentation.          
        range: string
      responsible_agent:
        slot_uri: prov:wasAssociatedWith
        description: >-
          ReconstructionAgent responsible for reconstruction (REQUIRED).
          PROV-O: wasAssociatedWith links Activity to responsible ReconstructionAgent.          
        range: ReconstructionAgent
      temporal_extent:
        slot_uri: crm:P4_has_time-span
        description: >-
          Temporal extent of reconstruction activity (start/end times with fuzzy boundaries).
          CIDOC-CRM: P4_has_time-span links Activity to TimeSpan.
          PROV-O: Maps to combination of prov:startedAtTime and prov:endedAtTime.
          
          For precise timestamps:
          - Set begin_of_the_begin == end_of_the_begin (activity start)
          - Set begin_of_the_end == end_of_the_end (activity end)
          
          For activities with uncertain duration, use fuzzy boundaries:
          - begin_of_the_begin: Earliest possible start
          - end_of_the_begin: Latest possible start
          - begin_of_the_end: Earliest possible end
          - end_of_the_end: Latest possible end          
        range: TimeSpan
        exact_mappings:
          - crm:P4_has_time-span
        related_mappings:
          - prov:startedAtTime
          - prov:endedAtTime
      used:
        slot_uri: prov:used
        description: >-
          CustodianObservation(s) used as input for this reconstruction activity (REQUIRED).
          
          PROV-O Pattern: Activity prov:used Entity
          - Multiple observations can contribute to a single reconstruction
          - Observations are INPUT entities consumed by the activity
          - Activity may generate CustodianLegalStatus (success) OR CustodianName (partial) OR nothing (failure)
          
          This is the PRIMARY input link in the observation→reconstruction flow.          
        range: CustodianObservation
        multivalued: true
        required: true
      confidence_score:
        slot_uri: prov:confidence
        description: >-
          Confidence in the reconstruction activity's PROCESS and methodology.
          
          CRITICAL: Measures quality of the PROCESS, not the result!
          - High confidence = Strong methodology, reliable sources, clear evidence
          - Low confidence = Weak matching, ambiguous sources, uncertain reconciliation
          
          Range: 0.0 (low confidence) to 1.0 (high confidence)
          
          PROV-O Extension: prov:confidence for activity quality assessment.          
        range: ConfidenceMeasure
        required: false
      justification:
        slot_uri: prov:qualifiedAttribution
        description: >-
          Justification for entity resolution decisions.
          PROV-O: qualifiedAttribution for detailed provenance rationale.          
        range: string
    
    comments:
      - "Documents the 'how' (method) and 'who' (responsible_agent) of entity resolution and reconstruction"
      - "Enables provenance tracking for data quality assessment and citation purposes"
      - "Example methods: manual expert curation, algorithmic fuzzy matching, hybrid semi-automated with human review"
      - "Uses TimeSpan for temporal_extent to support fuzzy temporal boundaries and CIDOC-CRM alignment"
      - "For precise timestamps (common in automated activities), set TimeSpan boundaries to identical values"
    see_also:
      - "https://www.w3.org/TR/prov-o/#Activity"
      - "https://github.com/FICLIT/PiCo"
      - "https://cidoc-crm.org/html/cidoc_crm_v7.1.3.html#P4"
    
    examples:
      - value:
          id: "https://w3id.org/heritage/custodian/activity/reconstruction-001"
          activity_type: MANUAL_CURATION
          method: "Expert historian reviewed 15 archival sources to reconcile conflicting references to 'Stedelijk Museum' in Amsterdam"
          responsible_agent:
            id: "https://w3id.org/heritage/custodian/agent/curator-jdoe"
            agent_type: PERSON
            name: "Jane Doe"
          temporal_extent:
            begin_of_the_begin: "2025-01-15T09:00:00Z"
            end_of_the_begin: "2025-01-15T09:00:00Z"
            begin_of_the_end: "2025-01-15T17:30:00Z"
            end_of_the_end: "2025-01-15T17:30:00Z"
          used_sources:
            - "https://archief.amsterdam/nl/inventaris/433.php"
            - "https://www.wikidata.org/wiki/Q621531"
          justification: "Name variations 'Stedelijk Museum Amsterdam' and 'Stedelijk Museum' confirmed as same institution via ISIL code NL-AsdSM"
        description: "Manual curation activity with precise timestamps"
      - value:
          id: "https://w3id.org/heritage/custodian/activity/reconstruction-002"
          activity_type: ALGORITHMIC_MATCHING
          method: "Fuzzy string matching algorithm (Levenshtein distance threshold 0.85) applied to 1,200 ISIL registry entries"
          responsible_agent:
            id: "https://w3id.org/heritage/custodian/agent/dedupe-v2.1"
            agent_type: SOFTWARE
            name: "Heritage Deduplication Tool v2.1"
          temporal_extent:
            begin_of_the_begin: "2025-01-20T02:00:00Z"
            end_of_the_begin: "2025-01-20T02:00:00Z"
            begin_of_the_end: "2025-01-20T02:15:00Z"
            end_of_the_end: "2025-01-20T02:15:00Z"
          used_sources:
            - "https://isil.org/NL"
          justification: "Automated matching with high confidence scores (>0.90) for 85% of entities"
        description: "Algorithmic reconstruction with precise automated timestamps"