ADR-00011: URI-Based Legal Entity Identifier Scheme

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Accepted	2026-06-05
CTN Technical Advisory Board	Accepted	2026-07-08
CTN Steering Committee	Not Required	2026-07-08
BDI Conformance Team	Proposed	2026-07-08
BDI Framework Team	Proposed	2026-07-08

Context and Problem Statement

The ASR data model records official business register identifiers of legal entities (LegalEntityIdentifier). The current design uses a closed Java enum IdentifierType (KVK, KBO, HRB, EUID, LEI, EORI, VAT) plus a separate free-form identifierValue string. The model review flagged two problems:

1. Not extensible. Adding an identifier scheme (e.g. GLN, DUNS, a non-European business register) requires a code change, a release, and — with EnumType.STRING persistence — touches every consumer that switches over the enum. A registry service for an open dataspace must accept new schemes as data, not as code.
2. Type and value are split. An identifier is only meaningful as the pair (scheme, value). Passing two loosely coupled fields through APIs, tokens, and logs invites mismatches. A single self-describing string removes that class of error.

We need a representation that:

• conveys the identifier scheme (e.g. “this is a Kamer van Koophandel number”),
• optionally carries the value itself (68750110) — scheme-only references are needed for onboarding forms (“please provide your KVK number”), query filters, and validation-source configuration,
• is extensible without code changes,
• interoperates with the ecosystems CTN already touches: Peppol, GLEIF, BRIS/EUID, VIES (see the identifier enrichment architecture).

Considered Options

Option 1: Keep enums (status quo)

• Description: Retain IdentifierType enum + identifierValue string as currently modelled.
• Pros: Type-safe in Java; database-level validation via enum string; no design work.
• Cons: Every new scheme is a code change; type and value travel separately; no interop story with external scheme registries; explicitly rejected by the model review.

Option 2: BDI URN namespace with readable tokens

• Description: A single custom namespace with human-readable scheme tokens: urn:bdi:legal-id:kvk:68750110. A documented mapping table (kvk↔0106, kbo↔0208, …) provides ISO 6523 / Peppol interop.
• Pros: Human-readable; uniform grammar (one namespace); full control over vocabulary; fallback and primary schemes look identical.
• Cons: BDI must govern the token vocabulary; every external exchange needs the mapping table applied; readable tokens invite ad-hoc inventions (“kvk” vs “nl-kvk” vs “kamer-van-koophandel”).

Option 3: ISO 6523-anchored URN with BDI fallback namespace

• Description: Use ISO 6523 International Code Designator (ICD) codes as the scheme authority: urn:iso6523:0106:68750110. Schemes without an ICD code use a BDI-governed fallback namespace: urn:bdi:legal-id:eori:NL123456789.
• Pros: Anchored on a global (not European) standard — DUNS (0060), GS1 GLN (0088), Australian ABN (0151), Japanese Corporate Number (0188), Singapore UEN (0195) are already registered; zero-translation interop with Peppol participant identifiers; scheme vocabulary governed externally, BDI only governs the small fallback set; new schemes appear by ICD registration, not BDI code or vocabulary changes.
• Cons: Numeric ICD codes are opaque to humans; two namespaces once the fallback is needed; the iso6523 URN namespace identifier is not IANA-registered (see Consequences).

Option 4: HTTPS dereferenceable URIs

• Description: Linked-Data style identifiers: https://id.bdinetwork.org/legal-id/kvk/68750110. The scheme URI serves documentation and validation rules when dereferenced.
• Pros: Dereferenceable — scheme metadata, validation rules, and trust-level mappings can be served at the URI; aligns with Gaia-X / W3C practice.
• Cons: Ties the identifier schema to ownership and uptime of a domain; longer strings; requires hosting infrastructure and content governance before the first identifier can be minted.

Decision Outcome

Chosen option: Option 3 — ISO 6523-anchored URN with BDI fallback namespace.

URI Grammar

urn:iso6523:<icd>[:<value>]            primary: scheme has an ISO 6523 ICD code
urn:bdi:legal-id:<token>[:<value>]     fallback: scheme has no ICD code

• <icd> — four-digit ISO 6523 International Code Designator.
• <token> — lowercase scheme token from the BDI-governed fallback vocabulary below.
• <value> — the identifier value, normalised per scheme (see normalisation rules). Optional: a URI without the value part denotes the identifier scheme itself — used in onboarding forms, query filters, and validation-source configuration. Persisted LegalEntityIdentifier records always carry the value.

Scheme Mapping

Current IdentifierType enum values map as follows:

Type	Scheme URI	Example
KVK (NL Chamber of Commerce)	urn:iso6523:0106	urn:iso6523:0106:68750110
KBO (BE Crossroads Bank for Enterprises)	urn:iso6523:0208	urn:iso6523:0208:0439291125
LEI (GLEIF)	urn:iso6523:0199	urn:iso6523:0199:529900T8BM49AURSDO55
EUID (BRIS)	urn:bdi:legal-id:euid	urn:bdi:legal-id:euid:NLNHR.68750110
EORI (EU customs)	urn:bdi:legal-id:eori	urn:bdi:legal-id:eori:NL123456789
VAT (VIES format, country-prefixed)	urn:bdi:legal-id:vat	urn:bdi:legal-id:vat:NL861785721B01
HRB (DE Handelsregister)	no own scheme — represent as EUID	urn:bdi:legal-id:euid:DEK1101R.HRB116737

A raw HRB number is ambiguous without its register court (the same HRB 116737 exists at multiple Amtsgerichte). The EUID form encodes the court (DEK1101R), and the enrichment pipeline already produces this form, so German register entries are represented as EUID rather than getting a fallback token of their own.

Extensibility examples — usable immediately, no vocabulary or code change needed:

Scheme	Scheme URI
GS1 GLN (global)	urn:iso6523:0088
DUNS (global)	urn:iso6523:0060
Australian ABN	urn:iso6523:0151
Japanese Corporate Number	urn:iso6523:0188

Normalisation Rules

To make exact-match lookup reliable, identifiers are normalised before persistence or comparison:

• The URN prefix and scheme part are lowercase (urn:iso6523:0106, not URN:ISO6523:0106).
• The value part keeps the casing the issuing scheme defines (LEI and VAT uppercase; EUID as issued by BRIS).
• Whitespace and presentation separators are stripped from the value (KVK 687 501 10 → 68750110).
• Per-scheme syntax validation (KVK: 8 digits; LEI: 20 chars ISO 17442 incl. checksum; VAT: VIES country-prefixed format) is applied where a validator is available.

Rationale

• Business alignment: CTN onboards across borders; the enrichment architecture already integrates Peppol, GLEIF, and BRIS. Anchoring on the same scheme registry those ecosystems use avoids a translation layer at every boundary.
• Global, not European: ISO 6523 is frequently mistaken for a European registry because Peppol popularised it there. The ICD list covers global schemes (DUNS, GLN) and national schemes far beyond the EU (AU, JP, SG, MY); Peppol authorities on those markets keep extending it. Non-European onboarding does not require BDI action.
• Minimal governance surface: BDI governs only the fallback token vocabulary (euid, eori, vat at present). Everything else is delegated to the ISO 6523 registration authority.
• Risk assessment: the main risk is the unregistered iso6523 URN namespace (see Negative consequences); mitigated by a documented, trivial mapping to the Peppol canonical form.

Consequences

• Positive:
  • New identifier schemes are configuration/data, not code.
  • A single string is the identifier — APIs, tokens, logs, and audit records carry one self-describing value.
  • Zero-translation interop with Peppol participant identifiers: urn:iso6523:0106:68750110 ↔ iso6523-actorid-upis::0106:68750110 is a mechanical prefix swap.
• Negative:
  • The iso6523 URN namespace identifier (NID) is not IANA-registered. These URIs are well-formed URNs syntactically but not resolvable through IANA registries. Peppol’s own canonical participant-identifier form (iso6523-actorid-upis::<icd>:<value>) is the registered interchange format; the bidirectional mapping is trivial and must be applied at Peppol boundaries.
  • Numeric ICD codes are opaque to humans; UI and documentation must render a display name (from a scheme metadata table) next to the raw URI.
  • Two namespaces (urn:iso6523: and urn:bdi:legal-id:) once a fallback scheme is involved; consumers must accept both.
• Neutral:
  • A scheme metadata table (display name, validation pattern, issuing registry, validation source) is needed regardless of the chosen option; this ADR makes the scheme URI its natural key.
  • Should ICD codes be registered later for EORI or EUID, the fallback URIs can be migrated by a one-time data update; both forms can be temporarily accepted as aliases.

Implementation Plan

The model is greenfield (pre-release). Changes are with respect to setup documents in arc42. An exploratory implementation of Phase 1 exists on branch feat/asr-panache-entities.

1. Phase 1 — model shape (decided; implemented exploratorily):
   • LegalEntityIdentifier drops the IdentifierType enum, the identifier_value column, and the registry_name column (the issuing registry is a property of the scheme, derivable from the scheme-metadata table — Phase 2 — not a per-row attribute).
   • It gains a single identifier_uri column: String, NOT NULL, globally unique (a business register identifier denotes exactly one legal entity). A richer value-object type is deferred — see Phase 2.
   • validation_status is kept as an enum (orthogonal to the scheme). validation_source is knowingly kept as a code-bound enum pending Phase 3.
   • Repository access patterns: findByIdentifierUri (exact, index-friendly) and listByScheme (prefix match on the scheme URI, e.g. identifier_uri LIKE 'urn:iso6523:0106:%').
   • Open (Phase 2 migration concern): the global-uniqueness constraint interacts with soft-delete (is_deleted). Resolve by either a partial unique index (WHERE is_deleted = false) or by tombstoning the URI on soft-delete. Not decided here.
   • Caveat: with no parser/validator yet, the entity is a plain holder that trusts callers to supply an already-normalised URI. Normalisation/validation arrives in Phase 2.
2. Phase 2: Add a parser/builder helper (split scheme URI / value, normalise, validate per scheme) plus the scheme metadata table keyed by scheme URI (display name, validation pattern, issuing registry, validation source). The preferred eventual type for identifier_uri is a value object (e.g. a record mapped via AttributeConverter) that encapsulates this parsing — promoting the Phase-1 String once the grammar helper exists.
3. Phase 3: Apply the same pattern to ValidationSource (also flagged in ISSUES.md) — validation sources become URIs reusable across schemes; candidate for a follow-up ADR. Until then the ValidationSource enum is retained deliberately.

Compliance and Validation

• Security review completed
• Performance impact assessed
• Integration impact evaluated
• Documentation updated
• Stakeholder approval obtained

Related Documents

• 00004-naming-follows-glossary.md — scheme display names follow the glossary
• Identifier enrichment architecture — EUID generation, Peppol/GLEIF/VIES integration
• asr-service/src/main/java/org/bdinetwork/asr/model/ISSUES.md — model review items driving this decision
• ISO/IEC 6523 — Structure for the identification of organizations and organization parts; ICD list
• Peppol Policy for use of Identifiers — EAS/ICD code usage, canonical participant identifier form
• EUID structure (BRIS) — country + register + registration number

Status History

Date	Status	Notes
2026-06-05	Proposed	Initial proposal