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:

```yaml
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:

```yaml
# 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:

```yaml
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**:
```yaml
- 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**:
```yaml
# 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**:
```yaml
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

```yaml
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

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

#### `change_history` → `prov:wasInfluencedBy`
**Type**: List[ChangeEvent]  
**Required**: No  
**Description**: Chronological list of organizational change events

```yaml
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

```yaml
official_name: "Stichting Rijksmuseum Amsterdam"
```

#### `sorting_name` → `tooi:officieleNaamSorteer`
**Type**: string  
**Required**: No  
**Description**: Name formatted for alphabetical sorting (no leading articles)

```yaml
sorting_name: "Rijksmuseum Amsterdam"  # "Het" removed
```

#### `abbreviation` → `tooi:afkorting`
**Type**: string  
**Required**: No  
**Description**: Official abbreviation or acronym

```yaml
abbreviation: "RM"
```

---

## Updated Class Mappings

### HeritageCustodian
**Added mixin**: `prov:Entity`

```yaml
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`

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

---

## Usage Patterns

### Pattern 1: Simple Institution (Minimal)
```yaml
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
```yaml
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
```yaml
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
```yaml
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):
   ```yaml
   # 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:
   ```yaml
   # 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:
   ```yaml
   # 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:

```json
{
  "@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**:
```sparql
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**:
```sparql
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
```python
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
```python
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:
```yaml
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