Skip to content

Versioning

This page explains how OCX tags, variants and platforms compose into a single package identifier.

Every binary package has three dimensions: what it is, which version, and which platform build. Most ecosystems handle these separately and leave the coordination to the consumer. Apt uses arch suffixes and ports mirrors. Pip uses platform-encoded wheel filenames. Bazel rules use hand-curated URL matrices.

OCX collapses all three dimensions into a single identifier. astral-sh/python-build-standalone:3.14 resolves the right binary for the current machine, verifies every layer against its digest (and the signature where a trust policy covers the package), and installs it. It needs no flags, name suffixes, or mirror configuration.

The task-oriented surface is how to choose between versions. It covers how to pick a tag, pin a digest, and override the platform.

Tags

An OCI tag is a human-readable label pointing to a specific manifest. The OCI Distribution Specification offers no notion of tag stability, because tags are mutable pointers. Structure and stability emerge from publishing conventions.

Rolling tags are a widespread pattern in container ecosystems. Docker official images use them extensively (ubuntu:24.04, node:22, nginx:latest). Semantic Versioning formalizes the same hierarchy for software releases. OCX adopts both conventions for binary packages.

OCX follows a semver-inspired hierarchy where specificity signals intent:

{major}[.{minor}[.{patch}[-{prerelease}][_{build}]]]

The _build suffix is typically a UTC timestamp like _20260216120000. It signals that the publisher considers the tag final and does not intend to re-push it. It is a convention, not a guarantee enforced by the registry.

Tag Publisher’s intent After index refresh
astral-sh/python-build-standalone:3.14.7_20260814 Do not re-push Same build (by publisher convention)
astral-sh/python-build-standalone:3.14.7 Rolling patch Highest build of 3.14.7
astral-sh/python-build-standalone:3.14 Rolling minor Newest 3.14.x build
astral-sh/python-build-standalone:3 Rolling major Newest stable 3.x build
astral-sh/python-build-standalone:latest Rolling Newest release

Build separator

Semantic Versioning uses + to delimit build metadata, for example 1.2.3+20260216. The OCI Distribution Specification restricts tags to [a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}, so the + character is not allowed.

This is a known ecosystem-wide issue (distribution-spec#154, open since 2020 and unresolved). The + also encodes as a space in URL query strings, which makes it unsafe even if registries accepted it.

OCX uses _ as the build separator, so every version string is a valid OCI tag by construction. The grammar above is fully unambiguous: . separates components, - introduces a pre-release, and _ introduces build metadata.

Input is tolerant. If you type + out of habit, OCX accepts it and normalizes it to _. For example, ocx package install astral-sh/python-build-standalone:3.14.7+20260814 installs the tag 3.14.7_20260814. The normalization happens at the earliest boundary, the identifier parser, so all downstream code sees _ only.

Variants

A binary can be built multiple ways. Examples are different optimization profiles (pgo, pgo.lto), feature toggles (freethreaded), or size trade-offs (slim). Variants describe how a binary was built, not where it runs. All variants for a given platform execute on the same host. The user chooses the variant, and it is not auto-detected.

Without variant support, publishers create separate packages (python-pgo, python-debug) to represent these build differences. That loses the semantic connection between builds of the same package.

Why not Docker’s tag-suffix convention?

Docker Hub encodes variants as tag suffixes (python:3.12-slim). This creates a parsing ambiguity with semver prereleases, because 3.12-alpha and 3.12-slim are syntactically indistinguishable.

Concourse CI’s registry image resource documents this explicitly. It resorts to a heuristic: only alpha, beta, and rc are treated as prereleases, and everything else is a variant suffix. OCX avoids this ambiguity entirely with a variant-prefix format.

OCX puts the variant name before the version, separated by a hyphen: slim-3.14.7. A variant name matches [a-z][a-z0-9.]*, so it holds lowercase letters, digits and dots only. Variants start with a letter and versions with a digit, so the boundary is unambiguous. The default variant’s tags carry no prefix. So astral-sh/python-build-standalone:3.14 names the default variant and astral-sh/python-build-standalone:slim-3.14 names the slim one.

Tag Meaning
astral-sh/python-build-standalone:3.14 Default variant at version 3.14
astral-sh/python-build-standalone:slim-3.14 Slim variant at version 3.14
astral-sh/python-build-standalone:slim-3 Newest version of the slim variant in the 3.x series
astral-sh/python-build-standalone:slim Newest version of the slim variant
astral-sh/python-build-standalone:latest Newest version of the default variant

Rolling tags cascade within their variant track. For example, slim-3.14.7 cascades to slim-3.14, then slim-3, then slim. Variants never cross: publishing a new slim build never updates the default variant’s tags. See Cascades for the full cascade model.

Aliasing onto the bare track is opt-in, not automatic. ocx package push --default lets the pushed tag’s own variant also own the un-prefixed track. That produces unadorned rolling tags alongside its own prefixed ones. With --cascade, the bare 3.14.7 → 3.14 → 3 → latest track cascades too. Without --default, a variant-prefixed push never touches the bare track.

Cascades

Publishers are expected to maintain the full tag hierarchy. When a build such as astral-sh/python-build-standalone:3.14.10_<build> is released, all rolling ancestors are re-pointed. This happens only if the release is genuinely the highest version at each specificity level:

python-build-standalone:latest ← rolling — updated
↓
python-build-standalone:3 ← rolling — updated
↓
python-build-standalone:3.14 ← rolling — updated
↓
python-build-standalone:3.14.10 ← rolling — updated
↓
python-build-standalone:3.14.10_<build> ← source of truth

Publishing a new 3.13 patch build updates astral-sh/python-build-standalone:3.13 but not astral-sh/python-build-standalone:3 or astral-sh/python-build-standalone:latest. The 3.14.x series is still ahead. Rolling tags only advance, never regress.

This is a publishing convention, not a guarantee enforced by the registry. Publishers must maintain the cascade manually, or have OCX do it for them.

Cascades operate within a single variant track. Publishing slim-3.14.7 updates slim-3.14, slim-3, and slim. It never touches the default variant’s tags (3.14, 3, latest) or any other variant’s tags. The --default flag opts a variant-prefixed push into also aliasing the bare track, mirroring the variant-prefixed chain under --cascade. See Variants for details.

Because cascading is a publishing convention rather than a registry-enforced rule, the chain above can also drift silently. A transient registry error partway through a cascade push can leave one rolling-tag level un-repointed. For example, astral-sh/python-build-standalone:3 still points at last week’s build even though astral-sh/python-build-standalone:3.14.7 published successfully as a newer version at that level.

Nothing about ordinary resolution notices this. A rolling tag that resolves to some valid manifest looks the same whether or not it is the highest one.

ocx package cascade check closes that gap by re-deriving what every rolling tag should point to. It does not trust the push that maybe updated the rolling tag. It folds over every published version. For a given rolling tag and platform, the expected build is the highest version under that rolling tag which publishes the platform at all.

Diffing the registry’s actual tags against that fold finds exactly the rolling tags a swallowed push error left behind. ocx package cascade repair rewrites the affected rolling-tag image indexes to match.

Platforms

The OCI image index specification defines a multi-platform manifest format. It allows multiple platform builds to live under a single tag, with the same repository name for all of them.

When you install a package, OCX reads your running system and selects the matching build automatically. It needs no flags, no configuration, and no separate repository per architecture.

System Detected as
Linux on x86-64 linux/amd64
Linux on ARM (Graviton, Ampere, RPi 4+) linux/arm64
macOS on Intel darwin/amd64
macOS on Apple Silicon darwin/arm64
Windows on x86-64 or ARM windows/amd64, windows/arm64

If a package publishes an any-platform build with no platform field in the manifest, OCX uses it as a fallback. This is common for interpreted runtimes and truly portable binaries.

Richer platform descriptors

The OCI platform model supports finer-grained descriptors for precise compatibility targeting:

  • variant: CPU sub-architecture. For ARM: v6, v7 (32-bit), v8 (64-bit / arm64). OCX selects the most specific match.
  • os.features: OS capability flags, for example win32k for Windows container isolation modes.
  • features: Reserved for future platform extensions in the OCI spec.

OCX matches all declared fields when selecting among manifest entries. The directed compatibility relation and scoring are documented in Platforms. See the OCI image index specification for the complete field reference.

Locking

The most direct lock is a digest. nodejs/node@sha256:abc123… bypasses the local index entirely and identifies an exact binary regardless of what any tag points to. All installed bytes are content-addressed, so every package can be pinned this way. It needs no lock files and no registry queries, just the hash.

For most use cases, the local index already provides the lock. Tags resolve to the digest recorded at last update. That mapping does not change until ocx index update runs. A CI runner that never updates its local index gets the same binary on every run.

For tool authors distributing OCX-powered workflows, there is a more ergonomic option. The local index holds only manifest metadata: small JSON files, with no layer archives and no binaries. It can therefore be shipped inside a GitHub Action, Bazel Rule, or DevContainer Feature.

The result is a two-level lock. The tool version locks the local index, which locks the resolved binary. Users pin the tool and get deterministic builds without managing digests, platform conditionals, or separate lock files.

The full pattern lives in Indices. It covers shipped copies, OCX_INDEX, the --remote and --offline interaction, and the Dependabot and Renovate flow.

See Also