ADR 050: URN-based global identities

Date: 2026-07-15

Status: Accepted

Decision Makers: @derlinne, @luckey

Context

Artifacts need a stable identity that is independent of storage location, API endpoint or registry technology.

Decision

All artifacts carry a URN of the form urn:core:<scope>:<owner>:<type>:<domain>:<name>:<disambiguator>:<version>.

Rationale

• Global stability: an artifact's identity is independent of storage location, API endpoint or registry technology.
• Versioning is part of the identity (...:1.0.0).
• JSON Schema $id and $ref with URN values are valid JSON Schema — no proprietary format.
• The logical URN (without version) is the artifact's stable identity; the version segment maps to a stored artifact_version.
• The identity (a CORE URN) is passed as an explicit parameter — the facade takes the URN as a plain method argument.

The segments

Segment	Meaning	In the example below
urn:core	The CORE namespace — the only part the parser enforces, besides the positional layout	urn:core
scope	Scope of validity: platform, tenant, standard, dataset, project	tenant
owner	The publisher	stadt-muenster
artifact-type	The artifact type, and the domain term itself (ADR 060): element, datastructure, mapping, pipeline, datasource, datasink, dataset	element
domain	Domain hierarchy, dot-separated	mobility.parking
name	Readable technical name	ParkingSensor
disambiguator	10 base36 characters in a segment of their own, so two artifacts with the same display name cannot collide and name stays readable	p4q8r2s6tu
version	SemVer; imported standards may carry two segments (1.7)	1.0.0

The value sets are platform convention, not parser-level constraints. An Element's exchange format is deliberately not a segment — both JSON Schema and XSD Elements use the element type (ADR 058), and a caller-supplied urn:core:…:xsd:… is rejected.

Example

urn:core:tenant:stadt-muenster:element:mobility.parking:ParkingSensor:p4q8r2s6tu:1.0.0

Dropping the version segment yields the logical URN — the artifact's stable identity, the registry key and the cache key:

urn:core:tenant:stadt-muenster:element:mobility.parking:ParkingSensor:p4q8r2s6tu

A reference may pin a concrete version or use the latest token to track the target's current version; latest is a valid reference target and read id, never a writable identity. The authoritative details — value sets, minted vs. derived disambiguators, latest resolution and the two-segment versions of imported standards — are in URN Format.

See also

• URN Format
• ADR 060: Canonical domain vocabulary — the artifact-type segment values
• ADR 059: Versioned references and a version-precise dependency graph