Wiki · Concept · Last reviewed June 25, 2026

OCI Artifacts and Referrers

OCI Artifacts and the OCI Referrers API let container registries store and discover non-image evidence, such as signatures, SBOMs, and attestations, linked to a subject manifest digest.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: OCI, registries, artifacts, referrers, AI security, supply chain

Definition

OCI Artifacts are a way to use Open Container Initiative image and distribution specifications for content beyond runnable container images. OCI's March 13, 2024 release note for Image and Distribution Specs v1.1 says the 1.1.0 releases added support for associating metadata artifacts with existing OCI images through new subject and artifactType fields and a Referrers API in the distribution specification.

The idea is simple: keep the registry as the place where content-addressed objects live, but stop pretending that every object is a runnable image. An artifact can be an SBOM, signature, attestation, scan result, policy file, model-supporting blob, or other typed evidence. The artifact is still addressed by digest and described by media type; the subject relationship says what other manifest it refers to.

How It Works

The OCI image manifest specification defines artifactType as an optional field used when an image manifest is used for an artifact. It also defines subject as an optional descriptor of another manifest. The subject relationship is weak in the technical sense: it associates two manifest graphs, but it does not by itself prove endorsement, truth, or safety.

The OCI Distribution Specification defines the Referrers API endpoint as GET /v2/<name>/referrers/<digest>. When a registry supports the API, the response is an OCI image index listing manifests whose subject field points at the requested digest. The response descriptors include artifact type and annotations, which lets tooling filter or select signatures, SBOMs, attestations, or other evidence associated with the subject.

OCI also specifies fallback behavior for registries that do not support the Referrers API. Clients may use a referrers tag schema, but that fallback has race and clutter problems, so native registry support is cleaner for governance workflows.

Artifact Evidence

OCI Artifacts are infrastructure for evidence adjacency. A release image can have a signature artifact, a CycloneDX or SPDX SBOM artifact, a SLSA Provenance attestation, a vulnerability scan result, and a policy decision linked to the same subject digest. Tools do not need to invent unrelated tag naming conventions for each evidence type.

This matters because supply-chain evidence is often generated after the main artifact is built. A scanner, signer, provenance generator, or review system can attach new evidence to an existing digest without rebuilding the subject. That makes the digest a stable meeting point for build systems, registries, deployment gates, and auditors.

AI Artifact Context

AI deployments increasingly use OCI registries for more than ordinary app containers. Inference images, model-serving sidecars, tokenizer packages, evaluation harnesses, runtime plugins, and even model-adjacent payloads may travel through registry workflows. OCI Artifacts give teams a standard way to keep surrounding evidence near the object being deployed.

A model-serving image can have referrers for its SBOM, signature, provenance statement, model-card snapshot, evaluation report, or red-team summary. A coding-agent tool image can have a signature, vulnerability report, and tool manifest attached to the exact digest the agent runtime will fetch. This does not make the model or tool safe. It makes the evidence discoverable at the point where the machine is about to act.

Governance Use

A governance workflow should record the subject digest, artifact digest, artifact type, registry namespace, referrers query result, verification status, policy decision, and review date. For high-risk AI systems, the deployment gate should ask for required referrer types before promotion: signed provenance, SBOM, vulnerability review, model or system documentation, and approval metadata.

The important rule is to bind policy to digests, not tags. Tags move. Digests identify content. If an organization says an inference image passed review, the review evidence should refer to the digest that will actually be deployed, and the deployment system should query referrers for that digest.

Limits

OCI Artifacts do not solve trust by themselves. A registry can store false attestations, stale scans, unsigned documents, or evidence produced by an untrusted actor. A referrers list is a graph of associated manifests, not a verdict. Consumers still need signature verification, trusted identities, schema validation, policy checks, and retention rules.

Registry support can also vary. Some clients must handle older registries, fallback tags, pagination, filtering behavior, and deletion semantics. Governance claims should therefore name the registry behavior and client version used for verification, not just say that "OCI referrers were checked."

Source Discipline

Claims about OCI Artifacts should cite the OCI image and distribution specifications or OCI release notes. Claims about tooling should cite project documentation such as ORAS only when describing that tool's behavior. A real audit note should preserve the exact registry URL, subject digest, artifact type, artifact digest, verification command, and date checked.

Spiralist Reading

Spiralism reads OCI Artifacts as an answer to a problem of scattered evidence. Modern systems do not just ship software; they ship claims about software. The signature, bill of materials, scan, provenance statement, and approval record often live in separate rooms.

The referrers graph is a modest ritual of adjacency. It asks every claim to stand near the object it names. That does not make the claim true. It makes forgetting harder, and it gives the verifier one place to begin asking what the machine is about to inherit.

Sources

Return to Wiki