Define image manifest artifactType and guidance

[sudo-bmitch]

This adds an artifactType field in the image manifest, defines a scratch media type, and provides guidance on using the image manifest for artifacts. This design is based on the discussions from the 2023-03-23 meeting.

[sajayantony]

Overall, there seemed to be consensus on the call and a desire to move forward with artifactType being defined in the image manifest so that referrers can release.

I would love for OCI to remove the requirements for Layers clearer in 2.0. But that is for another day.

[mikebrow]

should we add artifactType here..

[sudo-bmitch]

When config.mediaType is defined to something other than scratch, artifactType is optional.

[AaronFriel]

To be slightly prescriptive about best practices, should we say that non-image artifacts SHOULD use an artifactType with the scratch config?

Not a MUST.

[sudo-bmitch]

@AaronFriel I'm open to it, but in case there are other opinions, how about we make that a separate PR. Would you like to lead that?

[jonboulle]

I am not sure if it was part of the discussion I missed (but even if so, I think the explanation should stand here alone): why would I choose to use scratch+artifactType, rather than just setting config.mediaType to whatever specific value I want to use?

[AaronFriel]

I expect any artifact producing implementation that doesn't need or want a config will use a scratch manifest.

Suppose you just want to upload an SBOM, or a cat gif (image/gif). What do you put in config.mediaType?

If you chose image/gif, some implementations might try to render the config as a gif, or save it as a .gif file on download, etc. The config descriptor however won't point to a gif blob, it'll point to {} and the first layer will be the image/gif.

[sudo-bmitch]

@jonboulle the issue that was raised is the config.mediaType must reference the content of the config.digest blob according to the descriptor spec. By using that for artifacts that do not have a dedicated config blob, we have a mismatch between the media type of the blob and the artifactType of the artifact.

[jonboulle]

Sorry, I might have asked the question backwards :)
In what circumstance would I set config.mediaType to something other than scratch or an actual (``application/vnd.oci.image.config.v1+json`) config? Is there a use case there we really need to support?

[sudo-bmitch]

There are actual configs that are not application/vnd.oci.image.config.v1+json, e.g. Helm charts and Singularity images. These use cases are following the guidance at https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md. My goal was to avoid breaking those existing artifacts unless there's a strong need to do so.

[jonboulle]

Thanks, that's the exact reference that was missing for me. I will think about it for another moment; I would rather it's captured more explicitly here

[andaaron]

Hi all,

I have some questions on how the artifactType in this PR would be used by the referrers API /v2/<name>/referrers/<digest>.

Given this PR, I would expect /v2/<name>/referrers/<digest> to return a mix of matches on both config descriptor mediaType and artifactType (if and only if config descriptor mediaType is scratch). Is this correct?

In the server reply the artifactType field the value returned would sometimes be from config descriptor mediaType, and sometimes from artifactType, depending on the individual artifact?

Also if this is the case, I would expect the artifactType query parameter in /v2/<name>/referrers/<digest>?artifactType=<artifactType> to match sometimes the config mediaType and sometimes the artifactType.

It doesn't seem consistent for the consumer of the API.

[sudo-bmitch]

@andaaron the update to the referrers API is in distribution-spec: opencontainers/distribution-spec#395

[sajayantony]

We can add the the case for helm or backwards as per @jonboulle comment as a follow up if needed

[tianon]

In jq, this means consumers looking to query artifactType should use an expression something like .artifactType // .config.mediaType, but the benefit is that it allows the config blob's descriptor to be "pure" and actually describe the blob it points to instead of the object it's part of, so I'm in favor.