glam/docs/SCHEMA_V0.2_QUICK_REFERENCE.md

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: tooi: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	tooi:Oprichting
CLOSURE	Organization dissolved	tooi:Opheffing
MERGER	Merged with other organizations	tooi:Fusie
SPLIT	Split into separate entities	tooi: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 → tooi:officieleNaamInclSoort

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

official_name: "Stichting Rijksmuseum Amsterdam"

sorting_name → tooi:officieleNaamSorteer

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

sorting_name: "Rijksmuseum Amsterdam"  # "Het" removed

abbreviation → tooi: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

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

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

3. 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": "tooi: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?

A:

• 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:

1. Rijksmuseum (Dutch museum with 3 change events)
2. MASP Brazil (international museum with name change)
3. Noord-Hollands Archief (merger with GHCID change)
4. 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