diff --git a/descriptor.md b/descriptor.md index 2ba672d07..7a1802036 100644 --- a/descriptor.md +++ b/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 diff --git a/image-index.md b/image-index.md index 27c305318..67607868b 100644 --- a/image-index.md +++ b/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:* diff --git a/manifest.md b/manifest.md index da3b675d7..f237986f9 100644 --- a/manifest.md +++ b/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:* diff --git a/specs-go/v1/descriptor.go b/specs-go/v1/descriptor.go index 6e442a085..291d0dc61 100644 --- a/specs-go/v1/descriptor.go +++ b/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. diff --git a/specs-go/v1/index.go b/specs-go/v1/index.go index 4e6c4b236..aa478f37c 100644 --- a/specs-go/v1/index.go +++ b/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"` } diff --git a/specs-go/v1/manifest.go b/specs-go/v1/manifest.go index 7ff32c40b..aab89b463 100644 --- a/specs-go/v1/manifest.go +++ b/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"` }