283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# Appellation and Identifier Refactoring - Complete ✅
|
|
|
|
**Date**: 2025-11-22
|
|
**Status**: COMPLETE
|
|
**Schema Version**: 0.1.0
|
|
|
|
## Summary
|
|
|
|
Successfully renamed and connected the `Appellation` and `Identifier` classes to the `Custodian` hub using proper CIDOC-CRM edge properties.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Renamed Classes ✅
|
|
|
|
**Before**:
|
|
- `Appellation` (orphaned, no connection to Custodian hub)
|
|
- `Identifier` (orphaned, no connection to Custodian hub)
|
|
|
|
**After**:
|
|
- `CustodianAppellation` (connected via bidirectional CIDOC-CRM properties)
|
|
- `CustodianIdentifier` (connected via bidirectional CIDOC-CRM properties)
|
|
|
|
### 2. Added CIDOC-CRM Edge Properties ✅
|
|
|
|
#### CustodianAppellation Connection
|
|
|
|
**Forward Property** (Custodian → CustodianAppellation):
|
|
```yaml
|
|
# In Custodian class
|
|
appellations:
|
|
slot_uri: crm:P1_is_identified_by
|
|
range: CustodianAppellation
|
|
multivalued: true
|
|
description: "Names and labels used to identify this custodian"
|
|
```
|
|
|
|
**Inverse Property** (CustodianAppellation → Custodian):
|
|
```yaml
|
|
# In CustodianAppellation class
|
|
identifies_custodian:
|
|
slot_uri: crm:P1i_identifies
|
|
range: Custodian
|
|
required: false
|
|
description: "Links this appellation back to the Custodian hub it identifies"
|
|
```
|
|
|
|
**CIDOC-CRM Properties**:
|
|
- `crm:P1_is_identified_by` - Domain: E1_CRM_Entity (Custodian) → Range: E41_Appellation
|
|
- `crm:P1i_identifies` - Inverse property (E41_Appellation → E1_CRM_Entity)
|
|
|
|
#### CustodianIdentifier Connection
|
|
|
|
**Forward Property** (Custodian → CustodianIdentifier):
|
|
```yaml
|
|
# In Custodian class
|
|
identifiers:
|
|
slot_uri: crm:P48_has_preferred_identifier
|
|
range: CustodianIdentifier
|
|
multivalued: true
|
|
description: "External identifiers assigned to this custodian by authorities"
|
|
```
|
|
|
|
**Inverse Property** (CustodianIdentifier → Custodian):
|
|
```yaml
|
|
# In CustodianIdentifier class
|
|
identifies_custodian:
|
|
slot_uri: crm:P48i_is_preferred_identifier_of
|
|
range: Custodian
|
|
required: false
|
|
description: "Links this identifier back to the Custodian hub it identifies"
|
|
```
|
|
|
|
**CIDOC-CRM Properties**:
|
|
- `crm:P48_has_preferred_identifier` - Domain: E1_CRM_Entity (Custodian) → Range: E42_Identifier
|
|
- `crm:P48i_is_preferred_identifier_of` - Inverse property (E42_Identifier → E1_CRM_Entity)
|
|
|
|
### 3. Created New Slot Files ✅
|
|
|
|
**Created**:
|
|
- `modules/slots/appellations.yaml` - Forward property (Custodian → CustodianAppellation)
|
|
- `modules/slots/identifies_custodian.yaml` - Inverse property (both CustodianAppellation and CustodianIdentifier → Custodian)
|
|
|
|
**Updated**:
|
|
- `modules/slots/identifiers.yaml` - Updated to use `crm:P48_has_preferred_identifier` and `CustodianIdentifier` range
|
|
|
|
### 4. Updated Class Files ✅
|
|
|
|
**Updated Files**:
|
|
1. `modules/classes/Appellation.yaml` → Renamed to reference `CustodianAppellation`
|
|
- Added `identifies_custodian` slot
|
|
- Added CIDOC-CRM documentation
|
|
- Updated class_uri: `crm:E41_Appellation`
|
|
|
|
2. `modules/classes/Identifier.yaml` → Renamed to reference `CustodianIdentifier`
|
|
- Added `identifies_custodian` slot
|
|
- Added CIDOC-CRM documentation
|
|
- Updated class_uri: `crm:E42_Identifier`
|
|
|
|
3. `modules/classes/Custodian.yaml` → Added forward properties
|
|
- Added `appellations` slot (multivalued)
|
|
- Added `identifiers` slot (multivalued)
|
|
- Both use proper CIDOC-CRM properties
|
|
|
|
4. `modules/classes/CustodianObservation.yaml` → Updated range references
|
|
- `observed_name`: `Appellation` → `CustodianAppellation`
|
|
- `alternative_observed_names`: `Appellation` → `CustodianAppellation`
|
|
|
|
5. `modules/classes/CustodianReconstruction.yaml` → Updated range references
|
|
- `identifiers`: `Identifier` → `CustodianIdentifier`
|
|
- Updated slot_uri: `dcterms:identifier` → `crm:P48_has_preferred_identifier`
|
|
|
|
### 5. Updated Main Schema ✅
|
|
|
|
**File**: `01_custodian_name_modular.yaml`
|
|
|
|
**Changes**:
|
|
- Added imports: `modules/slots/appellations`, `modules/slots/identifies_custodian`
|
|
- Updated file count: 84 → 86 total files (+2 new slots)
|
|
- Added comment about new bidirectional slots
|
|
|
|
## Hub Architecture Pattern
|
|
|
|
The refactoring implements proper bidirectional linking between the Custodian hub and its appellations/identifiers:
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Custodian │ (Hub - minimal, just hc_id)
|
|
│ (E39_Actor) │
|
|
└────────┬────────┘
|
|
│
|
|
├─── crm:P1_is_identified_by ─────→ CustodianAppellation (E41_Appellation)
|
|
│ │
|
|
│ └─── crm:P1i_identifies ────→ (back to hub)
|
|
│
|
|
└─── crm:P48_has_preferred_identifier ──→ CustodianIdentifier (E42_Identifier)
|
|
│
|
|
└─── crm:P48i_is_preferred_identifier_of ──→ (back to hub)
|
|
```
|
|
|
|
**Key Design Principles**:
|
|
|
|
1. **Bidirectional Links**: Both forward and inverse properties implemented
|
|
2. **CIDOC-CRM Compliance**: Uses standard cultural heritage ontology properties
|
|
3. **Multivalued**: A custodian can have multiple appellations and identifiers
|
|
4. **Optional Inverse**: The `identifies_custodian` slot is optional (not required)
|
|
|
|
## CIDOC-CRM Ontology Alignment
|
|
|
|
### E41_Appellation (CustodianAppellation)
|
|
|
|
**CIDOC-CRM Definition**:
|
|
> "This class comprises any identifier expressed as text (names, titles, labels)."
|
|
|
|
**Properties Used**:
|
|
- **P1_is_identified_by** (E1 CRM Entity → E41 Appellation)
|
|
- "This property describes the naming or identification of any real-world item by a name or any other identifier."
|
|
|
|
- **P1i_identifies** (E41 Appellation → E1 CRM Entity) - *inverse*
|
|
- "This property identifies the entity that is named or identified."
|
|
|
|
**Use Cases**:
|
|
- Official names (emic names accepted by the custodian)
|
|
- Alternative names and translations
|
|
- Historical name variants
|
|
- Multilingual representations
|
|
|
|
### E42_Identifier (CustodianIdentifier)
|
|
|
|
**CIDOC-CRM Definition**:
|
|
> "This class comprises formal symbols or reference codes for unique identification."
|
|
|
|
**Properties Used**:
|
|
- **P48_has_preferred_identifier** (E1 CRM Entity → E42 Identifier)
|
|
- "This property records the preferred E42 Identifier that was used to identify an instance of E1 CRM Entity at the time this property was recorded."
|
|
|
|
- **P48i_is_preferred_identifier_of** (E42 Identifier → E1 CRM Entity) - *inverse*
|
|
- "This property identifies the E1 CRM Entity that this E42 Identifier is the preferred identifier for."
|
|
|
|
**Use Cases**:
|
|
- ISIL codes (International Standard Identifier for Libraries and Related Organizations)
|
|
- Wikidata Q-numbers
|
|
- VIAF identifiers (Virtual International Authority File)
|
|
- KvK numbers (Dutch Chamber of Commerce)
|
|
- ROR identifiers (Research Organization Registry)
|
|
|
|
## Validation
|
|
|
|
**Schema Compilation**: ✅ PASS
|
|
```bash
|
|
$ gen-owl -f ttl schemas/20251121/linkml/01_custodian_name_modular.yaml
|
|
# Successfully compiled with expected warnings about namespace mappings
|
|
```
|
|
|
|
**Warnings** (expected and acceptable):
|
|
- Namespace mapping conflicts (heritage, schema, tooi) - resolved by import order
|
|
- Multiple owl types for language slot - acceptable for multilingual support
|
|
|
|
## File Count Summary
|
|
|
|
**Before Refactoring**:
|
|
- Total files: 84
|
|
|
|
**After Refactoring**:
|
|
- Total files: 86 (+2 new slot files)
|
|
- Breakdown:
|
|
- 17 classes (no change, renamed existing)
|
|
- 6 enums (no change)
|
|
- 61 slots (+2: `appellations`, `identifies_custodian`)
|
|
- 1 metadata file
|
|
- 1 main schema
|
|
|
|
## Next Steps
|
|
|
|
### 1. Regenerate RDF Formats ⏳
|
|
```bash
|
|
cd /Users/kempersc/apps/glam/schemas/20251121/rdf
|
|
gen-owl -f ttl ../linkml/01_custodian_name_modular.yaml > 01_custodian_name.owl.ttl
|
|
rdfpipe 01_custodian_name.owl.ttl -o nt > 01_custodian_name.nt
|
|
rdfpipe 01_custodian_name.owl.ttl -o jsonld > 01_custodian_name.jsonld
|
|
# ... repeat for all 8 formats
|
|
```
|
|
|
|
### 2. Update UML Diagrams ⏳
|
|
- Regenerate Mermaid class diagram with new appellations/identifiers slots
|
|
- Regenerate PlantUML diagram showing bidirectional relationships
|
|
|
|
### 3. Create Example Instances ⏳
|
|
```yaml
|
|
# Example showing bidirectional linking
|
|
---
|
|
# Custodian hub
|
|
- hc_id: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
|
|
appellations:
|
|
- appellation_value: "Rijksmuseum"
|
|
appellation_language: "nl"
|
|
appellation_type: OFFICIAL
|
|
identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
|
|
identifiers:
|
|
- identifier_scheme: "ISIL"
|
|
identifier_value: "NL-AmRMA"
|
|
identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
|
|
- identifier_scheme: "Wikidata"
|
|
identifier_value: "Q190804"
|
|
identifies_custodian: https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804
|
|
```
|
|
|
|
### 4. Update Documentation ⏳
|
|
- Update `SCHEMA_ARCHITECTURE.md` with bidirectional linking patterns
|
|
- Document CIDOC-CRM property usage in `ONTOLOGY_ALIGNMENT.md`
|
|
- Add examples to `USAGE_GUIDE.md`
|
|
|
|
## References
|
|
|
|
**CIDOC-CRM**:
|
|
- [CIDOC-CRM v7.1.3 Specification](https://www.cidoc-crm.org/html/cidoc_crm_v7.1.3.html)
|
|
- E41_Appellation: http://www.cidoc-crm.org/Entity/e41-appellation/version-7.1.3
|
|
- E42_Identifier: http://www.cidoc-crm.org/Entity/e42-identifier/version-7.1.3
|
|
- P1_is_identified_by: http://www.cidoc-crm.org/Property/p1-is-identified-by/version-7.1.3
|
|
- P48_has_preferred_identifier: http://www.cidoc-crm.org/Property/p48-has-preferred-identifier/version-7.1.3
|
|
|
|
**Local Files**:
|
|
- Ontology: `/data/ontology/CIDOC_CRM_v7.1.3.rdf`
|
|
- Schema: `/schemas/20251121/linkml/01_custodian_name_modular.yaml`
|
|
- RDF Output: `/schemas/20251121/rdf/` (to be regenerated)
|
|
|
|
## Session Context
|
|
|
|
This refactoring is part of the broader **Legal Entity Refactoring** work (2025-11-22), which:
|
|
1. ✅ Added comprehensive legal entity model (8 new classes)
|
|
2. ✅ Generated RDF serializations (7 formats, 2,701 triples)
|
|
3. ✅ Created UML diagrams (Mermaid + PlantUML)
|
|
4. ✅ Connected orphaned Appellation/Identifier classes to Custodian hub (THIS DOCUMENT)
|
|
|
|
**See Also**:
|
|
- `LEGAL_ENTITY_REFACTORING.md` - Complete legal entity model documentation
|
|
- `RDF_UML_GENERATION_COMPLETE_20251122.md` - RDF generation guide
|
|
- `SESSION_SUMMARY_20251122_APPELLATION_IDENTIFIER_REFACTORING.md` - Session log
|
|
|
|
---
|
|
|
|
**Status**: ✅ COMPLETE
|
|
**Validated**: Schema compiles successfully
|
|
**Next Actions**: Regenerate RDF, update UML, create example instances
|