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

id: https://nde.nl/ontology/hc/class/PersonObservation
name: PersonObservation
title: Person Observation (Staff Role Context)

imports:
  - linkml:types

classes:
  PersonObservation:
    class_uri: pico:PersonObservation
    description: >-
      An observation of a person serving in a staff role at a heritage custodian institution,
      as documented in a specific source at a specific point in time.
      
      **PiCo Pattern Adaptation**:
      The PiCo (Persons in Context) ontology distinguishes between:
      - **PersonObservation**: Data about a person as found in a source (evidence-based)
      - **PersonReconstruction**: Aggregated identity from multiple observations (inferred)
      
      For heritage custodian staff tracking, we adapt this pattern:
      - **PersonObservation**: Staff role as documented in institutional sources
        (annual reports, org charts, staff directories, archival records)
      - Focus on ROLES and AFFILIATIONS rather than biographical details
      - Temporal validity tracks employment period in specific position
      
      **Key Distinction from General Person Data**:
      This class models INSTITUTIONAL ROLES, not complete biographical data:
      - Emphasis: Role, title, unit affiliation, employment dates
      - NOT: Full biographical reconstruction (birth, death, family, etc.)
      - Sources: Institutional records (not vital records, census, etc.)
      
      **Ontological Alignment**:
      - PiCo: `pico:PersonObservation` (primary - person data from sources)
      - Schema.org: `schema:Person` (for person identity)
      - Schema.org: `schema:Role` (for organizational role)
      - CIDOC-CRM: `crm:E21_Person` (person as cultural heritage actor)
      - PROV-O: `prov:Agent` (person as responsible agent)
      - FOAF: `foaf:Person` (person in social network)
      
      **Hub Architecture Integration**:
      - PersonObservation refers to OrganizationalStructure via `unit_affiliation`
      - OrganizationalStructure refers back via `staff_members` (bidirectional)
      - PersonObservation affected by OrganizationalChangeEvent via `affected_by_event`
      - Temporal alignment: employment dates vs. organizational unit validity
      
      **Use Cases**:
      1. **Staff directories**: Document current and historical staff roles
      2. **Organizational provenance**: Track who managed departments/collections
      3. **Workforce history**: Analyze staffing patterns over time
      4. **Expertise tracking**: Find conservators, curators by specialization
      5. **Reorganization impact**: Track staff transitions during structural changes
      
      **Example - Conservation Staff**:
      ```yaml
      PersonObservation:
        person_name: "Dr. Jane Smith"
        staff_role: CONSERVATOR
        role_title: "Senior Paintings Conservator"
        unit_affiliation: ".../org-unit/rm-conservation-division"
        role_start_date: "2013-03-01"
        role_end_date: null  # Still employed
        observation_source:
          source_type: "Staff directory"
          source_uri: "https://rijksmuseum.nl/staff/jane-smith"
          observation_date: "2024-11-22"
      ```
      
      **Example - Staff Through Organizational Change**:
      ```yaml
      # Before merger (2013-02-28)
      PersonObservation:
        person_name: "Dr. Jane Smith"
        staff_role: CONSERVATOR
        role_title: "Head, Paintings Conservation Department"
        unit_affiliation: ".../org-unit/rm-paintings-conservation"
        role_start_date: "2010-01-01"
        role_end_date: "2013-02-28"
      
      # After merger (2013-03-01)
      PersonObservation:
        person_name: "Dr. Jane Smith"
        staff_role: CONSERVATOR
        role_title: "Deputy Director, Conservation Division"
        unit_affiliation: ".../org-unit/rm-conservation-division"
        role_start_date: "2013-03-01"
        role_end_date: null
        affected_by_event: ".../event/rm-conservation-merger-2013"
      ```      
    exact_mappings:
      - pico:PersonObservation
    close_mappings:
      - schema:Person
      - schema:Role
      - crm:E21_Person
      - foaf:Person
      - prov:Agent
    slots:
      - id
      - person_name
      - staff_role
      - role_title
      - unit_affiliation
      - role_start_date
      - role_end_date
      - observation_source
      - affected_by_event
      - contact_email
      - expertise_areas
      - created
      - modified
    slot_usage:
      id:
        slot_uri: dcterms:identifier
        description: >-
          Unique identifier for this staff role observation.
          Format: https://nde.nl/ontology/hc/person-obs/{custodian-id}/{person-slug}/{role-slug}
          Example: https://nde.nl/ontology/hc/person-obs/nl-nh-ams-m-rm/jane-smith/conservator-2013          
        range: uriorcurie
        required: true
        identifier: true
        pattern: "^https://nde\\.nl/ontology/hc/person-obs/[a-z0-9-]+/[a-z0-9-]+/[a-z0-9-]+$"
      
      person_name:
        slot_uri: schema:name
        description: >-
          Full name of the person as recorded in institutional sources.
          
          **Schema.org**: `schema:name` for person's name
          
          **Format**: Use natural name order (Western: "Given Family", non-Western: as appropriate)
          
          **Normalization**: 
          - Include titles/honorifics if institutionally used ("Dr.", "Prof.")
          - Preserve name as it appears in organizational context
          - Use PNV (Person Name Vocabulary) for detailed name parsing (future extension)
          
          **Examples**:
          - "Dr. Jane Smith"
          - "Prof. dr. Willem van der Berg"
          - "Maria García Rodríguez"          
        range: string
        required: true
      
      staff_role:
        slot_uri: schema:roleName
        description: >-
          Primary staff role category from controlled vocabulary.
          
          **Schema.org**: `schema:roleName` for organizational role
          
          **Enumeration**: StaffRoleTypeEnum (curator, conservator, archivist, director, etc.)
          
          **Purpose**: Enable role-based queries ("Find all conservators")
          
          **Distinction from role_title**:
          - staff_role: CONSERVATOR (controlled category)
          - role_title: "Senior Paintings Conservator" (institutional job title)          
        range: StaffRoleTypeEnum
        required: true
      
      role_title:
        slot_uri: schema:jobTitle
        description: >-
          Official job title as used by the institution.
          
          **Schema.org**: `schema:jobTitle` for institutional title
          
          **Examples**:
          - "Head of Digital Preservation"
          - "Senior Curator of Medieval Art"
          - "Collections Manager"
          - "Deputy Director for Public Services"
          
          **Variability**: Job titles vary widely across institutions.
          Use staff_role for standardized categorization.          
        range: string
        required: false
      
      unit_affiliation:
        slot_uri: schema:affiliation
        description: >-
          Organizational unit (department/team) where person serves.
          
          **Schema.org**: `schema:affiliation` for organizational membership
          **W3C ORG**: Can map to `org:memberOf` (inverse of org:hasMember)
          
          **Reference**: Links to OrganizationalStructure.id
          
          **Temporal Alignment**:
          - Person's role_start_date should be >= unit's valid_from
          - Person's role_end_date should be <= unit's valid_to (if unit dissolved)
          
          **Example**: ".../org-unit/rm-conservation-division"
          
          **Rationale**: Staff roles exist within organizational context.
          Tracking unit affiliation enables:
          - Department staffing analysis ("How many staff in Conservation?")
          - Expertise location ("Which unit handles manuscript conservation?")
          - Reorganization impact ("Who moved to new Digital Services division?")          
        range: OrganizationalStructure
        required: false
      
      role_start_date:
        slot_uri: schema:startDate
        description: >-
          Date when person began serving in this role.
          
          **Schema.org**: `schema:startDate` for employment/membership start
          **PROV-O**: Can map to `prov:startedAtTime` for activity start
          
          **Format**: ISO 8601 date (YYYY-MM-DD)
          
          **Precision**:
          - Full date preferred: "2013-03-01"
          - Partial dates allowed: "2013-03" (month precision), "2013" (year precision)
          
          **Temporal Consistency**:
          - Must be >= unit_affiliation.valid_from (if unit reference exists)
          - Should align with organizational events if role started due to reorganization
          
          **Example**: "2013-03-01" (started on merger date)          
        range: date
        required: false
      
      role_end_date:
        slot_uri: schema:endDate
        description: >-
          Date when person ended service in this role (or null if still employed).
          
          **Schema.org**: `schema:endDate` for employment/membership end
          **PROV-O**: Can map to `prov:endedAtTime` for activity end
          
          **Format**: ISO 8601 date (YYYY-MM-DD) or null
          
          **Null Interpretation**: null = currently employed in this role
          
          **Temporal Consistency**:
          - Must be > role_start_date
          - Must be <= unit_affiliation.valid_to (if unit dissolved)
          
          **Reasons for End Date**:
          - Retirement
          - Role change (promotion, lateral move)
          - Organizational change (unit dissolved, merged)
          - Departure from institution
          
          **Example**: "2013-02-28" (ended before merger) or null (still employed)          
        range: date
        required: false
      
      observation_source:
        slot_uri: prov:hadPrimarySource
        description: >-
          Source where this staff role information was observed.
          
          **PiCo Pattern**: PersonObservation MUST link to source (evidence-based)
          **PROV-O**: `prov:hadPrimarySource` for provenance tracking
          
          **Source Types**:
          - Staff directory (online or print)
          - Organizational chart
          - Annual report
          - Institutional website
          - Archival personnel records
          - Publication credits
          - Email signature
          
          **Structure**: Reference to SourceDocument with:
          - source_type: "Staff directory", "Annual report", etc.
          - source_uri: URL if available
          - observation_date: When source was consulted
          
          **Data Quality**: Observation with documented source = higher confidence          
        range: SourceDocument
        required: false
      
      affected_by_event:
        slot_uri: prov:wasInfluencedBy
        description: >-
          Organizational change event that affected this person's role.
          
          **PROV-O**: `prov:wasInfluencedBy` for entity influenced by activity
          
          **Use Cases**:
          - Person promoted during reorganization
          - Person reassigned due to unit merger
          - Person's role changed after department split
          - Person retained position despite structural changes
          
          **Reference**: Links to OrganizationalChangeEvent.event_id
          
          **Temporal Alignment**:
          - If role_start_date = event_date: Role created by event
          - If role_end_date = event_date: Role ended by event
          
          **Example**: Person starts in new "Digital Services Division" on
          date of reorganization event that created the division.
          
          **Provenance**: Documents WHY role changed (organizational context)          
        range: OrganizationalChangeEvent
        required: false
      
      contact_email:
        slot_uri: schema:email
        description: >-
          Professional contact email (if publicly available).
          
          **Schema.org**: `schema:email` for contact information
          
          **Privacy**: Only include if email is publicly listed (staff directory, website)
          
          **Format**: Valid email address
          
          **Use Case**: Enable contact for research inquiries, collaborations          
        range: string
        required: false
        pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
      
      expertise_areas:
        slot_uri: schema:knowsAbout
        description: >-
          Areas of professional expertise or specialization.
          
          **Schema.org**: `schema:knowsAbout` for knowledge/expertise
          
          **Examples**:
          - Conservation: "18th-century paintings", "Paper conservation", "Preventive conservation"
          - Curatorial: "Dutch Golden Age", "Modern sculpture", "Decorative arts"
          - Archival: "Digital preservation", "Medieval manuscripts", "Corporate archives"
          - Library: "Rare books", "Metadata standards", "Linked open data"
          
          **Use Cases**:
          - Find expertise: "Who specializes in textile conservation?"
          - Research collaboration: "Curators working on contemporary art"
          - Collection management: "Match conservation specialists to objects"
          
          **Multivalued**: Person may have multiple expertise areas          
        range: string
        multivalued: true
        required: false
      
      created:
        slot_uri: schema:dateCreated
        description: >-
          Timestamp when this DATABASE RECORD was created.          
        range: datetime
      
      modified:
        slot_uri: schema:dateModified
        description: >-
          Timestamp when this DATABASE RECORD was last modified.          
        range: datetime
    
    comments:
      - "PiCo PersonObservation pattern adapted for institutional staff role tracking"
      - "Focus on ROLES and AFFILIATIONS within heritage organizations"
      - "NOT general biographical reconstruction (PiCo PersonReconstruction is separate concept)"
      - "Temporal validity enables tracking staff through organizational changes"
      - "Bidirectional links: staff → unit (unit_affiliation), unit → staff (staff_members)"
    
    examples:
      - value:
          id: "https://nde.nl/ontology/hc/person-obs/nl-nh-ams-m-rm/jane-smith/conservator-2013"
          person_name: "Dr. Jane Smith"
          staff_role: CONSERVATOR
          role_title: "Deputy Director, Conservation Division"
          unit_affiliation: "https://nde.nl/ontology/hc/org-unit/rm-conservation-division"
          role_start_date: "2013-03-01"
          role_end_date: null
          affected_by_event: "https://nde.nl/ontology/hc/event/rm-conservation-merger-2013"
        description: "Conservator promoted during department merger"