Add reference field

descriptor.md

@@ -44,6 +44,11 @@ The following fields contain the primary properties that constitute a Descriptor
     This OPTIONAL property contains arbitrary metadata for this descriptor.
     This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
 
+- **`reference`** *descriptor*
+
+    This OPTIONAL property contains a descriptor is the subject of the content described by this descriptor.
+    This is used to associate multiple pieces of content.
+
 Descriptors pointing to [`application/vnd.oci.image.manifest.v1+json`](manifest.md) SHOULD include the extended field `platform`, see [Image Index Property Descriptions](image-index.md#image-index-property-descriptions) for details.
 
 ### Reserved
@@ -176,6 +181,21 @@ In the following example, the descriptor indicates that the referenced manifest
 }
 ```
 
+In the following example, the descriptor indicates that the referenced manifest is retrievable from a particular URL:
+
+```json
+{
+  "mediaType": "application/vnd.example.signature+json",
+  "size": 3514,
+  "digest": "sha256:19387f68117dbe07daeef0d99e018f7bbf7a660158d24949ea47bc12a3e4ba17",
+  "reference": {
+    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
+    "size": 1201,
+    "digest": "sha256:b4f9e18267eb98998f6130342baacaeb9553f136142d40959a1b46d6401f0f2b"
+  }
+}
+```
+
 [rfc3986]: https://tools.ietf.org/html/rfc3986
 [rfc4634-s4.1]: https://tools.ietf.org/html/rfc4634#section-4.1
 [rfc4634-s4.2]: https://tools.ietf.org/html/rfc4634#section-4.2

image-index.md

@@ -97,6 +97,11 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
     See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
+- **`reference`** *descriptor*
+
+    This OPTIONAL property contains a [descriptor](descriptor.md) is the subject of the content described by this descriptor.
+    This is used to associate multiple pieces of content.
+
 ## Example Image Index
 
 *Example showing a simple image index pointing to image manifests for two platforms:*

manifest.md

@@ -72,6 +72,11 @@ Unlike the [image index](image-index.md), which contains information about a set
 
     See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
+- **`reference`** *descriptor*
+
+    This OPTIONAL property contains a [descriptor](descriptor.md) is the subject of the content described by this descriptor.
+    This is used to associate multiple pieces of content.
+
 ## Example Image Manifest
 
 *Example showing an image manifest:*

specs-go/v1/descriptor.go

@@ -39,6 +39,9 @@ type Descriptor struct {
 	//
 	// This should only be used when referring to a manifest.
 	Platform *Platform `json:"platform,omitempty"`
+
+	// Reference refers to the subject of this descriptor.
+	Reference *Descriptor `json:"reference,omitempty"`
 }
 
 // Platform describes the platform which the image in the manifest runs on.

specs-go/v1/index.go

@@ -26,4 +26,7 @@ type Index struct {
 
 	// Annotations contains arbitrary metadata for the image index.
 	Annotations map[string]string `json:"annotations,omitempty"`
+
+	// Reference refers to the subject this image index.
+	Reference *Descriptor `json:"reference,omitempty"`
 }

specs-go/v1/manifest.go

@@ -29,4 +29,7 @@ type Manifest struct {
 
 	// Annotations contains arbitrary metadata for the image manifest.
 	Annotations map[string]string `json:"annotations,omitempty"`
+
+	// Reference refers to the subject this image manifest.
+	Reference *Descriptor `json:"reference,omitempty"`
 }