Clarify that "Image Layout" is OPTIONAL

[AkihiroSuda]

The current image spec explicitly says that "This layout MAY be used in a variety of different transport mechanisms" (image-layout.md).

However, it doesn't explicitly say that "This layout is OPTIONAL" (regardless to the transportation).

Actually, I was rather misunderstanding that using the layout were "REQUIRED but not specific to a certain transport mechanism", and got confused for that index.json is REQUIRED (image-layout.md) for layout but OPTIONAL (image-index.md)for image providers. (#716, #719)

So I'd like to open a PR as follows:

diff --git a/image-layout.md b/image-layout.md
index 0c762c1..5351150 100644
--- a/image-layout.md
+++ b/image-layout.md
@@ -1,6 +1,7 @@
 ## OCI Image Layout Specification

 * The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs).
+* Conformity to this layout specification is OPTIONAL unless an image contains `oci-layout` file.
 * This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).

 Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/bundle.md) by:

[wking]

On Fri, Aug 04, 2017 at 05:37:26AM +0000, Akihiro Suda wrote: * The OCI Image Layout is a slash separated layout… +* Conformity to this layout specification is OPTIONAL unless an image contains `oci-layout` file.

I'd recommend we make explicit that this is a consumer requirement. And “conformance” is not negotiable; you get to choose whether you attempt to implement a feature or not, but if you attempt to implement it you must be compliant (this is probably the reason for your “unless …”, although that doesn't explicitly say REQUIRED in the has-an-oci-layout-file case). And we also coin a formal name for this feature in the previous line. So I'd prefer something like: Consumer support for OCI Image Layouts is OPTIONAL.

[AkihiroSuda]

Maintainers PTAL?

[stevvooe]

@AkihiroSuda Where does it say that image layout is required? One should be able to use "index", "manifest" and "config", without using the "image layout".

Having an image layout is not required for making an OCI compliant image. You can have an OCI image that just uses the above types in another storage context and that is still an OCI image because it uses those types.

An "image layout" is just a tool for transmitting a set of related blobs. There are better transports to do that.

[AkihiroSuda]

Where does it say that image layout is required?

Nowhere, and the issue is that the spec neither saying the layout is required nor optional explicitly.
I know the layout is optional, but it is really hard to understand that without explicitly written spec.

[stevvooe]

@AkihiroSuda Would it be enough to enumerate use cases of the image layout?

The front matter for the image layout is a little confusing, in that regard.

[AkihiroSuda]

I think yes

[sudo-bmitch]

Would it be enough to enumerate use cases of the image layout?

The front matter for the image layout is a little confusing, in that regard.

We have a list in the second bullet:

• This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync).

Is there phrasing that needs to be changed there to make it easier to understand?

[tianon]

IMO it's pretty clear that the image layout is a specification for folks who want a standard way to represent a collection of image-spec objects in a filesystem or filesystem-like format (and the distribution-spec's lack of references to it makes that even more clear), but I'm not opposed to better front-matter if someone has some proposed wording changes (an explicit PR for bike shedding further discussion would be useful, in that case). 👍