================================================================================
LEGAL ENTITY MODEL REFACTORING - COMPLETE
Date: 2025-11-22
Schema Version: 20251121
================================================================================

OBJECTIVE:
Replace EntityTypeEnum with proper class-based legal entity model integrated
with ISO 20275, TOOI naming patterns, and W3C/ROV ontologies.

================================================================================
FILES CREATED (9):
================================================================================

1. schemas/20251121/linkml/modules/classes/LegalEntityType.yaml
   - Top-level classification: PERSON vs ORGANIZATION

2. schemas/20251121/linkml/modules/classes/LegalForm.yaml
   - ISO 20275 Entity Legal Forms (1,600+ codes)

3. schemas/20251121/linkml/modules/classes/LegalName.yaml
   - TOOI naming pattern (3 variants)

4. schemas/20251121/linkml/modules/classes/RegistrationInfo.yaml
   - Contains: RegistrationNumber, RegistrationAuthority, 
     GovernanceStructure, LegalStatus

5. schemas/20251121/linkml/modules/slots/legal_entity_type.yaml
   - Replaces entity_type slot

6. schemas/20251121/linkml/modules/slots/registration_numbers.yaml
   - Pluralized, replaces registration_number

7. schemas/20251121/linkml/modules/mappings/ISO20275_mapping.yaml
   - ISO 20275 code mapping template

8. schemas/20251121/linkml/modules/classes/LEGAL_ENTITY_REFACTORING.md
   - Comprehensive documentation (14 KB)

9. schemas/20251121/linkml/modules/classes/LEGAL_ENTITY_QUICK_REFERENCE.md
   - Quick reference guide

================================================================================
FILES UPDATED (8):
================================================================================

1. schemas/20251121/linkml/modules/classes/CustodianReconstruction.yaml
   - Added 4 class imports
   - Updated 7 slot ranges (string → class)
   - Added validation rules
   - Updated comments

2. schemas/20251121/linkml/modules/slots/legal_name.yaml
   - Range: string → LegalName
   - Updated slot_uri: cpov:legalName → rov:legalName

3. schemas/20251121/linkml/modules/slots/legal_form.yaml
   - Range: string → LegalForm
   - Updated slot_uri: org:classification → rov:orgType

4. schemas/20251121/linkml/modules/slots/registration_authority.yaml
   - Range: string → RegistrationAuthority
   - Updated slot_uri: prov:wasAttributedTo → rov:hasRegisteredOrganization

5. schemas/20251121/linkml/modules/slots/legal_status.yaml
   - Range: LegalStatusEnum → LegalStatus
   - Updated slot_uri: gleif-base:hasEntityStatus → schema:status

6. schemas/20251121/linkml/modules/slots/governance_structure.yaml
   - Range: string → GovernanceStructure
   - Updated slot_uri: org:organization → org:hasUnit

7. schemas/20251121/linkml/01_custodian_name_modular.yaml
   - Added 4 class imports
   - Added 2 slot imports
   - Updated file counts in comments

8. schemas/20251121/linkml/modules/classes/ReconstructionActivity.yaml
   - Added TimeSpan import
   - Changed started_at_time/ended_at_time → temporal_extent
   - Updated to use TimeSpan for activity duration

================================================================================
FILES DEPRECATED (2):
================================================================================

1. schemas/20251121/linkml/modules/slots/entity_type.yaml
   → entity_type.yaml.deprecated

2. schemas/20251121/linkml/modules/slots/registration_number.yaml
   → registration_number.yaml.deprecated

================================================================================
SCRIPTS CREATED (1):
================================================================================

1. scripts/parse_iso20275_codes.py
   - Parses data/ontology/2023-09-28-elf-code-list-v1.5.csv
   - Generates common heritage institution legal form mappings

================================================================================
DOCUMENTATION CREATED (3):
================================================================================

1. SESSION_SUMMARY_20251122_LEGAL_ENTITY_REFACTORING.md
   - Complete session summary

2. VERIFICATION_CHECKLIST_20251122.md
   - Verification of all links and imports

3. CHANGES_SUMMARY_20251122.txt
   - This file

================================================================================
KEY CHANGES:
================================================================================

BEFORE:
- entity_type: INDIVIDUAL/GROUP/ORGANIZATION/GOVERNMENT/CORPORATION
- legal_name: "string"
- legal_form: "string" (pattern)
- registration_number: "string"
- registration_authority: "string"
- legal_status: LegalStatusEnum
- governance_structure: "string"

AFTER:
- legal_entity_type: LegalEntityType class (PERSON/ORGANIZATION)
- legal_name: LegalName class (full_name, name_without_type, alphabetical_name)
- legal_form: LegalForm class (elf_code, country_code, local_name)
- registration_numbers: RegistrationNumber[] class (number, type, temporal_validity)
- registration_authority: RegistrationAuthority class (name, abbreviation, jurisdiction)
- legal_status: LegalStatus class (status_code, temporal_validity)
- governance_structure: GovernanceStructure class (structure_type, units)

================================================================================
CRITICAL RULES:
================================================================================

1. CustodianReconstruction is ONLY for formally registered legal entities
   - Natural persons (with legal rights)
   - Legal persons (organizations with legal personality)

2. Informal groups WITHOUT legal status remain as CustodianObservation only

3. Natural persons (PERSON) cannot have legal forms

4. Legal persons (ORGANIZATION) must have legal forms (ISO 20275 codes)

5. All legal attributes now have temporal validity via TimeSpan

================================================================================
ONTOLOGY ALIGNMENTS:
================================================================================

LegalEntityType        → org:classification
LegalForm              → rov:orgType, gleif:hasLegalForm, tooi:rechtsvorm
LegalName              → rov:legalName, tooi:officieleNaamInclSoort
RegistrationNumber     → rov:registration, tooi:organisatieIdentificatie
RegistrationAuthority  → rov:hasRegisteredOrganization
GovernanceStructure    → org:hasUnit
LegalStatus            → schema:status

================================================================================
NEXT STEPS:
================================================================================

1. Run LinkML validation:
   linkml-validate -s schemas/20251121/linkml/01_custodian_name_modular.yaml

2. Generate RDF:
   gen-owl -f ttl schemas/20251121/linkml/01_custodian_name_modular.yaml

3. Parse ISO 20275 codes:
   python scripts/parse_iso20275_codes.py

4. Migrate existing data to new structure

5. Update validation tests

================================================================================
VERIFICATION STATUS: ✅ COMPLETE
================================================================================

All files created, updated, and properly linked.
No broken imports. All ranges reference existing classes.
Ready for LinkML validation and RDF generation.

================================================================================