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
$idand$refwith 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 URNCORE URNThe global identity Model Management assigns to every model artifact: a unique, stable and versionable URN that exists independently of storage location, file names or registry technology.) 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 XSDXML Schema DefinitionA W3C language for describing the structure of XML documents. Model Management imports XSD into JSON Schema and can serialize an Element as 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-typesegment values - ADR 059: Versioned references and a version-precise dependency graph