OCI Referrers is a mechanism introduced in the OCI Image and Distribution Specification v1.1 (finalised 2024) that allows arbitrary artifacts — signatures, SBOMs, vulnerability scan reports, attestations, provenance documents — to be attached to an existing image in a registry without modifying the image itself and without requiring out-of-band storage or tag conventions. The attachment is expressed through a subject field added to any OCI manifest: a descriptor pointing to the digest of the target image. The registry then indexes these relationships, and the referrers API makes them discoverable.
The mechanics are straightforward. An artifact manifest carrying a subject field is pushed to the same repository as the image it annotates; conformant registries respond with an OCI-Subject header confirming the relationship was recorded. To discover what is attached to a given image, any client issues a GET /v2/<name>/referrers/<digest> request; the registry returns an OCI Image Index whose descriptors point to all manifests with that digest as their subject. Each descriptor in the response carries an artifactType field — a media type string identifying what kind of artifact it is (e.g. application/vnd.dev.cosign.artifact.sig.v1+json for a cosign signature, application/spdx+json for an SPDX SBOM) — enabling clients to filter the response to only the artifact types they need without fetching everything. For registries that do not yet implement the referrers API, a client-side fallback exists: the client maintains a tag derived from the subject digest (replacing : with -) that points to an equivalent index, preserving interoperability with older infrastructure at the cost of requiring client-side writes.
The practical effect is a content-addressed, registry-native supply chain graph. Cosign uses referrers to attach signatures and attestations (including SLSA provenance) to images without the tag mutation that cosign:sha256-<digest>.sig tags previously required. ORAS uses referrers to attach arbitrary files — Helm charts, OPA policies, licence documents — as first-class registry objects linked to the images they govern. bootc and image-based Linux tooling can attach OS-level SBOMs and attestation bundles to OS image releases, queryable by any tool that speaks the distribution spec. Because the subject relationship is expressed as a content-addressed digest, the attachment is immutable and tamper-evident: a referrer can only claim to be attached to an image it actually knows the digest of, and the image’s own digest — and therefore its referrers list — changes if the image changes. The referrers API is the OCI ecosystem’s answer to the question of how supply chain metadata travels with an image through promotion across registries and deployment into production.