glam/schemas/20251121/linkml/modules/classes/LEGAL_ENTITY_REFACTORING.md

Legal Entity Model Refactoring Summary

Date: 2025-11-22
Schema Version: 20251121
Status: Complete

Overview

Refactored the EntityTypeEnum into a proper class-based legal entity model that correctly distinguishes between informal observations and formal legal entities.

Key Changes

1. From Enum to Class Hierarchy

OLD: EntityTypeEnum with mixed informal/formal entity types

• INDIVIDUAL, GROUP, ORGANIZATION, GOVERNMENT, CORPORATION
• Mixed informal groups with formal legal entities
• No structured legal metadata

NEW: Proper class hierarchy for legal entities with ISO 20275 compliance

• LegalEntityType: Top-level classification (PERSON vs ORGANIZATION)
• LegalForm: ISO 20275-compliant legal forms with ELF codes
• LegalName: Structured names (TOOI pattern)
• RegistrationNumber: Registration identifiers with temporal validity
• RegistrationAuthority: Registration bodies
• GovernanceStructure: Internal organizational structure
• LegalStatus: Legal status tracking

2. New Class Structure

Core Legal Entity Classes:

LegalEntityType (schemas/20251121/linkml/modules/classes/LegalEntityType.yaml)

• Top-level classification distinguishing natural persons from legal persons
• Two types only: PERSON (natural person) and ORGANIZATION (legal person)
• Maps to: org:classification, schema:additionalType, tooi:organisatievorm

LegalForm (schemas/20251121/linkml/modules/classes/LegalForm.yaml)

• Specific legal forms based on ISO 20275 Entity Legal Form (ELF) codes
• Jurisdiction-specific: 1,600+ forms across 150+ countries
• Maps to: rov:orgType, gleif:hasLegalForm, tooi:rechtsvorm
• Attributes:
  • elf_code: 4-character ISO 20275 code (e.g., "8888" for Dutch Stichting)
  • country_code: ISO 3166-1 alpha-2 code
  • local_name: Name in local language
  • transliterated_name: For non-Latin scripts
  • abbreviation: Common abbreviation (e.g., "BV", "GmbH")
  • legal_entity_type: Link to PERSON or ORGANIZATION
  • valid_from/valid_to: Temporal validity

LegalName (schemas/20251121/linkml/modules/classes/LegalName.yaml)

• Structured legal names following TOOI pattern
• Three name variants:
  1. full_name: With organizational type (e.g., "Stichting Rijksmuseum")
  2. name_without_type: Without type (e.g., "Rijksmuseum")
  3. alphabetical_name: For ordering (e.g., "Gravenhage, 's")
• Maps to: rov:legalName, tooi:officieleNaamInclSoort, tooi:officieleNaamExclSoort
• Attributes:
  • display_name: Preferred UI display name
  • language: ISO 639-1 language code
  • script: ISO 15924 script code
  • temporal_validity: Time period when name is/was valid

RegistrationInfo (schemas/20251121/linkml/modules/classes/RegistrationInfo.yaml)

• RegistrationNumber: Official registration identifiers

  • number: Actual registration number
  • type: Type of registration (KvK, EIN, charity number, etc.)
  • temporal_validity: Period when registration is/was valid
  • Maps to: rov:registration, tooi:organisatieIdentificatie

• RegistrationAuthority: Bodies that maintain registrations

  • name: Official name (e.g., "Kamer van Koophandel")
  • abbreviation: Short code (e.g., "KvK")
  • jurisdiction: Geographic jurisdiction (country/region)
  • website: Official website
  • registration_types: Types of entities they can register
  • Maps to: rov:hasRegisteredOrganization

• GovernanceStructure: Internal organizational structure

  • structure_type: Type (hierarchical, matrix, flat, network)
  • organizational_units: List of departments/divisions
  • governance_body: Top-level board/trustees
  • Maps to: org:hasUnit, org:OrganizationalUnit

• LegalStatus: Legal status tracking

  • status_code: Standardized code (ACTIVE, DISSOLVED, SUSPENDED, MERGED)
  • status_name: Human-readable name
  • description: Detailed legal meaning
  • temporal_validity: Period when status applies
  • jurisdiction: Where status is defined
  • Maps to: schema:status

3. Key Distinctions

CustodianObservation vs CustodianReconstruction:

CustodianObservation:

• Can include informal references, groups, collectives
• Emic (insider) perspective: "what someone called themselves"
• No legal formalization required
• Examples: "Rijks" (letterhead), "The Rijksmuseum" (guidebook)

CustodianReconstruction:

• ONLY formal legal entities with legal recognition
• Etic (outsider) perspective: "what is the formal entity after analysis?"
• Must have legal registration OR established legal identity
• Two types:
  1. Natural persons (individuals with legal rights)
  2. Legal persons (organizations with legal personality)

CRITICAL: Informal groups WITHOUT legal status are NOT CustodianReconstructions. They remain as CustodianObservations only.

4. ISO 20275 Integration

Source: data/ontology/2023-09-28-elf-code-list-v1.5.csv

• 1,600+ standardized legal form codes
• Covers 150+ jurisdictions
• Each legal form has:
  • 4-character alphanumeric code
  • Country-specific definition
  • Local and transliterated names
  • Legal rights and obligations

Common Heritage Institution Legal Forms:

Country	ELF Code	Legal Form	Type
Netherlands	8888	Stichting	Foundation
Netherlands	54M6	Besloten vennootschap	Private Company
Germany	QS1L	Stiftung	Foundation
Germany	HRA1	GmbH	Private Company
France	L6L1	Association	Association
UK	PRIV	Private Limited	Private Company
UK	CHAR	Charity	Charity
US	501C	501(c) Nonprofit	Nonprofit

5. Ontology Alignments

Base Ontology Mappings:

TOOI (Dutch entities):

• tooi:rechtsvorm → Legal form
• tooi:officieleNaamInclSoort → Legal name with type
• tooi:officieleNaamExclSoort → Legal name without type
• tooi:alfabetischeVolgorde → Alphabetical name ordering
• tooi:organisatieIdentificatie → Registration numbers

W3C Organization Ontology:

• org:Organization → Base organizational class
• org:FormalOrganization → Legally recognized entities
• org:hasUnit → Governance structure
• org:classification → Entity type classification

Registered Organizations Vocabulary (ROV):

• rov:legalName → Official legal names
• rov:orgType → Legal form classification
• rov:registration → Registration numbers
• rov:hasRegisteredOrganization → Registering authority

CPOV (Core Public Organisation Vocabulary):

• cpov:PublicOrganisation → Government/public sector entities

Schema.org:

• schema:name, schema:alternateName → Names
• schema:status → Legal status
• schema:additionalType → Entity classification
• schema:validFrom, schema:validThrough → Temporal validity

GLEIF (Global Legal Entity Identifier Foundation):

• gleif:hasEntityLegalFormCode → ISO 20275 ELF codes
• gleif:hasLegalForm → Legal form references

6. Updated CustodianReconstruction Slots

Old Slot	New Slot	Old Range	New Range
entity_type	legal_entity_type	EntityTypeEnum	LegalEntityType
legal_name	legal_name	string	LegalName
legal_form	legal_form	string (pattern)	LegalForm
registration_number	registration_numbers	string	RegistrationNumber[]
registration_date	(deprecated)	date	(moved to RegistrationNumber.temporal_validity)
registration_authority	registration_authority	string	RegistrationAuthority
legal_status	legal_status	LegalStatusEnum	LegalStatus
governance_structure	governance_structure	string	GovernanceStructure

7. Validation Rules

Natural Persons (PERSON):

• Cannot have legal forms (legal form is N/A for individuals)
• May not have registration numbers (unless sole proprietor)
• Identity established through biographical sources

Legal Persons (ORGANIZATION):

• Must have legal forms (ISO 20275 code)
• Must have registration numbers
• Must have registration authority
• Governance structure documented

All Reconstructed Entities:

• Must have legal status (active, dissolved, etc.)
• Must derive from at least one CustodianObservation
• Must document reconstruction activity

8. Examples

Example 1: Dutch Museum (Stichting)

legal_entity_type:
  code: "ORGANIZATION"
  label: "Legal Person"
  
legal_name:
  full_name: "Stichting Rijksmuseum Amsterdam"
  name_without_type: "Rijksmuseum Amsterdam"
  display_name: "Rijksmuseum"
  language: "nl"
  
legal_form:
  elf_code: "8888"
  country_code: "NL"
  local_name: "Stichting"
  abbreviation: "St."
  
registration_numbers:
  - number: "41215422"
    type: "KvK"
    temporal_validity:
      begin_of_the_begin: "1885-07-01"
      
registration_authority:
  name: "Kamer van Koophandel"
  abbreviation: "KvK"
  jurisdiction: "NL"
  
legal_status:
  status_code: "ACTIVE"
  status_name: "Active"

Example 2: Government Archive

legal_entity_type:
  code: "ORGANIZATION"
  label: "Legal Person"
  
legal_name:
  full_name: "Nationaal Archief"
  display_name: "National Archives of the Netherlands"
  language: "nl"
  
legal_form:
  local_name: "Rijksinstelling"  # Government institution
  country_code: "NL"
  
parent_custodian:
  legal_name:
    full_name: "Ministerie van Onderwijs, Cultuur en Wetenschap"
    
legal_status:
  status_code: "ACTIVE"
  status_name: "Active"

Example 3: Private Collector (Natural Person)

legal_entity_type:
  code: "PERSON"
  label: "Natural Person"
  
legal_name:
  full_name: "Dr. Jan de Vries"
  display_name: "Jan de Vries"
  
# No legal_form (not applicable for natural persons)
# No registration_numbers (private individual)

legal_status:
  status_code: "ACTIVE"
  status_name: "Active collector"

Benefits

1. Legal Accuracy: Properly distinguishes legal entities from informal references
2. ISO Compliance: Aligns with ISO 20275 international standard for legal forms
3. Ontology Integration: Reuses properties from established ontologies (TOOI, ROV, W3C Org, CPOV)
4. Temporal Tracking: All legal aspects can have temporal validity (names change, registrations expire)
5. Jurisdiction Support: Handles legal forms across different countries and legal systems
6. Validation: Enforces legal entity constraints at schema level
7. Clarity: Clear distinction between observations (what people call things) and reconstructions (formal legal entities)

Migration Notes

For Data Curators:

1. EntityTypeEnum is deprecated: Use LegalEntityType class instead

2. Existing enum values map to:

   • INDIVIDUAL → LegalEntityType(code="PERSON")
   • ORGANIZATION, GOVERNMENT, CORPORATION → LegalEntityType(code="ORGANIZATION")
   • GROUP → Not a legal entity (remains CustodianObservation only)

3. String-based legal attributes now require structured data:

   • Simple strings → Proper class instances
   • Add ISO 20275 codes where available
   • Document registration authorities

4. Informal groups:

   • If group has legal status (registered association) → CustodianReconstruction
   • If group lacks legal status (informal collective) → CustodianObservation only

For Developers:

1. Import new classes:

   imports:
     - LegalEntityType
     - LegalForm
     - LegalName
     - RegistrationInfo
   

2. Update slot ranges:

   • Change entity_type → legal_entity_type: LegalEntityType
   • Change legal_name: string → legal_name: LegalName
   • Change legal_form: string → legal_form: LegalForm

3. Handle temporal validity:

   • Registration dates now in RegistrationNumber.temporal_validity
   • Name changes tracked via LegalName.temporal_validity

4. Validation rules:

   • Check legal entity type before requiring legal form
   • Ensure organizations have registration details
   • Persons may lack registrations

File Structure

schemas/20251121/linkml/modules/
├── classes/
│   ├── LegalEntityType.yaml          # NEW: Top-level classification
│   ├── LegalForm.yaml                 # NEW: ISO 20275 legal forms
│   ├── LegalName.yaml                 # NEW: Structured names (TOOI pattern)
│   ├── RegistrationInfo.yaml         # NEW: Registration details
│   ├── CustodianReconstruction.yaml  # UPDATED: Uses new class ranges
│   └── LEGAL_ENTITY_REFACTORING.md   # This file
│
├── enums/
│   └── EntityTypeEnum.yaml            # DEPRECATED
│
└── mappings/
    ├── ISO20275_mapping.yaml          # NEW: ISO 20275 code mappings
    └── ISO20275_common.yaml           # NEW: Common heritage institution forms

Scripts

scripts/parse_iso20275_codes.py:

• Parses data/ontology/2023-09-28-elf-code-list-v1.5.csv
• Generates LinkML mappings for common heritage institution legal forms
• Outputs schemas/20251121/linkml/modules/mappings/ISO20275_common.yaml

Usage:

python scripts/parse_iso20275_codes.py

Related Documentation

• ISO 20275 Standard: https://www.gleif.org/en/about-lei/code-lists/iso-20275-entity-legal-forms-code-list
• TOOI Ontology: data/ontology/tooiont.ttl
• W3C Organization Ontology: https://www.w3.org/TR/vocab-org/
• Registered Organizations Vocabulary: https://www.w3.org/TR/vocab-regorg/
• CPOV: https://joinup.ec.europa.eu/collection/semantic-interoperability-community-semic/solution/core-public-organisation-vocabulary

Status

✅ Complete: All files created and updated

• LegalEntityType.yaml
• LegalForm.yaml
• LegalName.yaml
• RegistrationInfo.yaml
• CustodianReconstruction.yaml (updated)
• ISO20275_mapping.yaml
• parse_iso20275_codes.py

⏳ Next Steps:

1. Parse ISO 20275 CSV to generate full mappings
2. Validate schema with LinkML tools
3. Update documentation to reference new classes
4. Create migration script for existing data
5. Update validation tests