# GLEIF Integration Pattern for Heritage Custodian Ontology

## Overview

The Heritage Custodian Ontology integrates with the Global Legal Entity Identifier Foundation (GLEIF) ontology to model organizational registration and jurisdiction. This enables:

1. **Registration Authority tracking** - Link heritage institutions to their official business registries
2. **Jurisdiction modeling** - Capture legal jurisdictions (national, subnational, supranational)
3. **Trade Register identification** - Reference specific business/trade registers worldwide
4. **LEI compatibility** - Align with Legal Entity Identifier (LEI) infrastructure

## GLEIF Ontology Alignment

### Classes

| Heritage Custodian Class | GLEIF Class | Description |
|--------------------------|-------------|-------------|
| `Jurisdiction` | `lcc-cr:GeographicRegion` | Legal/administrative jurisdiction |
| `TradeRegister` | `gleif-ra:BusinessRegistry` | Official business register |
| `RegistrationAuthority` | `gleif-base:RegistrationAuthority` | Organization maintaining register |
| `RegistrationNumber` | `gleif-base:RegistryIdentifier` | Registration identifier |
| `LegalStatus` | `gleif-base:RegistrationStatus` | Entity legal status |

### Properties

| Heritage Custodian Property | GLEIF Property | Usage |
|-----------------------------|----------------|-------|
| `jurisdiction` | `gleif-base:hasCoverageArea` | Jurisdiction of register/authority |
| `legal_jurisdiction` | `gleif-base:hasLegalJurisdiction` | Legal jurisdiction of entity |
| `primary_register` | `gleif-base:isRegisteredIn` | Primary trade register |
| `maintained_by` | `gleif-base:isManagedBy` | Authority managing register |
| `register_name` | `gleif-base:hasNameTranslatedEnglish` | Register name in English |
| `register_name_local` | `gleif-base:hasNameLegalLocal` | Register name in local language |
| `gleif_ra_code` | `schema:identifier` | GLEIF RA code (e.g., RA000439) |

## GLEIF Registration Authorities List (RAL)

GLEIF maintains a comprehensive list of 1,050+ registration authorities across 232 jurisdictions. Key codes for heritage institutions:

| RA Code | Authority | Country |
|---------|-----------|---------|
| RA000439 | Kamer van Koophandel (KvK) | Netherlands |
| RA000585 | Companies House | United Kingdom |
| RA000586 | Charity Commission | United Kingdom |
| RA000385 | Amtsgericht München | Germany (Bavaria) |
| RA000429 | Legal Affairs Bureau (法務局) | Japan |
| RA000598 | Division of Corporations | USA (Delaware) |
| RA000421 | Companies Registration Office | Ireland |
| RA000287 | Registre du commerce et des sociétés | France |

Reference: https://www.gleif.org/en/about-lei/code-lists/registration-authorities-list

## Schema Structure

### Jurisdiction Class

```yaml
Jurisdiction:
  class_uri: lcc-cr:GeographicRegion
  slots:
    - jurisdiction_id       # Unique ID (e.g., "NL", "DE-BY")
    - jurisdiction_type     # NATIONAL, SUBNATIONAL, MUNICIPAL, SUPRANATIONAL
    - country               # ISO 3166-1 country
    - subregion             # ISO 3166-2 subdivision (for SUBNATIONAL)
    - settlement            # GeoNames settlement (for MUNICIPAL)
    - supranational_code    # e.g., "EU" (for SUPRANATIONAL)
    - legal_system_type     # CIVIL_LAW, COMMON_LAW, MIXED, etc.
    - gleif_jurisdiction_code
    - description
```

### TradeRegister Class

```yaml
TradeRegister:
  class_uri: gleif-ra:BusinessRegistry
  slots:
    - register_id           # Unique ID (e.g., "NL-HR")
    - register_name         # English name
    - register_name_local   # Local language name
    - register_abbreviation # e.g., "HR", "KvK"
    - register_type         # COMMERCIAL, FOUNDATION, ASSOCIATION, CHARITY, MIXED
    - jurisdiction          # Jurisdiction object (inlined)
    - maintained_by         # RegistrationAuthority (inlined)
    - gleif_ra_code         # GLEIF RA code
    - website               # Official website
    - api_endpoint          # Public API URL
    - identifier_format     # Regex pattern for registration numbers
```

### RegistrationAuthority Class

```yaml
RegistrationAuthority:
  class_uri: gleif-base:RegistrationAuthority
  attributes:
    - id                    # URI identifier
    - name                  # English name
    - name_local            # Local language name
    - abbreviation          # e.g., "KvK", "CH"
    - jurisdiction          # Jurisdiction object (inlined)
    - gleif_ra_code         # GLEIF RA code
    - website               # Official website
    - registration_types    # List of entity types handled
```

### RegistrationNumber Class

```yaml
RegistrationNumber:
  class_uri: gleif-base:RegistryIdentifier
  attributes:
    - id                    # URI identifier
    - number                # The actual registration number
    - type                  # e.g., "KvK", "CRN", "HRB"
    - trade_register        # Reference to TradeRegister
    - temporal_validity     # TimeSpan (when valid)
```

## Usage Examples

### 1. Dutch Museum with KvK Registration

```yaml
custodian_legal_statuses:
  - id: "https://w3id.org/heritage/custodian/nl/rijksmuseum/legal"
    legal_name:
      name: "Stichting het Rijksmuseum"
      name_language: "nl"
    legal_jurisdiction:
      jurisdiction_id: "NL"
      jurisdiction_type: NATIONAL
    primary_register:
      register_id: "NL-HR"
      register_name: "Commercial Register"
      register_name_local: "Handelsregister"
      jurisdiction:
        jurisdiction_id: "NL"
        jurisdiction_type: NATIONAL
      maintained_by:
        id: "https://w3id.org/heritage/ra/nl-kvk"
        name: "Chamber of Commerce"
        jurisdiction:
          jurisdiction_id: "NL"
          jurisdiction_type: NATIONAL
    registration_numbers:
      - id: "https://w3id.org/heritage/reg/nl/rijksmuseum-kvk"
        number: "41215422"
        type: "KvK"
        temporal_validity:
          begin_of_the_begin: "1885-07-01T00:00:00Z"
```

### 2. UK Charity (Dual Registration)

```yaml
# British Museum is registered with both Companies House AND Charity Commission
registration_numbers:
  # Companies House registration
  - id: "https://w3id.org/heritage/reg/gb/british-museum-ch"
    number: "RC000024"
    type: "CRN"
    trade_register:
      register_id: "GB-CH"
      register_type: COMMERCIAL

  # Charity Commission registration
  - id: "https://w3id.org/heritage/reg/gb/british-museum-cc"
    number: "1126962"
    type: "CC"
    trade_register:
      register_id: "GB-CC"
      register_type: CHARITY
```

### 3. German Institution (Subnational Jurisdiction)

```yaml
jurisdictions:
  - jurisdiction_id: "DE-BY"
    jurisdiction_type: SUBNATIONAL
    country:
      alpha_2: "DE"
    subregion:
      iso_3166_2_code: "DE-BY"
      subdivision_name: "Bavaria"
    legal_system_type: CIVIL_LAW
    gleif_jurisdiction_code: "DE"

trade_registers:
  - register_id: "DE-HRB-MUC"
    register_name: "Commercial Register"
    register_name_local: "Handelsregister"
    register_type: COMMERCIAL
    jurisdiction:
      jurisdiction_id: "DE-BY"
      jurisdiction_type: SUBNATIONAL
    maintained_by:
      id: "https://w3id.org/heritage/ra/de-by-muc"
      name: "Local Court Munich"
      name_local: "Amtsgericht München"
      jurisdiction:
        jurisdiction_id: "DE-BY"
        jurisdiction_type: SUBNATIONAL
```

## Validation

To validate instances against the schema:

```bash
linkml-validate -s schemas/20251121/linkml/01_custodian_name_modular.yaml \
                -C Container \
                schemas/20251121/linkml/examples/registration_info_examples.yaml
```

## Key Design Decisions

1. **Inlined Objects**: Jurisdiction and RegistrationAuthority are inlined within TradeRegister for easier data entry. They can also be referenced by ID from a separate jurisdictions list.

2. **Separate Country Class**: We use our existing `Country` (ISO 3166-1) and `Subregion` (ISO 3166-2) classes rather than inline country data, maintaining consistency with geographic modeling.

3. **GLEIF RA Codes**: We store GLEIF RA codes as strings with pattern validation (`^RA[0-9]{6}$`), enabling lookup in the official GLEIF RAL.

4. **TimeSpan for Validity**: Registration validity uses CIDOC-CRM TimeSpan pattern with fuzzy boundaries (`begin_of_the_begin`, `end_of_the_end`).

5. **Register Types**: The `RegisterTypeEnum` distinguishes between COMMERCIAL, FOUNDATION, ASSOCIATION, CHARITY, CULTURAL, and MIXED registers.

## Files

| File | Description |
|------|-------------|
| `modules/classes/Jurisdiction.yaml` | Jurisdiction class definition |
| `modules/classes/TradeRegister.yaml` | TradeRegister class definition |
| `modules/classes/RegistrationInfo.yaml` | RegistrationAuthority, RegistrationNumber classes |
| `modules/slots/jurisdiction.yaml` | jurisdiction slot |
| `modules/slots/primary_register.yaml` | primary_register slot |
| `modules/slots/legal_jurisdiction.yaml` | legal_jurisdiction slot |
| `examples/registration_info_examples.yaml` | Validation examples |

## References

- [GLEIF Ontology Documentation](https://www.gleif.org/en/about-lei/code-lists)
- [GLEIF Registration Authorities List](https://www.gleif.org/en/about-lei/code-lists/registration-authorities-list)
- [LCC (Languages Countries and Codes)](https://www.omg.org/spec/LCC/)
- [ISO 3166 Country Codes](https://www.iso.org/iso-3166-country-codes.html)