diff --git a/annotations.md b/annotations.md index 96f5abfd8..159ff4ee9 100644 --- a/annotations.md +++ b/annotations.md @@ -53,6 +53,9 @@ This specification defines the following annotation keys, intended for but not l - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement. - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds). - If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation. +- **org.opencontainers.image.referrer.subject** Digest of the subject referenced by the referrers response (string) + - This SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md). + - The descriptor SHOULD be the referrers response for the subject digest. ## Back-compatibility with Label Schema diff --git a/image-layout.md b/image-layout.md index 026e71ecd..df13215ce 100644 --- a/image-layout.md +++ b/image-layout.md @@ -160,6 +160,10 @@ For example, an image may have a tag for different versions or builds of the sof In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc. Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc. +**Referrers Support:** +Manifests included in an OCI Layout that contain a `subject` field SHOULD be listed in a [referrers response][referrers-response]. +The referrers response is then saved as a blob and listed in the `index.json` with the media type set to `application/vnd.oci.image.index.v1+json` and the annotation `org.opencontainers.image.referrer.subject` set to the `subject` digest value. + ### Index Example ```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson @@ -195,6 +199,14 @@ Those tags will often be represented in an image-layout repository with matching "org.freedesktop.specifications.metainfo.version": "1.0", "org.freedesktop.specifications.metainfo.type": "AppStream" } + }, + { + "mediaType": "application/vnd.oci.image.index.v1+json", + "size": 7143, + "digest": "sha256:1efe7ab979c486a5af7a29d2c4603d84a3b934a7253d61b37e8573afecf47c03", + "annotations": { + "org.opencontainers.image.referrer.subject": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd" + } } ], "annotations": { @@ -206,8 +218,9 @@ Those tags will often be represented in an image-layout repository with matching This illustrates an index that provides two named references and an auxiliary mediatype for this image layout. The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations. -Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`. +Note that the [`org.opencontainers.image.ref.name` and `org.opencontainers.image.referrer.subject` annotations](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`. The second named reference (`v1.0`) points to a manifest that is specific to the linux/ppc64le platform. [descriptors]: ./descriptor.md +[referrers-response]: https://github.com/opencontainers/distribution-spec/blob/v1.1.1/spec.md#listing-referrers diff --git a/specs-go/v1/annotations.go b/specs-go/v1/annotations.go index 581cf7cdf..607399eff 100644 --- a/specs-go/v1/annotations.go +++ b/specs-go/v1/annotations.go @@ -59,4 +59,9 @@ const ( // AnnotationBaseImageName is the annotation key for the image reference of the image's base image. AnnotationBaseImageName = "org.opencontainers.image.base.name" + + // AnnotationReferrerSubject is the annotation key for the digest of the subject referenced by the referrers response. + // This SHOULD only be considered valid when on descriptors on `index.json` within image layout. + // The descriptor SHOULD be the referrers response for the subject digest. + AnnotationReferrerSubject = "org.opencontainers.image.referrer.subject" )