Define a manifest

[SteveLasker]

There have been various interpretations for what defines a manifest.
The OCI Index has a manifests property, which some have interpreted it as meaning at least image-manifest or image-index, but could support other manifest types. It happens to store a manifest using an oci descriptor, but it's not a blob.
While buildx read it as a set of descriptors, and stores layers in the manifests list.

On the July 14, 2021 OCI call, we discussed clarifying "what is a manifest".

This issue to agree we should define a manifest in the distribution-spec as it's the distribution spec that inputs a manifest to account for the blobs that make up a "thing" and start the conversation for how registries may implement lifecycle management on those "things" (aka artifacts).

If this issue is approved, I'll make a PR to start the process of adding a description for what the role of a manifest is

[jonjohnsonjr]

It happens to store a manifest using an oci descriptor, but it's not a blob.

Can you clarify what you mean by "but it's not a blob".

This issue to agree we should define a manifest in the distribution-spec as it's the distribution spec that inputs a manifest to account for the blobs that make up a "thing" and start the conversation for how registries may implement lifecycle management on those "things" (aka artifacts).

This seems too vague to be actionable. How do you see this fitting into the spec? Should we add something like considerations.md to this repo (similar to image-spec)?

Are you trying to define a manifest from the distribution-spec perspective i.e. resources at /v2/.../manifests/<ref>? Or how distribution relates to image-spec, i.e. the manifests field in an image index?

[dmcgowan]

Manifest: a JSON document which defines an Artifact. Manifests are defined under the OCI Image Spec

The definition given for 1.0 was more about what is being done today in practice. If we were going to add a definition for a manifest in the distribution separate from the image spec, it would be more likely need to be more generic than this. JSON is kind of irrelevant from an API perspective.

The major difference from the API perspective is that a manifest is a typed blob and may have a tag.

• Manifest(Blob(size, digest), MediaType, [tag]) -> bytes
• Blob(size, digest) -> bytes

Everything related to artifacts, garbage collection references, image layers, etc is about context either defined by the client or the registry. This specification is scoped to the API for distributing the content between the client and registry. Defining anything further than that only complicates implementations and potential future use cases. That is why this specification has instead deferred and linked to specific definitions about content which MAY be distributed through this API. It does not limit what that content must look like today or in the future. From my perspective that is why we created the artifacts repository in the further place, to have a place which defines content and how it may be used by clients, registries, and be distributed using this API.

[sudo-bmitch]

I may have unknowingly resolved this one in #335 with the following:

- **Manifest**: a JSON document uploaded via the manifests endpoint. A manifest may reference other manifests and blobs in a repository via descriptors. Examples of manifests are defined under the OCI Image Spec <sup>[apdx-2](#appendix)</sup>, such as the Image Manifest, Image Index, and Artifact Manifest.</sup>

Does that resolve this issue, or should we keep this open for a follow up PR?

[vbatts]

looks like it may be resolved and no updates showing otherwise