211 lines
8 KiB
Markdown
211 lines
8 KiB
Markdown
# Auxiliary Classes Implementation Complete
|
|
|
|
**Date**: 2025-11-26
|
|
**Status**: ✅ COMPLETE
|
|
**Schema Version**: 20251121 (modular)
|
|
|
|
## Summary
|
|
|
|
Successfully implemented three new auxiliary classes to model secondary physical locations and digital platforms for heritage custodians with complex organizational structures.
|
|
|
|
## New Classes Created
|
|
|
|
### 1. AuxiliaryPlace (W3C Org `org:Site` alignment)
|
|
|
|
**File**: `/schemas/20251121/linkml/modules/classes/AuxiliaryPlace.yaml`
|
|
**Lines**: ~575
|
|
|
|
Secondary physical locations for heritage custodians:
|
|
- Storage depots
|
|
- Branch offices
|
|
- Research centers
|
|
- Partner locations
|
|
- Public access points
|
|
|
|
**Key Features**:
|
|
- Links back to main place via `is_auxiliary_of`
|
|
- Can host formal branches via `hosts_branch`
|
|
- Tracks operational status (ACTIVE, HISTORICAL, PLANNED, etc.)
|
|
- Includes temporal extent for historical places
|
|
|
|
### 2. OrganizationBranch (W3C Org `org:OrganizationalUnit` alignment)
|
|
|
|
**File**: `/schemas/20251121/linkml/modules/classes/OrganizationBranch.yaml`
|
|
**Lines**: ~501
|
|
|
|
Formal organizational sub-units at physical locations:
|
|
- Branch libraries
|
|
- Conservation labs
|
|
- Research units
|
|
- Regional offices
|
|
- Special collections units
|
|
|
|
**Key Features**:
|
|
- Located at AuxiliaryPlace via `hosts_branch` relationship
|
|
- Reports to parent custodian via `reports_to`
|
|
- Distinct from OrganizationalStructure (formal units vs administrative departments)
|
|
- Tracks branch status (ACTIVE, CLOSED, MERGED, etc.)
|
|
|
|
### 3. AuxiliaryDigitalPlatform (DCAT `dcat:Catalog` alignment)
|
|
|
|
**File**: `/schemas/20251121/linkml/modules/classes/AuxiliaryDigitalPlatform.yaml`
|
|
**Lines**: ~615
|
|
|
|
Secondary digital platforms and project-specific websites:
|
|
- Exhibition microsites
|
|
- Mobile apps
|
|
- API endpoints
|
|
- Legacy systems
|
|
- Project websites
|
|
|
|
**Key Features**:
|
|
- Links to main platform via `is_auxiliary_of`
|
|
- Tracks platform lifecycle (ACTIVE, DEPRECATED, ARCHIVED)
|
|
- Records archival status for deprecated platforms
|
|
- Supports multiple URL types (homepage, API, IIIF endpoints)
|
|
|
|
## New Enumerations
|
|
|
|
| Enum File | Values | Purpose |
|
|
|-----------|--------|---------|
|
|
| `AuxiliaryPlaceTypeEnum.yaml` | BRANCH_OFFICE, STORAGE_FACILITY, RESEARCH_CENTER, PARTNER_LOCATION, PUBLIC_ACCESS_POINT, EXHIBITION_VENUE, EDUCATION_CENTER, ADMINISTRATIVE_OFFICE | Types of secondary physical locations |
|
|
| `OrganizationBranchTypeEnum.yaml` | REGIONAL_OFFICE, BRANCH_LIBRARY, SATELLITE_GALLERY, CONSERVATION_LAB, RESEARCH_UNIT, PUBLIC_ACCESS_POINT, SPECIAL_COLLECTIONS_UNIT | Types of formal organizational units |
|
|
| `AuxiliaryDigitalPlatformTypeEnum.yaml` | PROJECT_WEBSITE, EXHIBITION_MICROSITE, API_ENDPOINT, MOBILE_APP, DATA_REPOSITORY, SPECIALIZED_COLLECTION_PORTAL, IIIF_SERVICE, SOCIAL_MEDIA_PRESENCE, DIGITAL_ASSET_MANAGEMENT, LEGACY_SYSTEM | Types of secondary digital platforms |
|
|
|
|
## New Slot Modules
|
|
|
|
| Slot File | Slot Name | Domain → Range | Purpose |
|
|
|-----------|-----------|----------------|---------|
|
|
| `auxiliary_places.yaml` | auxiliary_places | CustodianPlace → AuxiliaryPlace[] | Link main place to secondary locations |
|
|
| `auxiliary_platforms.yaml` | auxiliary_platforms | DigitalPlatform → AuxiliaryDigitalPlatform[] | Link main platform to secondary platforms |
|
|
| `located_at.yaml` | located_at | OrganizationalStructure → AuxiliaryPlace[] | Optional physical location for departments |
|
|
|
|
## Updated Existing Classes
|
|
|
|
| Class | Changes |
|
|
|-------|---------|
|
|
| `CustodianPlace.yaml` | Added `auxiliary_places` slot with full slot_usage |
|
|
| `DigitalPlatform.yaml` | Added `auxiliary_platforms` slot with full slot_usage |
|
|
| `OrganizationalStructure.yaml` | Added `located_at` slot with full slot_usage |
|
|
|
|
## Architecture Pattern
|
|
|
|
```
|
|
Custodian (hub)
|
|
├── preferred_label → CustodianName
|
|
│ └── alternative_names → CustodianAppellation[]
|
|
│
|
|
├── place_designation → CustodianPlace (main place)
|
|
│ └── auxiliary_places → AuxiliaryPlace[] ← NEW
|
|
│ └── hosts_branch → OrganizationBranch ← NEW
|
|
│
|
|
├── digital_platform → DigitalPlatform (main platform)
|
|
│ └── auxiliary_platforms → AuxiliaryDigitalPlatform[] ← NEW
|
|
│
|
|
└── organizational_structure → OrganizationalStructure
|
|
└── located_at → AuxiliaryPlace (optional) ← NEW
|
|
```
|
|
|
|
## Validation Results
|
|
|
|
**Schema Validation**: ✅ PASSED
|
|
```bash
|
|
gen-json-schema schemas/20251121/linkml/01_custodian_name_modular.yaml
|
|
# Output: 6,005 lines JSON schema
|
|
```
|
|
|
|
**RDF Generation**: ✅ PASSED
|
|
```bash
|
|
TIMESTAMP=20251126_101032
|
|
gen-owl -f ttl → custodian_with_auxiliary_classes_${TIMESTAMP}.owl.ttl (15,399 lines)
|
|
rdfpipe → .nt (14,986 lines)
|
|
rdfpipe → .jsonld (68,822 lines)
|
|
```
|
|
|
|
## Example Instances
|
|
|
|
**File**: `/schemas/20251121/linkml/examples/auxiliary_classes_examples.yaml`
|
|
|
|
Four comprehensive use cases:
|
|
|
|
1. **Rijksmuseum** - Large museum with storage depot, research library, and multiple digital platforms (Rijksstudio, mobile app, API, exhibition microsites)
|
|
|
|
2. **OBA Amsterdam** - Multi-branch public library system with branch locations (some active, some historical/closed) and auxiliary digital platforms (e-books, youth portal)
|
|
|
|
3. **Noord-Hollands Archief** - Regional archive with study center, off-site depot, partner reading rooms, and multiple digital services (OAI-PMH, image viewer, legacy system)
|
|
|
|
4. **UvA Library** - University library with special collections, science park branch, and research infrastructure (digital collections, institutional repository, IIIF service)
|
|
|
|
## Key Design Decisions
|
|
|
|
### 1. Auxiliary vs. Main Distinction
|
|
- Main classes (CustodianPlace, DigitalPlatform) represent primary operational entry points
|
|
- Auxiliary classes represent secondary, supporting, or project-specific entities
|
|
- Clear parent-child relationships via `is_auxiliary_of` back-references
|
|
|
|
### 2. OrganizationBranch vs. OrganizationalStructure
|
|
- **OrganizationBranch**: Formal organizational units at specific physical locations (branch libraries, regional offices)
|
|
- **OrganizationalStructure**: Administrative departments/divisions that may span multiple locations or be purely administrative
|
|
|
|
### 3. Lifecycle Tracking
|
|
- All auxiliary classes include `temporal_extent` for historical tracking
|
|
- Status enums track operational state (ACTIVE, CLOSED, DEPRECATED, ARCHIVED)
|
|
- AuxiliaryDigitalPlatform includes `archival_status` for web archiving metadata
|
|
|
|
### 4. Ontology Alignment
|
|
- AuxiliaryPlace → `org:Site` (W3C Org)
|
|
- OrganizationBranch → `org:OrganizationalUnit` (W3C Org)
|
|
- AuxiliaryDigitalPlatform → `dcat:Catalog` (DCAT)
|
|
|
|
## Files Modified/Created
|
|
|
|
### New Files
|
|
```
|
|
schemas/20251121/linkml/modules/classes/
|
|
├── AuxiliaryPlace.yaml
|
|
├── OrganizationBranch.yaml
|
|
└── AuxiliaryDigitalPlatform.yaml
|
|
|
|
schemas/20251121/linkml/modules/enums/
|
|
├── AuxiliaryPlaceTypeEnum.yaml
|
|
├── OrganizationBranchTypeEnum.yaml
|
|
└── AuxiliaryDigitalPlatformTypeEnum.yaml
|
|
|
|
schemas/20251121/linkml/modules/slots/
|
|
├── auxiliary_places.yaml
|
|
├── auxiliary_platforms.yaml
|
|
└── located_at.yaml
|
|
|
|
schemas/20251121/linkml/examples/
|
|
└── auxiliary_classes_examples.yaml
|
|
|
|
schemas/20251121/rdf/
|
|
├── custodian_with_auxiliary_classes_20251126_101032.owl.ttl
|
|
├── custodian_with_auxiliary_classes_20251126_101032.nt
|
|
└── custodian_with_auxiliary_classes_20251126_101032.jsonld
|
|
```
|
|
|
|
### Modified Files
|
|
```
|
|
schemas/20251121/linkml/modules/classes/
|
|
├── CustodianPlace.yaml (added auxiliary_places slot)
|
|
├── DigitalPlatform.yaml (added auxiliary_platforms slot)
|
|
└── OrganizationalStructure.yaml (added located_at slot)
|
|
|
|
schemas/20251121/linkml/
|
|
└── 01_custodian_name_modular.yaml (added imports)
|
|
```
|
|
|
|
## Next Steps (Potential Future Work)
|
|
|
|
1. **Validate example instances** against schema using `linkml-validate`
|
|
2. **Generate Python dataclasses** from updated schema
|
|
3. **Create SHACL shapes** for data validation
|
|
4. **Update UML/Mermaid diagrams** to show new relationships
|
|
5. **Document migration path** for existing data to use new classes
|
|
|
|
## References
|
|
|
|
- W3C Organization Ontology: https://www.w3.org/TR/vocab-org/
|
|
- DCAT Vocabulary: https://www.w3.org/TR/vocab-dcat-3/
|
|
- LinkML Documentation: https://linkml.io/
|