Document extensibility of the image layout

[sudo-bmitch]

Implementations have been seen that error if a manifest.json is included inside the OCI Layout. This documents the extensibility of the directory structure.

See moby/moby#49141

[thaJeztah]

LGTM, thanks!

[LTek-online]

Something else that could be helpful to add it to define which file has precedence over which.
In the example of a hybrid image with both manifest.json and index.json being present, without defining precedence the outcome of reading the image can still be non deterministic between different implementations as it very much depends on the implementation as to which file will be read and interpreted.

In my case of moby/moby#49141 the tool, nexus-iq scanner, assumed that the presence of the manifest.json file means that the layers are tarred.
Purely defining that unknown files have to be accepted might not be enough in this case as the tool happily accepts unknown files within the container image as long as it's not one of the layer files.

Adding that the index.json or any other files defined in the OCI spec have precedence over the manifest.json could be helpful here.
I have to acknowledge that I'm not an expert in the OCI image spec, so if anything is wrong / incorrect please feel free to point it out to me without hesitation.

[sudo-bmitch]

Something else that could be helpful to add it to define which file has precedence over which.

I'm hesitant to do this because it would be the specification trying to claim a priority over one of the projects that happens to implement the specification. It also feels like something much more appropriate for the projects consuming the content to decide individually. Some projects may prefer the docker save format, others may want the OCI Layout, and some may make that a user choice.

In the nexus-iq bug you are experiencing, I think that's a symptom of the docker save format not having a specification, only implementations (at least I couldn't find one in my brief searching). Docker is free to change their own implementation, and they may only focus on their own tooling interoperability. There may be some value in Docker documenting the requirements for the manifest.json, but I won't be surprise if this becomes a legacy format with their transition to containerd's image storage backend.