# The OCI Distribution Spec, the HTTP API that decides how registries hand out content > The OCI Distribution Specification defines an API protocol for distributing content, and it is the layer every container registry and every container runtime in the OCI ecosystem actually agrees on. This repository holds the specification text, the Go types and a registry conformance test suite, plus a process for extending the API when the core cannot express what you need. **opencontainers/distribution-spec** — OCI Distribution Specification - Repository: https://github.com/opencontainers/distribution-spec - Website: https://opencontainers.org - Stars: 1,156 · Forks: 260 - Language: Go - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/opencontainers-distribution-spec ## A spec, some types, and a conformance suite The repository holds three distinct things, and the split explains how a specification project is different from a code project. The specification itself is in spec.md, and it is the authoritative document. Alongside it the repository provides Go types, in a specs-go directory, and registry conformance tooling, in a conformance directory. The relationship between the types and the spec is stated as a constraint: the Go types and validation should be compatible with the current Go release, and earlier Go releases are not supported. That is a strong statement to make for a types package, because it means the types are regenerated or maintained against a moving Go standard library and the project accepts the churn rather than pinning to old versions. The primary language recorded for the repository is Go, but the artefact that matters is the protocol, and the Go types are an implementation of it. ``` The Go types and validation should be compatible with the current Go release; earlier Go releases are not supported. ``` ## How it relates to the image and runtime specs The distribution spec is one of three, and the documentation is careful to explain the division of labour between them. The OCI Image Format Specification strictly defines the requirements for an OCI Image, a container image, which consists of a manifest, an optional image index, a set of filesystem layers and a configuration, and the schema for those components is fully supported by the APIs defined in the Distribution Specification. The OCI Runtime Specification defines how to properly run a container as a filesystem bundle which fully adheres to the image format, and it is relevant here because both support OCI Images and because container runtimes use the APIs defined in the Distribution Specification to fetch pre-built container images and run them. So the image spec says what an image is, the runtime spec says how to execute one, and the distribution spec says how to move one across a network. A reader new to OCI should hold those three apart, because most confusion about the distribution spec comes from expecting it to describe images. ``` strictly defines the requirements for an OCI Image (container image) ``` ## Designed for content beyond containers The Distribution Specification is also designed generically enough to be leveraged as a distribution mechanism for any type of content. The example given is manifests: the format of uploaded manifests need not necessarily adhere to the OCI Image Format Specification, so long as it references the blobs which comprise a given artifact. That sentence is the specification's most consequential design decision, and it is easy to miss because the protocol is usually described in terms of containers. A registry built to this spec can hold Helm charts, WASM modules, SBOMs, model weights or signed attestations, because the contract is about blobs, manifests and the API that moves them, not about layers and filesystems. It also means the spec deliberately does not define a content type registry, so the ecosystem relies on conventions outside the document. For anyone building a registry for something other than containers, that is the part of the spec that makes it usable and the part that leaves the most to you. ``` The format of uploaded manifests, for example, need not necessarily adhere to the OCI Image Format Specification so long as it references the blobs which comprise a given artifact. ``` ## Extensions, and the high bar they have to clear Because the core spec changes slowly, the project has a formal mechanism for extending the API. The Distribution Specification Project includes a process and API for prototyping and testing extensions to the Distribution API, and contributions, comments and reviews on those extensions are invited. The rule that decides whether an extension lives is stated plainly: these extensions will only move forward with significant support from registries, registry clients and users. That is a deliberately high bar, and it is the right one, because an API that registries implement differently is worse than no extension at all. The extensions live in their own directory in the repository with their own README describing the process, and the project keeps a content-negotiation.md file at the top level, which is the kind of thing that tells you the extension work is not theoretical. For a client implementer, the practical rule is that anything outside the core is something you should check for adoption before depending on it. ``` These extensions will only move forward with significant support from registries, registry clients, and users. ``` ## Conformance tooling, and the make targets behind it The Makefile shows how the project turns a spec into something testable. The conformance version defaults to the current commit, with an explicit epoch test commit variable that can be used to pin the suite to a known-good revision, which is the sort of knob you need when a new registry implementation appears and you want to know whether it matches the spec or matches the current main branch. The build is careful about reproducibility. Pandoc is pinned to a 3.1 release with a comment explaining that this is due to a regression, with a link to the upstream issue, before upgrading. The linter is likewise pinned to a specific golangci-lint version by digest, and both tools can be run through Docker containers if they are not installed locally, with the Docker fallback wired in only when the local binary is missing. The test target depends on a git validation step and a license check, and in GitHub the validation runs only against the commit range. ```make CONFORMANCE_VERSION ?= $(CURRENT_COMMIT) DOC_FILES := spec.md FIGURE_FILES := test: .gitvalidation check-license ``` ## The process, which is the real content of the repository More than half of this repository is process, and that is a deliberate choice for a specification project. The contributing guide, the governance document, the maintainers guide, the releases document and a FAQ are all at the top level, alongside a CODEOWNERS file and a MAINTAINERS file, and an EMERITUS.md file. The contribution rules are unusually explicit about sequence. Development happens on GitHub for the spec, with issues used for bugs and actionable items and longer discussions happening on the mailing list. Before undertaking a nontrivial change to the specification, you are asked to send mail to the mailing list to discuss what you plan to do, and the reasons are spelled out: it gives everyone a chance to validate the design, helps prevent duplication of effort, ensures the idea fits, and guarantees the design is sound before code is written, since a GitHub pull-request is not the place for high-level discussions. Typos and grammatical errors, by contrast, can go straight to a pull-request. ``` to discuss what you plan to do ``` ## Housekeeping that is itself a convention Two small rules in the repository reveal how seriously the project treats consistency. The first is the Markdown style: all files should be formatted one sentence per line, and the reason given is that this fixes two things, it makes diffing easier with git and it resolves fights about line wrapping length. That is a rule you only see in repositories where a formatting argument has actually been had, and it is cheap to follow and annoying to ignore, because a patch that reflows every paragraph makes the real change invisible. The second is the developer certificate of origin, the DCO, whose text is reproduced in full in the README, and the commit convention that follows from it: a sign-off line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on, and then a Signed-off-by line in every git commit message. The Makefile ties this together, since the test target runs a git validation step that checks the DCO and the short subject when running in GitHub. ``` To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line. ``` ## Where the work happens, and what to expect from the project The community surfaces are listed plainly. The mailing list is on Google Groups, the chat is on the OCI Slack in the general channel, and a Matrix room at opencontainers:matrix.org, and the documentation says the chat rooms are all bridged together, so joining either is enough. Meetings are covered by the OCI org repository README, which also links agendas and minutes for prior meetings. The roadmap is not a document but a set of GitHub milestones. For the specification's own history, the recent releases are v1.1.1 from 2025-01-29, v1.1.0 from 2024-02-15 and v1.1.0-rc4 from 2024-01-18, so the 1.1 line has been stable for a while, which is exactly what you want from a protocol that every registry implements. The repository is not archived, the last push was on 2026-08-31, and the licence for the specification and the code is Apache 2.0, found in the LICENSE file of the repository. ## Conclusion Adopt the OCI Distribution Specification as your reference when you implement or audit a registry, a client, or a proxy in the container supply chain, and skip it if your distribution problem is not a registry, because the spec assumes blob and manifest semantics that only make sense for content-addressed storage. Verify three things before you build against it: which version of the spec you are implementing, since the releases are versioned as v1.1.x and the extension mechanism exists precisely because the core does not change often; that your implementation passes the conformance suite in the conformance/ directory, which is the objective check available here; and that the extensions you rely on are actually adopted, since the project states that extensions will only move forward with significant support from registries, registry clients and users. ## FAQ ### What does the OCI Distribution Specification define? It defines an API protocol to facilitate and standardize the distribution of content. The specification text is in spec.md, and the repository also provides Go types and registry conformance tooling. ### How does the Distribution Spec relate to the OCI Image Format and Runtime Specs? The Image Format Spec defines what an OCI Image is, consisting of a manifest, an optional image index, filesystem layers and a configuration. The Runtime Spec defines how to run a container filesystem bundle. The Distribution Spec defines the APIs that container runtimes use to fetch pre-built images. ### Can the OCI Distribution Spec be used for content other than container images? Yes. It is designed generically enough to be leveraged as a distribution mechanism for any type of content, and the format of uploaded manifests need not adhere to the OCI Image Format Specification so long as it references the blobs which comprise a given artifact. ### How are extensions to the OCI Distribution API handled? The project includes a process and API for prototyping and testing extensions, with details in the extensions README, and extensions are invited for contribution, comment and review. They will only move forward with significant support from registries, registry clients and users. ## Sources - [License: Apache-2.0](https://github.com/opencontainers/distribution-spec/blob/main/LICENSE) - [opencontainers/distribution-spec on GitHub](https://github.com/opencontainers/distribution-spec) - [Project website](https://opencontainers.org) - [README](https://github.com/opencontainers/distribution-spec/blob/main/README.md) - [Releases](https://github.com/opencontainers/distribution-spec/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opencontainers-distribution-spec