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

9.1 KiB
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

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

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

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

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

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)

# 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)

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:

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