3ff0e33bf9
- Created PlantUML diagrams for custodian types, full schema, legal status, and organizational structure. - Implemented a script to generate GraphViz DOT diagrams from OWL/RDF ontology files. - Developed a script to generate UML diagrams from modular LinkML schema, supporting both Mermaid and PlantUML formats. - Enhanced class definitions and relationships in UML diagrams to reflect the latest schema updates.
417 lines
14 KiB
Markdown
417 lines
14 KiB
Markdown
# EncompassingBody Implementation Complete
|
|
|
|
**Date**: 2025-11-23
|
|
**Status**: ✅ COMPLETE
|
|
**Purpose**: Model extra-organizational governance relationships for heritage custodians
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The **EncompassingBody** class hierarchy models organizations that encompass, oversee, or coordinate heritage custodian institutions. This extends governance modeling **beyond** internal organizational structure (OrganizationalStructure) and legal entity governance (GovernanceStructure) to capture **external parent-child and membership relationships**.
|
|
|
|
---
|
|
|
|
## Three Types of Encompassing Bodies
|
|
|
|
### 1. UmbrellaOrganisation (Legal Parent)
|
|
|
|
**Characteristics**:
|
|
- **PERMANENT** hierarchical legal structure
|
|
- Defined in articles of association, statutes, or legislation
|
|
- Strong governance authority (budgets, appointments, policy)
|
|
- Legal subordination relationship
|
|
|
|
**Examples**:
|
|
- Ministry of OCW → National Archives (Dutch Heritage Act)
|
|
- Gemeente Amsterdam → Amsterdam Museum (municipal oversight)
|
|
- Universiteit Leiden → Leiden University Library (university charter)
|
|
- Franciscan Order → Monastery archives (religious constitution)
|
|
|
|
**Ontology**: `org:FormalOrganization` (W3C ORG)
|
|
|
|
---
|
|
|
|
### 2. NetworkOrganisation (Service Provider)
|
|
|
|
**Characteristics**:
|
|
- **TEMPORARY** agreements for centralized services
|
|
- Voluntary membership (join for service benefits)
|
|
- Limited authority (coordinates services, no governance)
|
|
- Service-oriented (infrastructure, training, coordination)
|
|
|
|
**Examples**:
|
|
- Digital Heritage Network (digital preservation storage)
|
|
- DPLA (metadata aggregation)
|
|
- Europeana (digitization aggregation)
|
|
- Regional conservation lab networks
|
|
|
|
**Ontology**: `schema:Organization` (Schema.org)
|
|
|
|
---
|
|
|
|
### 3. Consortium (Mutual Assistance)
|
|
|
|
**Characteristics**:
|
|
- **TEMPORARY** peer-to-peer collaboration
|
|
- Mutual assistance (members help each other)
|
|
- Minimal authority (coordination only)
|
|
- Reciprocal services (not centralized provider)
|
|
|
|
**Examples**:
|
|
- UKB Consortium (Dutch university libraries - shared cataloging)
|
|
- Interlibrary loan consortia (reciprocal borrowing)
|
|
- Bulk licensing consortia (collective negotiations)
|
|
- Amsterdam Museums Consortium (joint marketing)
|
|
|
|
**Ontology**: `schema:Consortium` (Schema.org)
|
|
|
|
---
|
|
|
|
## Key Distinctions
|
|
|
|
### EncompassingBody vs. GovernanceStructure
|
|
|
|
| Aspect | EncompassingBody | GovernanceStructure |
|
|
|--------|------------------|---------------------|
|
|
| **Scope** | EXTERNAL parent organizations | INTERNAL legal structure |
|
|
| **Location** | On Custodian class | On CustodianLegalStatus class |
|
|
| **Example** | Ministry → National Archives | Board of Trustees (internal) |
|
|
| **Relationship** | Beyond custodian entity | Within legal entity |
|
|
|
|
### EncompassingBody vs. OrganizationalStructure
|
|
|
|
| Aspect | EncompassingBody | OrganizationalStructure |
|
|
|--------|------------------|-------------------------|
|
|
| **Scope** | EXTERNAL umbrella/networks | INTERNAL operational units |
|
|
| **Location** | On Custodian class | On Custodian class |
|
|
| **Example** | Digital Heritage Network | Digital Preservation Department |
|
|
| **Relationship** | Between organizations | Within organization |
|
|
|
|
### NetworkOrganisation vs. Consortium
|
|
|
|
| Aspect | NetworkOrganisation | Consortium |
|
|
|--------|---------------------|------------|
|
|
| **Service Model** | Centralized provider | Peer-to-peer mutual assistance |
|
|
| **Direction** | Network → Members | Members ↔ Members |
|
|
| **Example** | DPLA provides aggregation | Libraries lend to each other |
|
|
| **Authority** | Service standards | Coordination only |
|
|
|
|
---
|
|
|
|
## Schema Files Created
|
|
|
|
1. **Class Definition**: `/schemas/20251121/linkml/modules/classes/EncompassingBody.yaml`
|
|
- EncompassingBody (abstract parent)
|
|
- UmbrellaOrganisation (legal parent)
|
|
- NetworkOrganisation (service provider)
|
|
- Consortium (mutual assistance)
|
|
|
|
2. **Enumeration**: `/schemas/20251121/linkml/modules/enums/EncompassingBodyTypeEnum.yaml`
|
|
- UMBRELLA (legal hierarchy)
|
|
- NETWORK (service provision)
|
|
- CONSORTIUM (peer collaboration)
|
|
|
|
3. **Slot Definition**: `/schemas/20251121/linkml/modules/slots/encompassing_body.yaml`
|
|
- `encompassing_body` slot with `org:subOrganizationOf` property
|
|
|
|
4. **Examples**: `/schemas/20251121/linkml/modules/examples/encompassing_body_examples.yaml`
|
|
- National Archives with Ministry umbrella
|
|
- Amsterdam Museum with multiple encompassing bodies
|
|
- Leiden University Library with university + consortium
|
|
- Regional archive with provincial umbrella
|
|
- Monastery archive with religious order umbrella
|
|
|
|
5. **Custodian Class Updated**: `/schemas/20251121/linkml/modules/classes/Custodian.yaml`
|
|
- Added `encompassing_body` slot to slots list
|
|
- Added comprehensive slot_usage documentation with examples
|
|
|
|
---
|
|
|
|
## Ontological Mappings
|
|
|
|
### EncompassingBody (Abstract)
|
|
- **Primary**: `org:Organization` (W3C ORG)
|
|
- **Close**: `tooi:Samenwerkingsorganisatie` (TOOI), `schema:Organization`, `cpov:PublicOrganisation`
|
|
|
|
### UmbrellaOrganisation
|
|
- **Primary**: `org:FormalOrganization` (W3C ORG)
|
|
- **Close**: `tooi:Ministerie`, `cpov:PublicOrganisation`, `schema:GovernmentOrganization`
|
|
|
|
### NetworkOrganisation
|
|
- **Primary**: `schema:Organization` (Schema.org)
|
|
- **Close**: `tooi:Samenwerkingsorganisatie`, `org:Organization`
|
|
|
|
### Consortium
|
|
- **Primary**: `schema:Consortium` (Schema.org)
|
|
- **Close**: `tooi:Samenwerkingsorganisatie`, `org:Organization`
|
|
|
|
### Relationship Property
|
|
- **Primary**: `org:subOrganizationOf` (Custodian → EncompassingBody)
|
|
- **Inverse**: `org:hasSubOrganization` (EncompassingBody → Custodian)
|
|
- **Close**: `schema:parentOrganization`, `schema:memberOf`
|
|
|
|
---
|
|
|
|
## Properties and Slots
|
|
|
|
### Core Properties (All EncompassingBody Types)
|
|
|
|
- `id` (required) - Unique URI identifier
|
|
- `organization_name` (required) - Official name (SKOS prefLabel)
|
|
- `organization_type` (required) - UMBRELLA | NETWORK | CONSORTIUM
|
|
- `description` - Textual description of role and scope
|
|
- `legal_form` - Legal entity type (ministry, foundation, etc.)
|
|
- `founding_date` - Establishment date
|
|
- `dissolution_date` - Dissolution date (if applicable)
|
|
- `member_custodians` - Custodians governed/coordinated by this body
|
|
- `identifiers` - External IDs (Wikidata, VIAF, etc.)
|
|
- `website` - Official website
|
|
|
|
### Type-Specific Properties
|
|
|
|
**UmbrellaOrganisation** (required):
|
|
- `governance_authority` - Legal basis and governance powers
|
|
|
|
**NetworkOrganisation** (required):
|
|
- `service_offerings` - Services provided to members
|
|
- `membership_criteria` - Eligibility and fees
|
|
|
|
**Consortium** (required):
|
|
- `service_offerings` - Peer-to-peer services (mutual assistance)
|
|
- `membership_criteria` - Participation requirements
|
|
|
|
---
|
|
|
|
## Usage Patterns
|
|
|
|
### Single Umbrella Organization
|
|
|
|
```yaml
|
|
custodian:
|
|
hc_id: "https://nde.nl/ontology/hc/nl-na"
|
|
preferred_label: "Nationaal Archief"
|
|
encompassing_body:
|
|
- id: ".../umbrella/nl-ministry-ocw"
|
|
organization_type: "UMBRELLA"
|
|
governance_authority: "Heritage Act 2016"
|
|
```
|
|
|
|
### Multiple Encompassing Bodies
|
|
|
|
```yaml
|
|
custodian:
|
|
hc_id: "https://nde.nl/ontology/hc/nl-nh-ams-m-am"
|
|
preferred_label: "Amsterdam Museum"
|
|
encompassing_body:
|
|
- id: ".../umbrella/nl-municipality-amsterdam"
|
|
organization_type: "UMBRELLA"
|
|
- id: ".../network/digital-heritage-nl"
|
|
organization_type: "NETWORK"
|
|
- id: ".../consortium/amsterdam-museums-consortium"
|
|
organization_type: "CONSORTIUM"
|
|
```
|
|
|
|
### Peer Collaboration Consortium
|
|
|
|
```yaml
|
|
encompassing_body:
|
|
id: ".../consortium/dutch-univ-lib-consortium"
|
|
organization_name: "UKB Consortium"
|
|
organization_type: "CONSORTIUM"
|
|
service_offerings:
|
|
- "Shared union catalog"
|
|
- "Bulk licensing negotiations"
|
|
- "Reciprocal interlibrary loan"
|
|
member_custodians:
|
|
- hc_id: ".../nl-zh-lei-l-ub"
|
|
- hc_id: ".../nl-ut-utr-l-ub"
|
|
- hc_id: ".../nl-nh-ams-l-uba"
|
|
```
|
|
|
|
---
|
|
|
|
## Temporal Dynamics
|
|
|
|
Custodians can change umbrella organizations, join/leave networks, or participate in multiple consortia over time.
|
|
|
|
**Track Changes**:
|
|
- `founding_date` / `dissolution_date` on EncompassingBody
|
|
- Temporal validity tracked via EncompassingBody instances
|
|
- Changes recorded in organizational change events (future enhancement)
|
|
|
|
**Example - Network Membership Change**:
|
|
```yaml
|
|
# 2015-2020: Member of old network
|
|
encompassing_body:
|
|
- id: ".../network/old-network"
|
|
dissolution_date: "2020-12-31"
|
|
|
|
# 2021-present: Member of new network
|
|
encompassing_body:
|
|
- id: ".../network/new-network"
|
|
founding_date: "2021-01-01"
|
|
```
|
|
|
|
---
|
|
|
|
## SPARQL Query Examples
|
|
|
|
### Find All Custodians Under a Ministry
|
|
|
|
```sparql
|
|
PREFIX org: <http://www.w3.org/ns/org#>
|
|
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
|
|
PREFIX hc: <https://nde.nl/ontology/hc/class/>
|
|
|
|
SELECT ?custodian_name ?custodian_type WHERE {
|
|
?custodian org:subOrganizationOf <.../ministry-ocw> ;
|
|
skos:prefLabel ?custodian_name ;
|
|
hc:custodian_type ?custodian_type .
|
|
}
|
|
```
|
|
|
|
### Find All Networks a Custodian Belongs To
|
|
|
|
```sparql
|
|
SELECT ?network_name ?services WHERE {
|
|
<.../custodian/amsterdam-museum> org:subOrganizationOf ?network .
|
|
?network a hc:NetworkOrganisation ;
|
|
skos:prefLabel ?network_name ;
|
|
hc:service_offerings ?services .
|
|
}
|
|
```
|
|
|
|
### Find All Consortia with Reciprocal Interlibrary Loan
|
|
|
|
```sparql
|
|
SELECT ?consortium_name ?member_count WHERE {
|
|
?consortium a hc:Consortium ;
|
|
skos:prefLabel ?consortium_name ;
|
|
hc:service_offerings ?service .
|
|
FILTER(CONTAINS(?service, "interlibrary loan"))
|
|
|
|
{
|
|
SELECT ?consortium (COUNT(?member) AS ?member_count) WHERE {
|
|
?consortium org:hasSubOrganization ?member .
|
|
}
|
|
GROUP BY ?consortium
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Integration with Existing Classes
|
|
|
|
### Custodian Hub Class
|
|
|
|
EncompassingBody connects to Custodian via `encompassing_body` slot:
|
|
- Custodians can have 0 or more encompassing bodies
|
|
- Typical patterns: 1 umbrella + multiple networks/consortia
|
|
- Slot is multivalued and uses `org:subOrganizationOf` property
|
|
|
|
### CustodianLegalStatus
|
|
|
|
**Complementary, not overlapping**:
|
|
- **CustodianLegalStatus.governance_structure**: INTERNAL legal structure (board, trustees)
|
|
- **Custodian.encompassing_body**: EXTERNAL parent organizations
|
|
|
|
### OrganizationalStructure
|
|
|
|
**Complementary, not overlapping**:
|
|
- **OrganizationalStructure**: INTERNAL operational units (departments, teams)
|
|
- **EncompassingBody**: EXTERNAL organizations custodian is part of
|
|
|
|
---
|
|
|
|
## Data Quality Considerations
|
|
|
|
### High-Quality Data Includes
|
|
|
|
1. **Temporal Validity**: Founding/dissolution dates for encompassing bodies
|
|
2. **Governance Documentation**: Legal basis for UmbrellaOrganisations
|
|
3. **Service Descriptions**: Detailed service offerings for Networks/Consortia
|
|
4. **External Identifiers**: Wikidata IDs for encompassing organizations
|
|
5. **Membership Criteria**: Clear eligibility requirements
|
|
|
|
### Common Data Gaps
|
|
|
|
- Missing service descriptions for networks
|
|
- Unclear distinction between network and consortium
|
|
- Temporal validity not tracked (membership start/end dates)
|
|
- Governance authority not documented for umbrella organizations
|
|
|
|
---
|
|
|
|
## Design Decisions
|
|
|
|
### Why Three Types?
|
|
|
|
Three types reflect **fundamentally different governance models**:
|
|
1. **Legal hierarchy** (permanent, strong authority)
|
|
2. **Service provision** (temporary, centralized, limited authority)
|
|
3. **Peer collaboration** (temporary, distributed, minimal authority)
|
|
|
|
### Why Not More Types?
|
|
|
|
Additional categories considered but rejected:
|
|
- **Funding bodies**: Captured via provenance metadata, not governance
|
|
- **Professional associations**: Use Consortium if peer-to-peer, Network if service provider
|
|
- **Regulatory bodies**: Use UmbrellaOrganisation if legal authority exists
|
|
|
|
### Why on Custodian, Not CustodianLegalStatus?
|
|
|
|
EncompassingBody relationships affect the **entire custodian** (all aspects: place, collection, legal, name), not just the legal entity. Example: Religious order (umbrella) governs monastery archive (custodian) including its place (monastery building), collection (manuscripts), legal status (foundation), and name (emic identity).
|
|
|
|
---
|
|
|
|
## Next Steps (Future Enhancements)
|
|
|
|
1. **Temporal Tracking**: Add `membership_start_date` / `membership_end_date` to track when custodians join/leave networks
|
|
2. **Event Integration**: Link EncompassingBody changes to OrganizationalChangeEvent (e.g., "transferred to new ministry")
|
|
3. **Service Contracts**: Model service agreements for NetworkOrganisations (SLAs, pricing tiers)
|
|
4. **Governance Roles**: Model specific roles within umbrella organizations (e.g., "ministry appoints director")
|
|
5. **Network Topology**: Visualize multi-level governance hierarchies (ministry → agency → branch archive)
|
|
|
|
---
|
|
|
|
## Files Modified/Created
|
|
|
|
**Modified**:
|
|
- `/schemas/20251121/linkml/modules/classes/Custodian.yaml` (added encompassing_body slot)
|
|
|
|
**Created**:
|
|
- `/schemas/20251121/linkml/modules/classes/EncompassingBody.yaml`
|
|
- `/schemas/20251121/linkml/modules/enums/EncompassingBodyTypeEnum.yaml`
|
|
- `/schemas/20251121/linkml/modules/slots/encompassing_body.yaml`
|
|
- `/schemas/20251121/linkml/modules/examples/encompassing_body_examples.yaml`
|
|
- `ENCOMPASSING_BODY_IMPLEMENTATION_COMPLETE.md` (this file)
|
|
|
|
---
|
|
|
|
## Line Count Summary
|
|
|
|
| File | Lines |
|
|
|------|-------|
|
|
| EncompassingBody.yaml | 570 |
|
|
| EncompassingBodyTypeEnum.yaml | 120 |
|
|
| encompassing_body slot | 50 |
|
|
| encompassing_body_examples.yaml | 520 |
|
|
| Custodian.yaml (additions) | 140 |
|
|
| **TOTAL** | **1,400 lines** |
|
|
|
|
---
|
|
|
|
## Ontology Alignment Summary
|
|
|
|
✅ **W3C ORG Ontology**: Primary alignment for organizational relationships
|
|
✅ **TOOI Ontology**: Dutch government and collaborative organizations
|
|
✅ **Schema.org**: Consortium and organization types
|
|
✅ **CPOV**: EU public sector organizations
|
|
✅ **FOAF**: General agent/organization concepts
|
|
|
|
---
|
|
|
|
**Implementation Status**: ✅ COMPLETE
|
|
**Next Agent Handoff**: EncompassingBody class system fully implemented and ready for use
|