Updates for refers and artifacts (opencontainers#16)

Signed-off-by: Brandon Mitchell <git@bmitch.net>

Signed-off-by: Brandon Mitchell <git@bmitch.net>

annotations.md

@@ -16,8 +16,11 @@ This property contains arbitrary metadata.
 
 ## Pre-Defined Annotation Keys
 
-This specification defines the following annotation keys, intended for but not limited to [image index](image-index.md) and image [manifest](manifest.md) authors:
-* **org.opencontainers.image.created** date and time on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
+This specification defines the following annotation keys, intended for but not limited to [image index](image-index.md), image [manifest](manifest.md), [artifact](artifact.md), and [descriptor](descriptor.md) authors.
+
+* **org.opencontainers.artifact.created** date and time on which the artifact was built, conforming to [RFC 3339][rfc3339].
+* **org.opencontainers.artifact.description**: human readable description for the artifact (string)
+* **org.opencontainers.image.created** date and time on which the image was built, conforming to [RFC 3339][rfc3339].
 * **org.opencontainers.image.authors** contact details of the people or organization responsible for the image (freeform string)
 * **org.opencontainers.image.url** URL to find more information on the image (string)
 * **org.opencontainers.image.documentation** URL to get documentation on the image (string)
@@ -75,3 +78,5 @@ While users are encouraged to use the **org.opencontainers.image** keys, tools M
 | | `docker.*`, `rkt.*` | No equivalent in the OCI Image Spec |
 
 [spdx-license-expression]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
+
+[rfc3339]:     https://tools.ietf.org/html/rfc3339#section-5.6

artifact.md

@@ -17,7 +17,8 @@ For the media type(s) that this is compatible with see the [matrix](media-types.
 
 - **`artifactType`** *string*
 
-  This property SHOULD specify the mediaType of the referenced content and MAY be registered with [IANA][iana].
+  This property SHOULD be used and contain the mediaType of the referenced artifact.
+  If defined, the value MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
 
 - **`blobs`** *string*
 
@@ -27,58 +28,46 @@ For the media type(s) that this is compatible with see the [matrix](media-types.
 
 - **`refers`** *string*
 
-  This OPTIONAL property specifies a [descriptor](descriptor.md) of a container image or another artifact.
-  The purpose of this property is to provide a reference to the container image or artifact this artifact is related to.
-  The "Referrers" API in the distribution specification looks for this property to list all artifacts that refer to a given artifact or container image.
+  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 additional metadata for the artifact manifest.
   This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
 
-  The following annotations MAY be used:
+  See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
-  - `org.opencontainers.artifact.description`: human readable description for the artifact
-  - `org.opencontainers.artifact.created`: creation time of the artifact expressed as string defined by [RFC 3339][rfc-3339]
-
-  Additionally, the following annotations SHOULD be used when deploying multi-arch container images:
-
-  - `org.opencontainers.platform.architecture`: CPU architecture for binaries
-  - `org.opencontainers.platform.os`: operating system for binaries
-  - `org.opencontainers.platform.os.version`: operating system version for binaries
-  - `org.opencontainers.platform.variant`: variant of the CPU architecture for binaries
-
-    Also, see [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
-
-  User defined annotations MAY be used to filter various artifact types, e.g. signature public key hash, attestation type, and SBOM schema.
+  Annotations MAY be used to filter the response from the [`referrers` API](/~https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers).
 
 ## Examples
 
-*Example showing an artifact manifest for an ice cream flavor referencing an ice cream:*
+*Example showing an artifact manifest for an example SBOM referencing an image:*
 
 ```jsonc,title=Manifest&mediatype=application/vnd.oci.artifact.manifest.v1%2Bjson
 {
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
-  "artifactType" "application/example"
+  "artifactType": "application/vnd.example.sbom.v1"
   "blobs": [
     {
-      "mediaType": "application/vnd.icecream.flavor",
+      "mediaType": "application/gzip",
       "size": 123,
       "digest": "sha256:87923725d74f4bfb94c9e86d64170f7521aad8221a5de834851470ca142da630"
     }
   ],
   "refers": {
-    "mediaType": "application/vnd.icecream",
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
     "size": 1234,
     "digest": "sha256:cc06a2839488b8bd2a2b99dcdc03d5cfd818eed72ad08ef3cc197aac64c0d0a0"
   },
-  "annotations": [
-    "org.opencontainers.artifact.description": "vanilla surprise",
-    "org.opencontainers.artifact.created": "2022-04-05T14:30Z"
-  ]
+  "annotations": {
+    "org.opencontainers.artifact.created": "2022-01-01T14:42:55Z",
+    "org.example.sbom.format": "json"
+  }
 }
 ```
 
 [iana]:         https://www.iana.org/assignments/media-types/media-types.xhtml
-[rfc-3339]:     https://tools.ietf.org/html/rfc3339#section-5.6
+[rfc6838]:      https://tools.ietf.org/html/rfc6838
+[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2

descriptor.md

@@ -53,8 +53,10 @@ The following fields contain the primary properties that constitute a Descriptor
   See [Embedded Content](#embedded-content) for when this is appropriate.
 
 - **`artifactType`** *string*
-
-  This OPTIONAL property contains the [IANA][iana] mediaType of the object when the descriptor is pointing to an [artifact manifest](artifact.md).
+
+  This OPTIONAL property contains the type of an artifact when the descriptor points to an artifact.
+  This is the value of `artifactType` when the descriptor references an [artifact manifest](artifact.md).
+  This is the value of the config descriptor `mediaType` when the descriptor references an [image manifest](manifest.md).
 
 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.
 

image-index.md

@@ -35,6 +35,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
     Implementations MUST support at least the following media types:
 
     - [`application/vnd.oci.image.manifest.v1+json`](manifest.md)
+    - [`application/vnd.oci.artifact.manifest.v1+json`](artifact.md)
 
     Also, implementations SHOULD support the following media types:
 

manifest.md

@@ -67,8 +67,8 @@ Unlike the [image index](image-index.md), which contains information about a set
 
 - **`refers`** *[descriptor](descriptor.md)*
 
-    This OPTIONAL property specifies a [descriptor](descriptor.md) of another image or [artifact](artifact.md).
-    Clients may use this property to take advantage of the [`referrers` API](/~https://github.com/oci-playground/distribution-spec/blob/pr/spec.md#endpoints), to encode a reference to a related image or artifact.
+    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*
 

specs-go/v1/annotations.go

@@ -59,4 +59,13 @@ const (
 
 	// AnnotationBaseImageName is the annotation key for the image reference of the image's base image.
 	AnnotationBaseImageName = "org.opencontainers.image.base.name"
+
+	// AnnotationArtifactCreated is the annotation key for the date and time on which the artifact was built, conforming to RFC 3339.
+	AnnotationArtifactCreated = "org.opencontainers.artifact.created"
+
+	// AnnotationArtifactDescription is the annotation key for the human readable description for the artifact.
+	AnnotationArtifactDescription = "org.opencontainers.artifact.description"
+
+	// AnnotationReferrersFiltersApplied is the annotation key for the comma separated list of filters applied by the registry in the referrers listing.
+	AnnotationReferrersFiltersApplied = "org.opencontainers.referrers.filtersApplied"
 )