# 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