image-index: add the subject field

Fixes: #1002

This allows for an image-index / manifest-list (_still_ the better name
than "image-index" ...) to point to the blob of another manifest.
This is a part of the referrer API in the distribution-spec.

Signed-off-by: Vincent Batts <[email protected]>

Author: vbatts

image-index.md

@@ -87,6 +87,11 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
   If multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used.
 
+- **`subject`** *[descriptor](descriptor.md)*
+
+    This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
+    This value, used by the [`referrers` API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers), indicates a relationship to the specified manifest.
+
 - **`annotations`** *string-string map*
 
     This OPTIONAL property contains arbitrary metadata for the image index.

schema/image-index-schema.json

@@ -15,6 +15,9 @@
       "description": "the mediatype of the referenced object",
       "$ref": "defs-descriptor.json#/definitions/mediaType"
     },
+    "subject": {
+      "$ref": "content-descriptor.json"
+    },
     "manifests": {
       "type": "array",
       "items": {

specs-go/v1/index.go

@@ -27,6 +27,9 @@ type Index struct {
 	// Manifests references platform specific manifests.
 	Manifests []Descriptor `json:"manifests"`
 
+	// Subject is an optional link from the image manifest to another manifest forming an association between the image manifest and the other manifest.
+	Subject *Descriptor `json:"subject,omitempty"`
+
 	// Annotations contains arbitrary metadata for the image index.
 	Annotations map[string]string `json:"annotations,omitempty"`
 }