kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/docs/GLEIF_INTEGRATION.md

246 lines
9.1 KiB
Markdown
Raw Blame History

# 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)
Reference in a new issue View git blame Copy permalink