Skip to main content
Version: V2-Next

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 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​

SegmentMeaningIn the example below
urn:coreThe CORE namespace — the only part the parser enforces, besides the positional layouturn:core
scopeScope of validity: platform, tenant, standard, dataset, projecttenant
ownerThe publisherstadt-muenster
artifact-typeThe artifact type, and the domain term itself (ADR 060): element, datastructure, mapping, pipeline, datasource, datasink, datasetelement
domainDomain hierarchy, dot-separatedmobility.parking
nameReadable technical nameParkingSensor
disambiguator10 base36 characters in a segment of their own, so two artifacts with the same display name cannot collide and name stays readablep4q8r2s6tu
versionSemVer; 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-type segment values
  • ADR 059: Versioned references and a version-precise dependency graph