kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/AUXILIARY_CLASSES_COMPLETE.md

8 KiB
Raw Blame History

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

gen-json-schema schemas/20251121/linkml/01_custodian_name_modular.yaml
# Output: 6,005 lines JSON schema

RDF Generation: ✅ PASSED

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