glam/ENCOMPASSING_BODY_IMPLEMENTATION_COMPLETE.md

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

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

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

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:

# 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

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

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

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