Support referrers responses in the Image Layout

annotations.md

@@ -53,6 +53,12 @@ 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.
+- **org.opencontainers.image.referrer.convert** Defined and set to `true` when tooling has converted any referrers from the fallback tag to using the `org.opencontainers.image.referrer.subject` annotation.
+  - This SHOULD only be considered valid when on the manifest of the `index.json` within [image layout](image-layout.md).
+  - Tooling that reads an [image layout](image-layout.md) MAY skip the referrers conversion process when the annotation is detected.
 
 ## Back-compatibility with Label Schema
 

image-layout.md

@@ -155,6 +155,11 @@ 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:**
+Referrers MAY be referenced using the fallback tag if the "org.opencontainers.image.referrer.convert" annotation is not set to "true".
+Before writing descriptors with the "org.opencontainers.image.referrer.subject" annotation, implementations MUST ensure the "org.opencontainers.image.referrer.convert" annotation is set to "true" and convert any existing content referenced with the fallback tag if the annotation was not set.
+If the "org.opencontainers.image.referrer.convert" annotation is set to "true", implementations MAY skip the conversion of referrers stored with the fallback tag and depend on the "org.opencontainers.image.referrer.subject" annotation to detect any referrers.
+
 ### Index Example
 
 ```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
@@ -190,9 +195,18 @@ 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": {
+    "org.opencontainers.image.referrer.convert": "true",
     "com.example.index.revision": "r124356"
   }
 }
@@ -201,7 +215,8 @@ 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 [`org.opencontainers.image.referrer.convert` annotation](annotations.md) SHOULD only be considered valid when on manifest of the `index.json`.
 
 The second named reference (`v1.0`) points to a manifest that is specific to the linux/ppc64le platform.
 

specs-go/v1/annotations.go

@@ -59,4 +59,14 @@ 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"
+
+	// AnnotationReferrerConvert is the annotation key that is set to "true" when tooling has converted any referrers from the fallback tag to using the `org.opencontainers.image.referrer.subject` annotation.
+	// This SHOULD only be considered valid when on the manifest of the `index.json` within image layout.
+	// Tooling that reads an image layout MAY skip the referrers conversion process when the annotation is detected.
+	AnnotationReferrerConvert = "org.opencontainers.image.referrer.convert"
 )