I was trying to figure out docker terminology about image ID, manifests, and digests, in order to understand how docker maintains the integrity of distributed images. And there is one (of many) unexpected bit. I have just saved an existing image, untared it back, and cannot understand what is in its manifest.json file:

$ docker save 000908da321f > a.tar
$ tar -xvf ./a.tar -C a
$ ls a
blobs  index.json  manifest.json  oci-layout

Here index.json is an image index manifest that points to a specific manifest:

{
  "schemaVersion":2,
  "mediaType":"application/vnd.oci.image.index.v1+json",
  "manifests":
  [
    {
    "mediaType":"application/vnd.oci.image.manifest.v1+json",
    "digest":"sha256:dbe15f62d97cfdb1271a9612e4df8bd5d79b11404dcaed42b82e4cf796338f37",
    "size":1011
    }
  ]
}

And I can find dbe15 in a/blob/sha256/. It also makes sense: it is a mediaType manifest with a config and layers inside. And remaking the hashtags with sha256sum matches them.

But manifest.json does not follow the image spec schema. It is a list, and there is no schemaVersion and mediaType:

[
    {
        "Config": "blobs/sha256/000908da321ffa9418f599f3476fece162f3903f3f2e9fdd508c8b91ee9008ff",
        "Layers": [
            "blobs/sha256/08000c18d16dadf9553d747a58cf44023423a9ab010aab96cf263d2216b8b350",
            ...
        ],
        "LayerSources": { ... },
        "RepoTags": null
    }
]

It looks somewhat like what comes out of docker image inspect <image ID>, but not really. What is this file and is there a reason why it is called manifest.json when it does not follow the schema for an image manifest?

I was trying to figure out docker terminology about image ID, manifests, and digests, in order to understand how docker maintains the integrity of distributed images. And there is one (of many) unexpected bit. I have just saved an existing image, untared it back, and cannot understand what is in its manifest.json file:

$ docker save 000908da321f > a.tar
$ tar -xvf ./a.tar -C a
$ ls a
blobs  index.json  manifest.json  oci-layout

Here index.json is an image index manifest that points to a specific manifest:

{
  "schemaVersion":2,
  "mediaType":"application/vnd.oci.image.index.v1+json",
  "manifests":
  [
    {
    "mediaType":"application/vnd.oci.image.manifest.v1+json",
    "digest":"sha256:dbe15f62d97cfdb1271a9612e4df8bd5d79b11404dcaed42b82e4cf796338f37",
    "size":1011
    }
  ]
}

And I can find dbe15 in a/blob/sha256/. It also makes sense: it is a mediaType manifest with a config and layers inside. And remaking the hashtags with sha256sum matches them.

But manifest.json does not follow the image spec schema. It is a list, and there is no schemaVersion and mediaType:

[
    {
        "Config": "blobs/sha256/000908da321ffa9418f599f3476fece162f3903f3f2e9fdd508c8b91ee9008ff",
        "Layers": [
            "blobs/sha256/08000c18d16dadf9553d747a58cf44023423a9ab010aab96cf263d2216b8b350",
            ...
        ],
        "LayerSources": { ... },
        "RepoTags": null
    }
]

It looks somewhat like what comes out of docker image inspect <image ID>, but not really. What is this file and is there a reason why it is called manifest.json when it does not follow the schema for an image manifest?

• docker

1 Answer 1

The manifest.json is the original method to track the output of docker save. It lists the included images, their tags, and pointers needed to load the image back into a docker engine. It is a docker specific format that is not part of the OCI specifications.

What's new in the docker save output is the transition to using the OCI Image Layout that came from moby/moby PR#44833. That added the index.json, oci-layout, renamed the blobs, and gave the ability to support more use cases (compatibility with tooling and support for multi-platform images).

The two formats were compatible, so putting them both in the same docker save output allows the output to be used by older versions of Docker.

This all feels peripheral to your stated goals:

I was trying to figure out docker terminology about image ID, manifests, and digests,

The OCI image-spec covers this without needed to dissect the docker save output.

in order to understand how docker maintains the integrity of distributed images.

That's provided with Content Addressable Storage, Merkle Trees, and Directed Acyclic Graphs. I'd start by learning each of those.