How AI is applied across API Evangelist and APIs.io. Read my AI disclosure →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

OCI Distribution Specification

The OCI Distribution Specification defines the HTTP API a container registry exposes for pushing, pulling and discovering artifacts, including the referrers API. It is the one specification in the OCI set that is itself an HTTP API — and it ships an OpenAPI definition.

The OCI Distribution Specification is the registry API. Push, pull, blob uploads, tag listing, and the referrers API that lets you ask what else points at a given digest — signatures, SBOMs, attestations. It matters more than it looks, because it turned the container registry into general-purpose content-addressable storage that a great deal of the supply-chain stack now depends on.

  • Pull and push - Manifest and blob endpoints, with chunked and monolithic upload paths.
  • Content discovery - Tag listing, and the referrers API for finding artifacts attached to a subject digest.
  • Artifact-agnostic - Anything with a media type can be stored, which is how signatures and SBOMs ended up living next to images.
  • It has an OpenAPI - Unusual in this catalog, and worth stating plainly: the specification that defines an HTTP API describes that API in the format the industry asks everyone else to use.

That last point is why this entry is interesting beyond containers. Across the OpenAPI Standard Report, the recurring finding is that standards bodies ask implementers for machine-readable contracts more often than they publish one for their own surface. The Distribution spec is a counter-example, and a short one to point at. Companions: OCI Image and OCI Runtime.