The OCI image spec: index, manifest, config and layers as a Merkle DAG of descriptors

Four document types, linked by descriptors

Why does understanding the spec matter? Because when something breaks at the registry or supply-chain layer, the error message is always in spec terms — media types, descriptors, digests — and without the vocabulary you are debugging with one hand tied behind your back. The OCI Image Spec reached v1.0 in 2017, two years after the project formed in 2015 to lift Docker’s v2 schema2 manifest out of one vendor and into a neutral standard. It defines four JSON document types and one primitive that glues them together — the descriptor. A descriptor is the only way one OCI document points at another, and it is just three fields:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:7f0a3c…",
  "size": 2089
}

That is the whole linking mechanism. The mediaType says what kind of thing is at the other end, the digest is the sha256 that content-addresses it, and size is its byte length so a client can allocate and verify before it even fetches. Every reference in an OCI image — index to manifest, manifest to config, manifest to each layer — is a descriptor. The four document types it links are:

• Image index — application/vnd.oci.image.index.v1+json. The multi-arch fan-out: a list of descriptors, one per platform, each pointing at a manifest. Roughly 1–3 KB for a handful of platforms.
• Image manifest — application/vnd.oci.image.manifest.v1+json. One platform’s recipe: a config descriptor and an ordered layers array of descriptors. Typically about 2 KB.
• Image config — application/vnd.oci.image.config.v1+json. The JSON you met last lesson: Env, Entrypoint, rootfs.diff_ids, history. Its digest is the image ID.
• Layer blobs — application/vnd.oci.image.layer.v1.tar+gzip. The gzipped filesystem tarballs, the bulk of the bytes.

Pull resolves a tag to the top descriptor, fetches that document, reads the descriptors inside it, fetches those, and recurses down until it has the config and every layer.

Why it is a Merkle DAG

Because every link is a digest of the thing it points at, the references compose into a Merkle DAG — the same structure as a git commit graph. The config’s digest is computed from the config bytes. The manifest embeds that config digest plus each layer digest, so the manifest’s own digest is computed from bytes that include all of those child digests. The index embeds the manifest digests, so the index digest covers everything below it. The consequence is the property the whole supply chain leans on: change any blob and every digest above it changes. Flip one byte in a base layer and that layer’s digest changes, which changes the manifest that lists it, which changes the index that lists the manifest. You cannot alter content anywhere in the graph without the tag’s top digest moving. That is exactly why docker pull image@sha256:… is a hard guarantee: pinning the top digest pins the entire transitive set of bytes, the same way a git commit hash pins a whole tree.

The media-type war: OCI versus schema2

The descriptors only work if both ends agree on the vocabulary, and there are two vocabularies in the wild. Docker’s original is schema2: application/vnd.docker.distribution.manifest.v2+json for the manifest and application/vnd.docker.image.rootfs.diff.tar.gzip for layers. OCI’s is the application/vnd.oci.image.* family above. The bytes a layer carries are the same gzipped tar either way; only the type string differs. But old registries and old clients dispatch on that string, so an image tagged with OCI media types pushed to a registry that only codes for schema2 fails with manifest unknown or a pull error — not because anything is corrupt, but because the receiver has no handler for that mediaType. This is why build tooling exposes format flags: BuildKit’s --output type=image,oci-mediatypes=true|false and buildx’s --provenance=false (provenance attestations force an OCI index, which some registries reject). Modern Docker is OCI-compatible and, with the containerd snapshotter image store, the daemon emits OCI media types by default — which is precisely the change that surprised the team in the hook. When you hit manifest unknown against an old registry, the first move is to re-push with schema2 media types and see if the error clears.

A fifth thing rides on the same descriptor plumbing: the referrers / subject mechanism. A manifest can carry a subject descriptor pointing at another image’s manifest by digest, which attaches an artifact — a signature, an SBOM, a provenance attestation — to that image without changing its digest. The registry’s referrers API lets you ask “what is attached to sha256:…?” and get back the descriptors of every signature and SBOM. The attachment is by digest, so it inherits the same tamper-evidence: the artifact names the exact image bytes it vouches for.