Skip to main content
Version: V2-Next

ADR 059: Versioned references and a version-precise dependency graph

Date: 2026-07-15

Status: Accepted

Decision Makers: @derlinne, @luckey

Context​

Different versions of an artifact can have different dependencies, so a logical-only graph is not enough.

Decision​

Versioning is a first-class concept for all artifact types, and references between artifacts are version-precise.

  • Every type (element, datastructure, dataset, mapping, pipeline, datasource, datasink) supports version enumeration, version-addressed reads (…:1.0.0 ids) and version-aware navigation.
  • A reference URN is stored verbatim: it pins a concrete version (…:Foo:1.0.0) to track the target's current version.
  • The dependency graph is version-precise: nodes are versioned URNs, edges are verbatim, and the dependency endpoints report concrete versioned IDs.
  • A rename is a patch-version bump that records title/description as versioned metadata, format-independently (XSD included).

Rationale​

  • Different versions of an artifact can have different dependencies; a logical-only graph collapses them and cannot express "track the latest" versus "pin a version".
  • Storing references verbatim preserves the authored intent, and reads resolve it to a concrete version deterministically.

Mechanism​

  • artifact_version carries primary_format plus versioned title/description; artifact_reference carries the verbatim target_urn plus a resolved target_artifact_id and, for a pin, target_version_id — both back-filled as targets appear. ArtifactRegistry.resolveReference maps a reference to its concrete versioned target.

Consequences​

The dependency queries (dependencies, dependents) report versioned IDs. List reads stay current-oriented but expose concrete versions so clients can pin.

See also​

  • ADR 057: Backend-owned SemVer versioning
  • ADR 058: Format-agnostic Elements with versioned representations