- 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.
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):
person_name.yaml- Full name (schema:name)staff_role.yaml- Role category (schema:roleName)role_title.yaml- Job title (schema:jobTitle)unit_affiliation.yaml- Organizational unit (schema:affiliation)role_start_date.yaml- Employment start (schema:startDate)role_end_date.yaml- Employment end (schema:endDate)observation_source.yaml- Already existed (reused)affected_by_event.yaml- Organizational change impact (prov:wasInfluencedBy)contact_email.yaml- Contact info (schema:email)expertise_areas.yaml- Professional specializations (schema:knowsAbout)
OrganizationalStructure Slot (1 file):
staff_members.yaml- Unit → staff relationship (org:hasMember)
All slots include:
- Ontology mappings: Explicit
slot_urito 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:
- Added
staff_membersto slots list (line ~67) - Added comprehensive
slot_usagedocumentation (100+ lines afterstaff_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
-
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
-
schemas/20251121/linkml/modules/classes/OrganizationalStructure.yaml- Added
staff_membersslot - Added 100+ lines of slot_usage documentation
- Added
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:hasMember ↔ org:memberOf (inverse properties)
Rationale:
- Enables queries from both directions:
- "Who works here?" (
OrganizationalStructure.staff_members) - "Where does this person work?" (
PersonObservation.unit_affiliation)
- "Who works here?" (
- 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:
-
Rule 1:
role_start_date >= unit_affiliation.valid_from- Staff cannot work for a unit before it exists
-
Rule 2:
role_end_date <= unit_affiliation.valid_to(if unit dissolved)- Staff cannot work for a dissolved unit
-
Rule 3:
affected_by_event.event_datealigns 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:
PersonObservation→OrganizationalStructure(viaunit_affiliation)OrganizationalStructure→PersonObservation(viastaff_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:
PersonObservation→OrganizationalChangeEvent(viaaffected_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:
PersonObservation→CustodianCollection(potentialmanaged_collectionsslot)
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:
-
Temporal Integrity:
role_start_date < role_end_date(if end date exists)role_start_date >= unit_affiliation.valid_fromrole_end_date <= unit_affiliation.valid_to(if unit dissolved)
-
Organizational Change Alignment:
- If
affected_by_eventpresent, check:role_end_date==event_date(old role ends)role_start_date==event_date(new role starts)
- If
-
Required Fields:
id,person_name,staff_role,unit_affiliationpresentobservation_sourcereferences valid SourceDocument
-
Data Quality:
- Email format validation (if
contact_emailpresent) expertise_areasnot empty listrole_titlenot empty string
- Email format validation (if
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:
- Staffing reports (headcount by role, by unit)
- Expertise location (find specialists)
- Reorganization impact (staff affected by events)
- Contact directories (email lookup by role/unit)
- 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
- Website: https://personsincontext.org/
- GitHub: https://github.com/FICLIT/PiCo
- Paper: "Persons in Context: A Model for Representing Historical Person Data" (2020)
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
Related Ontologies
- W3C ORG: https://www.w3.org/TR/vocab-org/
org:hasMember,org:memberOf(staff-unit relationships)
- Schema.org: https://schema.org/
schema:Person,schema:Role,schema:name,schema:jobTitle,schema:email
- CIDOC-CRM: http://www.cidoc-crm.org/
crm:E21_Person(person as cultural heritage actor)
- PROV-O: https://www.w3.org/TR/prov-o/
prov:Agent,prov:wasInfluencedBy(organizational change impact)
- FOAF: http://xmlns.com/foaf/spec/
foaf:Person(person in social network)
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