# 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/