kempersc/glam

Fork 0

kempersc 3c80de87e0 add isil entries

2025-11-19 23:25:22 +01:00

13 KiB

Raw Blame History

Heritage Custodian Schema v0.2.0 - Quick Reference

Version: 0.2.0
Release Date: 2025-11-05
Major Features: PROV-O, TOOI, CPOV integration

New Features at a Glance

✨ Organizational Change Tracking

Track mergers, splits, relocations, and other institutional changes:

change_history:
  - event_id: "https://w3id.org/heritage/custodian/event/merger-2001"
    change_type: MERGER  # One of 12 ChangeTypeEnum values
    event_date: "2001-01-01"
    event_description: "Merged Institution A and B to form C"
    source_documentation: "https://institution.org/history"

🕒 Precise Temporal Tracking (PROV-O)

Add precise timestamps to complement simple dates:

# Simple dates (for display)
founded_date: "1800-11-19"
closed_date: "2020-12-31"

# PROV-O timestamps (for provenance tracking)
prov_generated_at: "1800-11-19T10:30:00Z"
prov_invalidated_at: "2020-12-31T23:59:59Z"

🏛️ TOOI Dutch Organizational Naming

Support official, sorting, and abbreviated names:

name: "Rijksmuseum"  # Display name (required)
official_name: "Stichting Rijksmuseum Amsterdam"  # Legal name
sorting_name: "Rijksmuseum Amsterdam"  # For alphabetical sorting (no "Het")
abbreviation: "RM"  # Official acronym

New Classes

1. ChangeEvent

Purpose: Track organizational changes in institutional lifecycle

Class URI: prov:Activity
Mixin: tooiont:Wijzigingsgebeurtenis

Required Fields:

event_id (uriorcurie)
change_type (ChangeTypeEnum)
event_date (date)

Optional Fields:

event_description (string)
affected_organization (HeritageCustodian)
resulting_organization (HeritageCustodian)
related_organizations (List[HeritageCustodian])
source_documentation (uri)

Example:

- event_id: "https://w3id.org/heritage/custodian/event/rijksmuseum-relocation-1885"
  change_type: RELOCATION
  event_date: "1885-07-13"
  event_description: "Moved from Trippenhuis to Museumstraat 1"
  source_documentation: "https://www.rijksmuseum.nl/en/about-us/history"

2. OrganizationalUnit

Purpose: Model departments, divisions, branches within institutions

Class URI: org:OrganizationalUnit

Required Fields:

unit_id (uriorcurie)
unit_name (string)

Optional Fields:

unit_type (string)
parent_unit (OrganizationalUnit) - supports recursive hierarchy
description (string)
contact_info (ContactInfo)
homepage (uri)

Example:

# Special Collections department at a library
- unit_id: "https://w3id.org/heritage/custodian/unit/ubl-special-collections"
  unit_name: "Special Collections"
  unit_type: "department"
  parent_unit: null  # Top-level unit
  description: "Rare books and manuscripts collection"
  homepage: "https://www.library.universiteitleiden.nl/special-collections"

New Enumeration

ChangeTypeEnum (12 values)

Value	Description	TOOI Mapping
`FOUNDING`	Organization established	`tooiont:Oprichting`
`CLOSURE`	Organization dissolved	`tooiont:Opheffing`
`MERGER`	Merged with other organizations	`tooiont:Fusie`
`SPLIT`	Split into separate entities	`tooiont:Afsplitsing`
`ACQUISITION`	Acquired another organization	-
`RELOCATION`	Moved to new location	-
`NAME_CHANGE`	Changed official name	-
`TYPE_CHANGE`	Institution type changed	-
`STATUS_CHANGE`	Operational status changed	-
`RESTRUCTURING`	Internal reorganization	-
`LEGAL_CHANGE`	Legal status/governance changed	-
`OTHER`	Other type of change	-

Usage:

change_history:
  - change_type: MERGER
  - change_type: NAME_CHANGE
  - change_type: RELOCATION

New Slots on HeritageCustodian

PROV-O Temporal Slots

`prov_generated_at` → `prov:generatedAtTime`

Type: datetime
Required: No
Description: Precise timestamp when organization was founded/created

prov_generated_at: "1800-11-19T00:00:00Z"

`prov_invalidated_at` → `prov:invalidatedAtTime`

Type: datetime
Required: No
Description: Precise timestamp when organization was dissolved/closed

prov_invalidated_at: "2020-12-31T23:59:59Z"

`change_history` → `prov:wasInfluencedBy`

Type: List[ChangeEvent]
Required: No
Description: Chronological list of organizational change events

change_history:
  - event_id: "https://..."
    change_type: MERGER
    event_date: "2001-01-01"

TOOI Naming Slots

`official_name` → `tooiont:officieleNaamInclSoort`

Type: string
Required: No
Description: Official legal name including organizational form

official_name: "Stichting Rijksmuseum Amsterdam"

`sorting_name` → `tooiont:officieleNaamSorteer`

Type: string
Required: No
Description: Name formatted for alphabetical sorting (no leading articles)

sorting_name: "Rijksmuseum Amsterdam"  # "Het" removed

`abbreviation` → `tooiont:afkorting`

Type: string
Required: No
Description: Official abbreviation or acronym

abbreviation: "RM"

Updated Class Mappings

HeritageCustodian

Added mixin: prov:Entity

HeritageCustodian:
  class_uri: org:Organization
  mixins:
    - prov:Entity  # NEW - enables PROV-O provenance tracking

ContactInfo

Changed class_uri: cpov:ContactPoint (was schema:ContactPoint)
Added mixin: schema:ContactPoint

ContactInfo:
  class_uri: cpov:ContactPoint  # UPDATED - EU standard
  mixins:
    - schema:ContactPoint  # Maintains Schema.org compatibility

Usage Patterns

Pattern 1: Simple Institution (Minimal)

id: "https://w3id.org/heritage/custodian/example"
name: "Example Museum"
institution_type: MUSEUM
founded_date: "1900-01-01"
provenance:
  data_source: MANUAL_ENTRY
  data_tier: TIER_2_VERIFIED
  extraction_date: "2025-11-05T10:00:00Z"

Pattern 2: Dutch Institution with TOOI Naming

id: "https://w3id.org/heritage/custodian/NL-NH-AMS-M-RM"
name: "Rijksmuseum"
official_name: "Stichting Rijksmuseum Amsterdam"
sorting_name: "Rijksmuseum Amsterdam"
abbreviation: "RM"
institution_type: MUSEUM
founded_date: "1800-11-19"
prov_generated_at: "1800-11-19T00:00:00Z"
provenance:
  data_source: DUTCH_ORG_CSV
  data_tier: TIER_1_AUTHORITATIVE
  extraction_date: "2025-11-05T10:00:00Z"

Pattern 3: Institution with Change History

id: "https://w3id.org/heritage/custodian/NL-NH-HAA-A-NHA"
name: "Noord-Hollands Archief"
institution_type: ARCHIVE
founded_date: "2001-01-01"
prov_generated_at: "2001-01-01T00:00:00Z"

change_history:
  - event_id: "https://w3id.org/heritage/custodian/event/nha-merger-2001"
    change_type: MERGER
    event_date: "2001-01-01"
    event_description: >-
      Merger of Gemeentearchief Haarlem (founded 1910) and 
      Rijksarchief in Noord-Holland (founded 1802)      
    source_documentation: "https://www.noordhollandsarchief.nl/over-ons/geschiedenis"

ghcid_history:
  - ghcid: "NL-NH-HAA-A-GHA"
    valid_from: "1910-01-01T00:00:00Z"
    valid_to: "2000-12-31T23:59:59Z"
    reason: "Original identifier before merger"
  - ghcid: "NL-NH-HAA-A-NHA"
    valid_from: "2001-01-01T00:00:00Z"
    valid_to: null
    reason: "New identifier after merger"

provenance:
  data_source: DUTCH_ORG_CSV
  data_tier: TIER_1_AUTHORITATIVE
  extraction_date: "2025-11-05T11:00:00Z"

Pattern 4: International Institution

id: "https://w3id.org/heritage/custodian/BR-SP-SAO-M-MASP"
name: "Museu de Arte de São Paulo Assis Chateaubriand"
official_name: "Museu de Arte de São Paulo Assis Chateaubriand"
sorting_name: "Museu de Arte de Sao Paulo Assis Chateaubriand"
abbreviation: "MASP"
institution_type: MUSEUM
founded_date: "1947-10-02"
prov_generated_at: "1947-10-02T00:00:00Z"

change_history:
  - event_id: "https://w3id.org/heritage/custodian/event/masp-name-addition-1968"
    change_type: NAME_CHANGE
    event_date: "1968-01-01"
    event_description: "Added 'Assis Chateaubriand' to honor founder"

provenance:
  data_source: WIKIDATA
  data_tier: TIER_3_CROWD_SOURCED
  extraction_date: "2025-11-05T10:30:00Z"

Migration Guide (v0.1.0 → v0.2.0)

Breaking Changes

None - v0.2.0 is backward compatible with v0.1.0

Recommended Updates

Add PROV-O timestamps (optional but recommended):

# Before (v0.1.0)
founded_date: "1900-01-01"

# After (v0.2.0)
founded_date: "1900-01-01"
prov_generated_at: "1900-01-01T00:00:00Z"  # Add precise timestamp

Add change history for institutions with known changes:

# New in v0.2.0
change_history:
  - event_id: "..."
    change_type: MERGER
    event_date: "2001-01-01"
    event_description: "Merged with X"

Add TOOI naming for Dutch institutions:

# New in v0.2.0
official_name: "Stichting [Organization Name]"
sorting_name: "[Organization Name]"  # Without articles
abbreviation: "ABC"

No Action Required

Existing v0.1.0 records remain valid
New fields are optional
Class URIs unchanged (except ContactInfo enhancement via mixin)

RDF/Linked Data Mappings

JSON-LD Context

Use schemas/heritage_custodian_context.jsonld for RDF serialization:

{
  "@context": {
    "HeritageCustodian": {"@id": "org:Organization"},
    "ChangeEvent": {"@id": "prov:Activity"},
    "ContactInfo": {"@id": "cpov:ContactPoint"},
    "prov_generated_at": {"@id": "prov:generatedAtTime", "@type": "xsd:dateTime"},
    "official_name": {"@id": "tooiont:officieleNaamInclSoort"}
  }
}

SPARQL Examples

Find all mergers:

PREFIX prov: <http://www.w3.org/ns/prov#>
PREFIX heritage: <https://w3id.org/heritage/custodian/>

SELECT ?event ?date ?description
WHERE {
  ?event a prov:Activity ;
         heritage:change_type heritage:MERGER ;
         heritage:event_date ?date ;
         heritage:event_description ?description .
}
ORDER BY ?date

Find institutions founded before 1600 still active:

PREFIX prov: <http://www.w3.org/ns/prov#>

SELECT ?org ?name ?founded
WHERE {
  ?org prov:generatedAtTime ?founded ;
       schema:name ?name .
  FILTER(?founded < "1600-01-01T00:00:00Z"^^xsd:dateTime)
  FILTER NOT EXISTS { ?org prov:invalidatedAtTime ?closed }
}
ORDER BY ?founded

Validation

Python Validation

from linkml_runtime.utils.schemaview import SchemaView

sv = SchemaView('schemas/heritage_custodian.yaml')
print(f"Schema version: {sv.schema.version}")  # 0.2.0

# Check if ChangeEvent class exists
assert 'ChangeEvent' in sv.all_classes()

# Check if ChangeTypeEnum exists
assert 'ChangeTypeEnum' in sv.all_enums()
enum = sv.get_enum('ChangeTypeEnum')
print(f"Change types: {len(enum.permissible_values)}")  # 12

Load Example Instances

import yaml

with open('examples/heritage_custodian_instances.yaml', 'r') as f:
    instances = yaml.safe_load(f)

# Check features
for inst in instances:
    if inst.get('change_history'):
        print(f"{inst['name']}: {len(inst['change_history'])} changes tracked")
    if inst.get('prov_generated_at'):
        print(f"{inst['name']}: Founded at {inst['prov_generated_at']}")

FAQs

Q: Are the new v0.2.0 fields required?

A: No. All new fields (prov_generated_at, change_history, TOOI naming, etc.) are optional. Existing v0.1.0 records remain valid.

Q: Should I use both `founded_date` and `prov_generated_at`?

A: Recommended but not required. Use founded_date for simple display, prov_generated_at for precise provenance tracking. They complement each other.

Q: When should I use `official_name` vs. `name`?

name: Required, display name (e.g., "Rijksmuseum")
official_name: Optional, legal name (e.g., "Stichting Rijksmuseum Amsterdam")
Use official_name for Dutch institutions or when legal precision matters

Q: How do I link a ChangeEvent to GHCID changes?

A: Match the event_date with ghcid_history timestamps:

change_history:
  - event_date: "2001-01-01"  # Merger event
    change_type: MERGER

ghcid_history:
  - valid_to: "2000-12-31T23:59:59Z"  # Old GHCID invalidated
  - valid_from: "2001-01-01T00:00:00Z"  # New GHCID generated

Q: Can I use `ChangeEvent` for non-organizational changes?

A: No. ChangeEvent is specifically for organizational changes (mergers, relocations, etc.). For collection changes or other events, use description field or create custom extensions.

Examples

See examples/heritage_custodian_instances.yaml for 4 comprehensive examples:

Rijksmuseum (Dutch museum with 3 change events)
MASP Brazil (international museum with name change)
Noord-Hollands Archief (merger with GHCID change)
Leiden University Library (stable institution since 1575)

Resources

Schema: schemas/heritage_custodian.yaml
JSON-LD Context: schemas/heritage_custodian_context.jsonld
Examples: examples/heritage_custodian_instances.yaml
Design Docs: docs/ontology_integration_design.md
AI Guidance: AGENTS.md (Task 8: Organizational Change Event Extraction)

Version: 0.2.0
Last Updated: 2025-11-05
Compatibility: Backward compatible with v0.1.0

13 KiB Raw Blame History