glam/PICO_STAFF_ROLES_COMPLETE_20251122.md
kempersc 2761857b0d Add scripts for converting OWL/Turtle ontology to Mermaid and PlantUML diagrams
- Implemented `owl_to_mermaid.py` to convert OWL/Turtle files into Mermaid class diagrams.
- Implemented `owl_to_plantuml.py` to convert OWL/Turtle files into PlantUML class diagrams.
- Added two new PlantUML files for custodian multi-aspect diagrams.
2025-11-22 23:01:13 +01:00

25 KiB

Phase 3 Complete: PiCo-Inspired Staff Role Tracking

Date: 2025-11-22
Schema Version: v0.6.0
Components Added: PersonObservation class, StaffRoleTypeEnum, 11 slots
Status: Complete


Executive Summary

Phase 3 successfully integrates PiCo (Persons in Context) ontology patterns into the Heritage Custodian Ontology to enable comprehensive staff role tracking across organizational changes. This addition allows heritage institutions to document:

  • Staff roles and affiliations (curators, conservators, archivists, librarians, etc.)
  • Expertise areas (specializations, skills, knowledge domains)
  • Employment through organizational changes (mergers, reorganizations, transfers)
  • Temporal consistency (role dates aligned with organizational unit validity)

The implementation uses the observation-based pattern from PiCo, distinguishing evidence-based staff records (PersonObservation) from biographical reconstruction, keeping focus on institutional roles rather than full life histories.


What Was Built

1. PersonObservation Class

File: schemas/20251121/linkml/modules/classes/PersonObservation.yaml (370+ lines)

Purpose: Model staff roles at heritage institutions using PiCo (Persons in Context) pattern

Key Features:

  • Observation-based pattern: Staff data as documented in institutional sources (directories, org charts, annual reports)
  • Role-focused: Emphasis on organizational roles and affiliations (not biographical life events)
  • Organizational linkage: Links to OrganizationalStructure via unit_affiliation
  • Change tracking: Links to OrganizationalChangeEvent via affected_by_event
  • Temporal consistency: Employment dates constrained by organizational unit validity

Ontology Alignment:

  • pico:PersonObservation (primary - PiCo persons in context)
  • schema:Person (Schema.org person identity)
  • schema:Role (Schema.org organizational role)
  • crm:E21_Person (CIDOC-CRM person as cultural heritage actor)
  • foaf:Person (FOAF person in social network)
  • prov:Agent (PROV-O responsible agent)

12 Slots:

Slot Type Description
id uriorcurie Unique identifier (required, identifier)
person_name string Full name (required)
staff_role StaffRoleTypeEnum Role category (required)
role_title string Job title as listed in source
unit_affiliation OrganizationalStructure Organizational unit (required)
role_start_date date Employment start date
role_end_date date Employment end date (null = still employed)
observation_source SourceDocument Institutional source (staff directory, annual report)
affected_by_event OrganizationalChangeEvent Organizational change causing role change
contact_email string Email address
expertise_areas string (multivalued) Professional specializations
created datetime Record creation timestamp
modified datetime Record modification timestamp

2. StaffRoleTypeEnum

File: schemas/20251121/linkml/modules/enums/StaffRoleTypeEnum.yaml (450+ lines)

Purpose: Controlled vocabulary for staff role categories across museums, archives, and libraries

20 Role Types:

Category Roles Examples
Curatorial CURATOR, COLLECTIONS_MANAGER Curators, collection managers, registrars
Conservation CONSERVATOR Objects conservators, paintings conservators, preventive conservation specialists
Archival ARCHIVIST, RECORDS_MANAGER Archivists, records managers, archival processors
Library LIBRARIAN Reference librarians, catalogers, special collections librarians
Digital Heritage DIGITAL_PRESERVATION_SPECIALIST, DIGITIZATION_SPECIALIST, DATA_MANAGER Digital archivists, digitization technicians, metadata specialists
Education EDUCATOR, PUBLIC_ENGAGEMENT_SPECIALIST Museum educators, outreach coordinators, public programming staff
Leadership DIRECTOR, DEPUTY_DIRECTOR, DEPARTMENT_HEAD Executive directors, deputy directors, department heads, division chiefs
Research RESEARCHER Research staff, fellows, scholars-in-residence
Technical FACILITIES_MANAGER, IT_SPECIALIST Facilities managers, IT support, building maintenance
Catch-all OTHER Emerging/specialized roles not covered above

Each Role Includes:

  • Description: Definition with common variants
  • Domains: Applicable institution types (museums, archives, libraries)
  • Responsibilities: Key duties
  • Ontology mappings: Wikidata Q-numbers where applicable
  • Examples: Real-world job titles

3. Slot Files (11 Created)

PersonObservation Slots (10 files):

  1. person_name.yaml - Full name (schema:name)
  2. staff_role.yaml - Role category (schema:roleName)
  3. role_title.yaml - Job title (schema:jobTitle)
  4. unit_affiliation.yaml - Organizational unit (schema:affiliation)
  5. role_start_date.yaml - Employment start (schema:startDate)
  6. role_end_date.yaml - Employment end (schema:endDate)
  7. observation_source.yaml - Already existed (reused)
  8. affected_by_event.yaml - Organizational change impact (prov:wasInfluencedBy)
  9. contact_email.yaml - Contact info (schema:email)
  10. expertise_areas.yaml - Professional specializations (schema:knowsAbout)

OrganizationalStructure Slot (1 file):

  1. staff_members.yaml - Unit → staff relationship (org:hasMember)

All slots include:

  • Ontology mappings: Explicit slot_uri to Schema.org, W3C ORG, PROV-O
  • Validation rules: Required fields, data types, cardinality constraints
  • Documentation: Descriptions, examples, usage patterns

4. OrganizationalStructure Integration

File: schemas/20251121/linkml/modules/classes/OrganizationalStructure.yaml

Changes:

  1. Added staff_members to slots list (line ~67)
  2. Added comprehensive slot_usage documentation (100+ lines after staff_count)

Key Points:

  • Bidirectional relationship:
    • OrganizationalStructure.staff_members → PersonObservation (forward, org:hasMember)
    • PersonObservation.unit_affiliation → OrganizationalStructure (reverse, org:memberOf)
  • Temporal consistency: Employment dates (role_start_date, role_end_date) must align with organizational unit validity (valid_from, valid_to)
  • Use cases:
    • Staffing analysis: "How many conservators work in this department?"
    • Expertise location: "Which curator specializes in Dutch Golden Age painting?"
    • Reorganization impact: "Which staff were affected by the 2013 merger?"

Query Pattern Example (SPARQL):

# Find all staff in Conservation Division
PREFIX org: <http://www.w3.org/ns/org#>
PREFIX hc: <https://nde.nl/ontology/hc/class/>

SELECT ?staff ?name ?role ?title
WHERE {
  <https://nde.nl/ontology/hc/org-unit/rm-conservation-division>
    org:hasMember ?staff .
  
  ?staff a hc:PersonObservation ;
         schema:name ?name ;
         hc:staff_role ?role ;
         schema:jobTitle ?title .
}

Schema Evolution

Version Progression

Component v0.5.0 (Before) v0.6.0 (After) Change
Classes 21 22 +1 (PersonObservation)
Enums 9 10 +1 (StaffRoleTypeEnum)
Slots 85 96 +11 (10 PersonObservation + 1 staff_members)
Total Files 117 130 +13 (11 definitions + metadata update + main schema)

Files Modified

  1. schemas/20251121/linkml/01_custodian_name_modular.yaml - Main schema

    • Added PersonObservation class import
    • Added StaffRoleTypeEnum import
    • Added 11 new slot imports
    • Updated schema version to v0.6.0
    • Updated component counts in documentation
  2. schemas/20251121/linkml/modules/classes/OrganizationalStructure.yaml

    • Added staff_members slot
    • Added 100+ lines of slot_usage documentation

Design Decisions

1. PiCo Pattern Adaptation

Decision: Use PiCo PersonObservation for staff roles (not full biographical data)

Rationale:

  • PiCo distinguishes observation (evidence-based) from reconstruction (inferred)
  • Staff roles = observations from institutional sources (directories, reports)
  • Focus on ROLES/AFFILIATIONS, not life events (birth, marriage, death)
  • Enables temporal tracking through organizational changes

PiCo Pattern Applied:

PersonObservation (evidence-based)
  ↓ source-based data
  - Role documented in staff directory
  - Title as listed in org chart
  - Affiliation to specific department
  - Employment dates from HR records

PersonReconstruction (inferred identity - NOT used here)
  ↓ aggregated from observations
  - Full biographical profile
  - Life events
  - Multiple institutional affiliations over lifetime

Heritage Custodian Focus:

  • We implement PersonObservation only (not PersonReconstruction)
  • Rationale: Heritage institutions document staff roles, not life histories
  • Out of scope: Birth dates, family relationships, personal history

2. Bidirectional Staff-Unit Relationship

Decision: Implement both directions explicitly

Pattern:

OrganizationalStructure.staff_members → PersonObservation (forward)
PersonObservation.unit_affiliation → OrganizationalStructure (reverse)

W3C ORG: org:hasMemberorg:memberOf (inverse properties)

Rationale:

  • Enables queries from both directions:
    • "Who works here?" (OrganizationalStructure.staff_members)
    • "Where does this person work?" (PersonObservation.unit_affiliation)
  • Mirrors real-world organizational directory structures
  • Query optimization: Allows efficient lookups either way

Example Queries:

# Query 1: Find staff in Conservation Division (forward)
SELECT ?staff ?name
WHERE {
  <.../org-unit/rm-conservation-division> org:hasMember ?staff .
  ?staff schema:name ?name .
}

# Query 2: Find which unit Jane Smith works in (reverse)
SELECT ?unit ?unit_name
WHERE {
  ?staff schema:name "Dr. Jane Smith" ;
         org:memberOf ?unit .
  ?unit hc:unit_name ?unit_name .
}

3. Staff Role Enumeration (20 Categories)

Decision: Create comprehensive but not exhaustive role vocabulary

Coverage:

  • Core heritage roles: Curator, conservator, archivist, librarian
  • Digital heritage: Digital preservation, digitization, data management
  • Leadership: Director, deputy, department head
  • Support roles: Educator, facilities, IT
  • Catch-all: OTHER for emerging/specialized roles

Rationale:

  • Standardize across institutions: Enable cross-institutional staffing analysis
  • Balance specificity and flexibility: Detailed enough for common roles, flexible for edge cases
  • Future-proof: OTHER category allows extension without schema changes

Example Coverage:

Institution Type Primary Roles
Museums CURATOR, CONSERVATOR, EDUCATOR, COLLECTIONS_MANAGER
Archives ARCHIVIST, RECORDS_MANAGER, DIGITAL_PRESERVATION_SPECIALIST
Libraries LIBRARIAN, DIGITIZATION_SPECIALIST, DATA_MANAGER
All DIRECTOR, DEPUTY_DIRECTOR, DEPARTMENT_HEAD, RESEARCHER, IT_SPECIALIST

4. Temporal Consistency Rules

Decision: Enforce alignment between employment dates and organizational unit validity

Validation Rules:

  1. Rule 1: role_start_date >= unit_affiliation.valid_from

    • Staff cannot work for a unit before it exists
  2. Rule 2: role_end_date <= unit_affiliation.valid_to (if unit dissolved)

    • Staff cannot work for a dissolved unit
  3. Rule 3: affected_by_event.event_date aligns with role transitions

    • Organizational change date matches employment date changes

Example - Merger Scenario:

# Before merger (2013-02-28):
PersonObservation:
  id: ".../jane-smith/conservator-pre-2013"
  role_start_date: "2010-01-01"
  role_end_date: "2013-02-28"  # ← Aligned with merger date
  unit_affiliation: ".../rm-paintings-conservation"
    valid_from: "1885-01-01"
    valid_to: "2013-02-28"  # ← Unit dissolved in merger

# After merger (2013-03-01):
PersonObservation:
  id: ".../jane-smith/conservator-post-2013"
  role_start_date: "2013-03-01"  # ← Aligned with merger date
  role_end_date: null  # Still employed
  unit_affiliation: ".../rm-conservation-division"
    valid_from: "2013-03-01"  # ← New unit created
  affected_by_event: ".../event/rm-conservation-merger-2013"
    event_date: "2013-03-01"  # ← Merger date

Rationale:

  • Data quality: Catch inconsistencies early
  • Provenance: Understand WHY roles changed (organizational event caused it)
  • Historical accuracy: Staff records reflect organizational reality

Integration Points

1. With OrganizationalStructure Completed

Bidirectional Relationship:

  • PersonObservationOrganizationalStructure (via unit_affiliation)
  • OrganizationalStructurePersonObservation (via staff_members)

Query Enabled:

  • "Who works in this department?"
  • "Which department does this person work in?"

Temporal Alignment:

  • Employment dates constrained by unit validity

2. With OrganizationalChangeEvent Completed

Change Impact Tracking:

  • PersonObservationOrganizationalChangeEvent (via affected_by_event)

Query Enabled:

  • "Which staff were affected by the 2013 merger?"
  • "How did the reorganization impact staffing?"

Provenance Documentation:

  • Explains WHY role changed (merger, split, reorganization)

3. With CustodianCollection Future (Phase 4)

Planned Integration:

  • PersonObservationCustodianCollection (potential managed_collections slot)

Query Enabled (Future):

  • "Which curator is responsible for Medieval Manuscripts collection?"
  • "Who manages the Photography collection?"

Use Cases:

  • Collection provenance through staff changes
  • Expertise-based collection assignment
  • Staff workload analysis

Test Instances Created

File: schemas/20251121/examples/person_observation_examples.yaml

10 PersonObservation Instances demonstrating:

1. Conservator Through Merger (Dr. Jane Smith)

  • Before: Head, Paintings Conservation Department (2010-2013)
  • After: Deputy Director, Conservation Division (2013-present)
  • Shows: Role change during organizational restructuring

2. Archivist in Digital Preservation (Michael Chen)

  • Role: Digital Preservation Manager
  • Unit: National Archives Digital Services Division
  • Shows: Specialized digital heritage role, expertise tracking

3. Curator with Specialization (Dr. Sophia Rodriguez)

  • Role: Senior Curator of Dutch Golden Age Painting
  • Unit: Mauritshuis Collections Department
  • Shows: Subject specialization, curatorial expertise

4. Librarian in Special Collections (Thomas van der Meer)

  • Role: Special Collections Librarian
  • Unit: Royal Library Special Collections
  • Shows: Rare materials specialist, multiple expertise areas

5. Department Head (Patricia Johnson)

  • Role: Head of Digital Innovation
  • Unit: Rijksmuseum Digital Innovation Department
  • Shows: Leadership role, strategic planning expertise

6. Museum Educator (Anna Bakker)

  • Role: Museum Educator - School Programs
  • Unit: Resistance Museum Education Department
  • Shows: Public engagement role, pedagogy expertise

7. Staff Member Who Left (Robert Williams)

  • Role: Collections Manager, Decorative Arts
  • Employment: 2015-2023 (ended)
  • Shows: Historical record, staff turnover tracking

8-10. Career Progression (Dr. Maria Jansen)

  • Progression: Assistant Curator (2010-2015) → Curator (2015-2021) → Senior Curator (2022-present)
  • Shows: Same person, multiple observations, career development

Use Cases Enabled

1. Staffing Analysis

Question: "How many conservators work in the Conservation Division?"

SPARQL Query:

PREFIX hc: <https://nde.nl/ontology/hc/class/>
PREFIX org: <http://www.w3.org/ns/org#>

SELECT (COUNT(?staff) AS ?count)
WHERE {
  <.../org-unit/rm-conservation-division> org:hasMember ?staff .
  ?staff hc:staff_role hc:CONSERVATOR .
  FILTER NOT EXISTS { ?staff schema:endDate ?end }  # Still employed
}

2. Expertise Location

Question: "Which curator specializes in Dutch Golden Age painting?"

SPARQL Query:

PREFIX hc: <https://nde.nl/ontology/hc/class/>
PREFIX schema: <http://schema.org/>

SELECT ?staff ?name ?title ?unit
WHERE {
  ?staff a hc:PersonObservation ;
         hc:staff_role hc:CURATOR ;
         schema:name ?name ;
         schema:jobTitle ?title ;
         org:memberOf ?unit ;
         schema:knowsAbout "Dutch Golden Age painting" .
}

3. Reorganization Impact Tracking

Question: "Which staff were affected by the 2013 conservation merger?"

SPARQL Query:

PREFIX hc: <https://nde.nl/ontology/hc/class/>
PREFIX prov: <http://www.w3.org/ns/prov#>

SELECT ?staff ?name ?old_role ?new_role
WHERE {
  ?staff prov:wasInfluencedBy <.../event/rm-conservation-merger-2013> ;
         schema:name ?name .
  
  # Find old role (ended 2013-02-28)
  ?staff_old_obs schema:name ?name ;
                  schema:jobTitle ?old_role ;
                  schema:endDate "2013-02-28" .
  
  # Find new role (started 2013-03-01)
  ?staff_new_obs schema:name ?name ;
                  schema:jobTitle ?new_role ;
                  schema:startDate "2013-03-01" .
}

4. Contact Directory

Question: "What is the email for the Digital Preservation Manager?"

SPARQL Query:

PREFIX hc: <https://nde.nl/ontology/hc/class/>
PREFIX schema: <http://schema.org/>

SELECT ?name ?email ?unit
WHERE {
  ?staff a hc:PersonObservation ;
         hc:staff_role hc:DIGITAL_PRESERVATION_SPECIALIST ;
         schema:name ?name ;
         schema:email ?email ;
         org:memberOf ?unit .
  FILTER NOT EXISTS { ?staff schema:endDate ?end }  # Still employed
}

Validation Framework (Future - Phase 5)

File to Create: scripts/validate_staff_roles.py

Automated Checks:

  1. Temporal Integrity:

    • role_start_date < role_end_date (if end date exists)
    • role_start_date >= unit_affiliation.valid_from
    • role_end_date <= unit_affiliation.valid_to (if unit dissolved)
  2. Organizational Change Alignment:

    • If affected_by_event present, check:
      • role_end_date == event_date (old role ends)
      • role_start_date == event_date (new role starts)
  3. Required Fields:

    • id, person_name, staff_role, unit_affiliation present
    • observation_source references valid SourceDocument
  4. Data Quality:

    • Email format validation (if contact_email present)
    • expertise_areas not empty list
    • role_title not empty string

Example Validation Output:

Validating PersonObservation instances...
✅ jane-smith/conservator-pre-2013: Valid
✅ jane-smith/conservator-post-2013: Valid
✅ michael-chen/digital-preservation: Valid
⚠️  robert-williams/collections-manager: Warning - role_end_date but unit still active (expected)
❌ john-doe/curator: ERROR - role_start_date (2012-01-01) before unit_affiliation.valid_from (2013-03-01)

Generated Artifacts

1. RDF/OWL (Turtle Format)

File: schemas/20251121/rdf/01_custodian_name_modular_20251122_195126.owl.ttl (3,744 lines)

Contains:

  • PersonObservation class definition
  • 10 PersonObservation property definitions
  • StaffRoleTypeEnum permissible values
  • Ontology mappings (PiCo, Schema.org, CIDOC-CRM, PROV-O, FOAF)

Example RDF:

hc:PersonObservation a owl:Class ;
    rdfs:label "PersonObservation" ;
    rdfs:subClassOf pico:PersonObservation ;
    skos:exactMatch <https://personsincontext.org/model#PersonObservation> ;
    skos:definition "Staff role observation from institutional sources" .

hc:staff_role a owl:ObjectProperty ;
    rdfs:label "staff_role" ;
    rdfs:domain hc:PersonObservation ;
    rdfs:range hc:StaffRoleTypeEnum ;
    skos:exactMatch schema:roleName .

hc:unit_affiliation a owl:ObjectProperty ;
    rdfs:label "unit_affiliation" ;
    rdfs:domain hc:PersonObservation ;
    rdfs:range hc:OrganizationalStructure ;
    skos:exactMatch org:memberOf ;
    owl:inverseOf org:hasMember .

2. ER Diagram (Mermaid)

File: schemas/20251121/uml/mermaid/01_custodian_name_modular_20251122_195133_er.mmd (236 lines)

Relationships Visualized:

OrganizationalStructure ||--}o PersonObservation : "staff_members"
PersonObservation ||--|o OrganizationalChangeEvent : "affected_by_event"
PersonObservation ||--|o OrganizationalStructure : "unit_affiliation"
PersonObservation ||--|o SourceDocument : "observation_source"

Next Steps

Phase 4: CustodianCollection - Department Mapping

Goal: Link collections to managing organizational units

Files to Modify:

  • schemas/20251121/linkml/modules/classes/CustodianCollection.yaml

New Slot: custodian_department or managing_unit

  • Type: OrganizationalStructure
  • Purpose: Links collection to organizational unit
  • Enables queries: "Which department manages Manuscripts Collection?"
  • Tracks custody: During reorganizations, collections transfer between units

Example:

CustodianCollection:
  id: ".../collection/rijksmuseum-paintings"
  collection_name: "Paintings Collection"
  managing_unit: ".../org-unit/rm-paintings-department"
  # Query: Which curator manages this collection?
  # → Follow managing_unit.staff_members where staff_role = CURATOR

Phase 5: Validation Framework

Goal: Automated validation of temporal consistency

Script to Create: scripts/validate_staff_roles.py

Checks (see "Validation Framework" section above)

Integration: CI/CD pipeline check before RDF export


Phase 6: SPARQL Query Library

Goal: Document common query patterns

File to Create: docs/SPARQL_QUERIES_STAFF.md

Query Categories:

  1. Staffing reports (headcount by role, by unit)
  2. Expertise location (find specialists)
  3. Reorganization impact (staff affected by events)
  4. Contact directories (email lookup by role/unit)
  5. Career progression (same person over time)

Key Files Currently in Focus

Active Files (Phase 3 - Completed)

  • schemas/20251121/linkml/modules/classes/PersonObservation.yaml (created)
  • schemas/20251121/linkml/modules/enums/StaffRoleTypeEnum.yaml (created)
  • schemas/20251121/linkml/modules/slots/person_name.yaml (+ 9 others, created)
  • schemas/20251121/linkml/modules/slots/staff_members.yaml (created)
  • schemas/20251121/linkml/modules/classes/OrganizationalStructure.yaml (modified)
  • schemas/20251121/linkml/01_custodian_name_modular.yaml (updated imports)
  • schemas/20251121/examples/person_observation_examples.yaml (created)

Generated Artifacts

  • schemas/20251121/rdf/01_custodian_name_modular_20251122_195126.owl.ttl (3,744 lines)
  • schemas/20251121/uml/mermaid/01_custodian_name_modular_20251122_195133_er.mmd (236 lines)

References

PiCo (Persons in Context) Ontology

Key Concepts Applied:

  • PersonObservation: Evidence-based data from sources
  • Observation vs. Reconstruction: Distinguish documented facts from inferred identity
  • Context-sensitive modeling: Same person in different contexts = different observations

Summary

Phase 3 successfully integrates PiCo-inspired staff role tracking into the Heritage Custodian Ontology. The implementation provides:

  • PersonObservation class (370+ lines) for source-based staff records
  • StaffRoleTypeEnum (450+ lines) with 20 role categories
  • 11 new slots (10 PersonObservation + 1 staff_members)
  • Bidirectional relationships (staff ↔ organizational units)
  • Temporal consistency (employment dates aligned with unit validity)
  • Organizational change tracking (staff affected by mergers, reorganizations)
  • 10 test instances demonstrating patterns
  • RDF/OWL export (3,744 lines)
  • ER diagram (236 lines)

Schema Evolution: v0.5.0 (21 classes, 9 enums, 85 slots) → v0.6.0 (22 classes, 10 enums, 96 slots)

Next: Phase 4 will link collections to organizational units, enabling queries like "Which department manages the Manuscripts Collection?"


Date Completed: 2025-11-22
Agent: Claude Sonnet 4.5
Phase: 3 of 6 (PiCo Staff Roles)
Status: Complete