kempersc 3ff0e33bf9 Add UML diagrams and scripts for custodian schema

- 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.

2025-11-23 23:05:33 +01:00

15 KiB

Raw Blame History

Legal Responsibility Collection Implementation - Complete

Date: 2025-11-22
Status: ✅ COMPLETE
Implementation Time: ~1 hour

🎯 Objective

Create a LegalResponsibilityCollection subclass of CustodianCollection that models the TOOI ontology pattern for informatieobjecten (information objects) under the legal responsibility of overheidsorganisaties (government organizations).

✅ Completed Tasks

1. Created LegalResponsibilityCollection Class ✅

File: schemas/20251121/linkml/modules/classes/LegalResponsibilityCollection.yaml

Key Features:

Subclass of: CustodianCollection (inherits all collection properties)
TOOI Alignment: class_uri: tooi:Informatieobject
Core Property: responsible_legal_entity → CustodianLegalStatus
Legal Basis Documentation: legal_responsibility_basis (statutory/regulatory/contractual foundation)
Temporal Tracking: legal_responsibility_start_date / legal_responsibility_end_date

Ontology Mappings:

Exact: tooi:Informatieobject, prov:Entity, dcat:Resource
Close: rico:RecordSet, crm:E78_Curated_Holding, bf:Collection

2. Created Bidirectional Relationship Slots ✅

Forward Relationship: `responsible_legal_entity`

File: schemas/20251121/linkml/modules/slots/responsible_legal_entity.yaml

Property: tooi:verantwoordelijke (TOOI: "responsible organization")
Range: CustodianLegalStatus
Inverse: collections_under_responsibility
Required: true

Reverse Relationship: `collections_under_responsibility`

File: schemas/20251121/linkml/modules/slots/collections_under_responsibility.yaml

Property: tooi:heeft_informatieobject (custom: "has information object")
Range: LegalResponsibilityCollection
Inverse: responsible_legal_entity
Multivalued: true
Required: false

3. Created Supporting Temporal Slots ✅

`legal_responsibility_basis`

File: schemas/20251121/linkml/modules/slots/legal_responsibility_basis.yaml

Property: dcterms:conformsTo
Purpose: Documents statutory/regulatory/contractual foundation for legal accountability
Examples: "Archiefwet 1995", "Erfgoedwet + Foundation statute"

`legal_responsibility_start_date`

File: schemas/20251121/linkml/modules/slots/legal_responsibility_start_date.yaml

Property: prov:generatedAtTime
Purpose: When legal responsibility began (may differ from collection creation date)

`legal_responsibility_end_date`

File: schemas/20251121/linkml/modules/slots/legal_responsibility_end_date.yaml

Property: prov:invalidatedAtTime
Purpose: When legal responsibility ended (custody transfer, deaccession, dissolution)

4. Updated Schema Structure ✅

Main Schema (`01_custodian_name_modular.yaml`)

✅ Added import: modules/classes/LegalResponsibilityCollection
✅ Added 5 slot imports:
- collections_under_responsibility
- responsible_legal_entity
- legal_responsibility_basis
- legal_responsibility_start_date
- legal_responsibility_end_date

CustodianLegalStatus Class

✅ Added slot: collections_under_responsibility
✅ Creates reverse link from legal entity to collections

Fixed CustodianCollection.yaml

✅ Resolved duplicate slot_usage keys (lines 46 and 80)
✅ Merged validation constraints with slot definitions
✅ Removed duplicate entries for:
- collection_name (line 176)
- managing_unit (line 102)
- valid_from (line 200)
- valid_to (line 208)

5. Updated UML Diagrams ✅

File: schemas/20251121/uml/mermaid/CustodianLegalStatus.md

Added relationship:

CustodianLegalStatus --> "*" LegalResponsibilityCollection : collections_under_responsibility

📐 Architecture Overview

TOOI Ontology Alignment

TOOI Pattern: tooi:Informatieobject + tooi:verantwoordelijke

# TOOI Definition
tooi:Informatieobject-verantwoordelijke a sh:PropertyShape ;
  sh:class tooi:Overheidsorganisatie ;
  sh:path tooi:verantwoordelijke ;
  skos:definition "Overheidsorganisatie die de wettelijke verantwoordelijkheid 
                   draagt voor de inhoud (strekking) van het informatieobject"@nl .

Heritage Custodian Implementation:

LegalResponsibilityCollection:
  is_a: CustodianCollection
  class_uri: tooi:Informatieobject
  
  slots:
    - responsible_legal_entity  # tooi:verantwoordelijke
    - legal_responsibility_basis
    - legal_responsibility_start_date
    - legal_responsibility_end_date
    # + all inherited CustodianCollection slots

Bidirectional Relationship

# Forward: Collection → Legal Entity
LegalResponsibilityCollection:
  responsible_legal_entity: ".../legal/nha-organization"

# Reverse: Legal Entity → Collections
CustodianLegalStatus:
  collections_under_responsibility:
    - ".../collection/nha-provincial-archive"
    - ".../collection/nha-haarlem-municipal"

🔗 Key Distinctions

LegalResponsibilityCollection vs. CustodianCollection

Aspect	LegalResponsibilityCollection	CustodianCollection (Parent)
Legal Accountability	Formal legal responsibility documented	May or may not have legal accountability
Use Case	Government archives, mandated collections	All heritage collections (including private)
Required Properties	`responsible_legal_entity`, `legal_responsibility_basis`	None beyond basic collection metadata
Ontology Mapping	`tooi:Informatieobject`	`crm:E78_Curated_Holding`
Example	National archive under Archiefwet 1995	Private collection donated to museum

responsible_legal_entity vs. managing_unit

Property	Level	Purpose	Range
responsible_legal_entity	Top-level	Legal accountability	`CustodianLegalStatus`
managing_unit	Operational	Day-to-day management	`OrganizationalStructure`

Example:

LegalResponsibilityCollection:
  # TOP LEVEL: Who is legally responsible?
  responsible_legal_entity: ".../legal/rijksmuseum-foundation"  # Stichting Rijksmuseum
  
  # OPERATIONAL: Which department manages it?
  managing_unit: ".../org-unit/rm-paintings-dept"  # Paintings Department

📝 Use Cases

1. Government Archive Collections

LegalResponsibilityCollection:
  id: "https://nde.nl/ontology/hc/collection/nha-provincial-archive"
  collection_name: "Noord-Hollands Archief - Provinciaal Archief"
  collection_type: ["archival_records"]
  
  # Legal responsibility
  responsible_legal_entity: "https://nde.nl/ontology/hc/legal/nha-organization"
  legal_responsibility_basis: >-
    Archiefwet 1995 (Dutch Archives Act), Article 41: 
    "De provincie draagt zorg voor de archiefbescheiden"    
  legal_responsibility_start_date: "2001-01-01"
  
  # Links to custodian hub
  refers_to_custodian: "https://nde.nl/ontology/hc/nl-nh-haa-a-nha"

2. Museum Collections Under Heritage Law

LegalResponsibilityCollection:
  id: "https://nde.nl/ontology/hc/collection/rm-national-collection"
  collection_name: "Rijksmuseum National Art Collection"
  collection_type: ["museum_objects"]
  
  responsible_legal_entity: "https://nde.nl/ontology/hc/legal/rijksmuseum-foundation"
  legal_responsibility_basis: >-
    Erfgoedwet (Heritage Act) 2016 + Stichting Rijksmuseum statute (1885)    
  legal_responsibility_start_date: "1885-07-01"
  
  refers_to_custodian: "https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804"

3. Custody Transfer (Before & After)

# BEFORE MERGER (2000)
LegalResponsibilityCollection:
  id: ".../collection/haarlem-municipal-pre-2001"
  collection_name: "Gemeentearchief Haarlem Municipal Records"
  
  responsible_legal_entity: ".../legal/haarlem-municipality-1990s"
  legal_responsibility_start_date: "1910-01-01"
  legal_responsibility_end_date: "2001-01-01"  # ← Custody ended
  
  custody_history:
    - transfer_date: "2001-01-01"
      from_entity: ".../legal/haarlem-municipality-1990s"
      to_entity: ".../legal/nha-organization"
      transfer_reason: "Merger of Gemeentearchief into NHA"

# AFTER MERGER (2001)
LegalResponsibilityCollection:
  id: ".../collection/haarlem-municipal-post-2001"
  collection_name: "Gemeentearchief Haarlem Municipal Records"
  
  responsible_legal_entity: ".../legal/nha-organization"  # ← New responsible entity
  legal_responsibility_start_date: "2001-01-01"
  
  refers_to_custodian: ".../nl-nh-haa-a-nha"  # Same custodian hub

🔍 SPARQL Query Examples

Find Collections Under Legal Responsibility

PREFIX tooi: <https://identifier.overheid.nl/tooi/def/ont/>
PREFIX hc: <https://nde.nl/ontology/hc/class/>

SELECT ?collection ?collection_name ?legal_basis
WHERE {
  <.../legal/nha-organization> 
    hc:collections_under_responsibility ?collection .
  
  ?collection hc:collection_name ?collection_name ;
              hc:legal_responsibility_basis ?legal_basis .
}

Find Legal Entity Responsible for Collection

PREFIX tooi: <https://identifier.overheid.nl/tooi/def/ont/>
PREFIX hc: <https://nde.nl/ontology/hc/class/>

SELECT ?legal_entity ?legal_name ?legal_form
WHERE {
  <.../collection/nha-provincial-archive> 
    tooi:verantwoordelijke ?legal_entity .
  
  ?legal_entity hc:legal_name/hc:full_name ?legal_name ;
                hc:legal_form/hc:local_name ?legal_form .
}

Track Custody Transfers Over Time

PREFIX hc: <https://nde.nl/ontology/hc/class/>
PREFIX prov: <http://www.w3.org/ns/prov#>

SELECT ?collection ?responsible_entity ?start_date ?end_date
WHERE {
  ?collection a hc:LegalResponsibilityCollection ;
              hc:responsible_legal_entity ?responsible_entity ;
              hc:legal_responsibility_start_date ?start_date .
  
  OPTIONAL { ?collection hc:legal_responsibility_end_date ?end_date }
}
ORDER BY ?collection ?start_date

📊 Files Created/Modified

New Files Created (5)

File	Purpose	Lines	Status
`modules/classes/LegalResponsibilityCollection.yaml`	Main class definition	500+	✅
`modules/slots/collections_under_responsibility.yaml`	Reverse relationship slot	200+	✅
`modules/slots/responsible_legal_entity.yaml`	Forward relationship slot	50+	✅
`modules/slots/legal_responsibility_basis.yaml`	Legal basis documentation	50+	✅
`modules/slots/legal_responsibility_start_date.yaml`	Temporal start slot	50+	✅
`modules/slots/legal_responsibility_end_date.yaml`	Temporal end slot	50+	✅

Modified Files (3)

File	Changes	Status
`01_custodian_name_modular.yaml`	Added 1 class import, 5 slot imports	✅
`modules/classes/CustodianLegalStatus.yaml`	Added `collections_under_responsibility` slot	✅
`modules/classes/CustodianCollection.yaml`	Fixed duplicate `slot_usage` keys	✅
`uml/mermaid/CustodianLegalStatus.md`	Added relationship diagram	✅

🎓 Implementation Insights

Why This Pattern Matters

Legal Compliance: Heritage institutions operate under statutory mandates (Archiefwet, Erfgoedwet, UNESCO conventions)
Custody Accountability: Clear documentation of which legal entity is responsible for collection preservation
Organizational Change Tracking: Mergers, splits, and transfers don't change collection physical identity but DO change legal responsibility
TOOI Alignment: Dutch government heritage data integrates with national interoperability standards

Temporal Dimension is Critical

Collections have THREE temporal dimensions:

Material Existence: valid_from / valid_to (when collection physically existed)
Legal Responsibility: legal_responsibility_start_date / legal_responsibility_end_date (when legal accountability applied)
Material Coverage: temporal_coverage (time period of materials in collection)