From 3b30a776bd0975aa11a321267111b3373caedeaa Mon Sep 17 00:00:00 2001 From: Bjorn Neergaard Date: Tue, 17 Oct 2023 14:30:22 -0600 Subject: [PATCH 1/3] artifacts-guidance: better define Artifact and Image Better define images and artifacts conceptually, and add additional guidance on detecting them in code/at a data-model level. Signed-off-by: Bjorn Neergaard --- artifacts-guidance.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/artifacts-guidance.md b/artifacts-guidance.md index 49b8c634e..1185a7f26 100644 --- a/artifacts-guidance.md +++ b/artifacts-guidance.md @@ -1,6 +1,30 @@ # Guidance for Artifacts Authors -Content other than OCI container images MAY be packaged using the image manifest. -When this is done, the `config.mediaType` value should not be a known OCI image config [media type](media-types.md). -Historically, due to registry limitations, some tools have created non-OCI conformant artifacts using the `application/vnd.oci.image.config.v1+json` value for `config.mediaType` and values specific to the artifact in `layer[*].mediaType`. +## Artifacts and Images + +This specification is primarily concerned with packaging two kinds of content: Artifacts and Images. +Both are representing using a [manifest](manifest.md). +Images are defined in this specification as conformant content with a conformant [config](config.md), processed according to [conversion.md](conversion.md) to derive a [runtime-spec][] configuration blob. +Conversely, an Artifact is any other conformant content that **does not contain a config to be interpreted by a runtime-spec implementation using the conversion mechanism. + +## Creating an Artifact + +Content other than Images MAY be packaged using the [manifest]; this is otherwise known as an Artifact. +When this is done, the `artifactType` should be set to a custom media type, or the `config.mediaType` should not be a known Image config [media type](media-types.md). Implementation details and examples are provided in the [image manifest specification](manifest.md#guidelines-for-artifact-usage). + +Note: Historically, due to registry limitations, some tools have created non-conformant Artifacts using the `application/vnd.oci.image.config.v1+json` value for `config.mediaType`. + +## Interacting with Artifacts + +Software following the process described in [conversion.md](conversion.md) to create a [runtime-spec][] configuration blob SHOULD ignore unknown Artifacts (as determined by the presence of a descriptor `artifactType`) when selecting content from an [index](image-index.md). +It is possible that implementations may also be able to interpret known Artifact types; however that is outside the scope of this spec. + +Artifacts can be detected at runtime using by checking two keys: +1. Is an `artifactType` present in the descriptor, or in the [manifest](manifest.md)? +2. Is the `config.mediaType` of the manifest something other than a [known media type](media-types.md) for [config](config.md)? + +If either of these tests is true, then the content is an Artifact. + +[runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/main/spec.md + From 035b0a6ae0dbe799f5f6a33b1543bd8ceee642da Mon Sep 17 00:00:00 2001 From: Bjorn Neergaard Date: Tue, 17 Oct 2023 14:34:55 -0600 Subject: [PATCH 2/3] descriptor: clarify value of artifactType field Signed-off-by: Bjorn Neergaard --- descriptor.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptor.md b/descriptor.md index 455db1efa..0dc349b31 100644 --- a/descriptor.md +++ b/descriptor.md @@ -54,8 +54,8 @@ The following fields contain the primary properties that constitute a Descriptor - **`artifactType`** *string* - This OPTIONAL property contains the type of an artifact when the descriptor points to an artifact. - This is the value of the config descriptor `mediaType` when the descriptor references an [image manifest](manifest.md). + This OPTIONAL property contains the type of an artifact when the descriptor points to an [artifact](artifacts-guidance.md). + This property MUST be the same as the `artifactType` of the referenced [manifest](manifest.md), or the `mediaType` of the `config` descriptor if an `artifactType` is not set. 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]. 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. From 75c75e5dd65ab01a66c9c4571f6874999011faeb Mon Sep 17 00:00:00 2001 From: Bjorn Neergaard Date: Tue, 17 Oct 2023 14:36:55 -0600 Subject: [PATCH 3/3] descriptor: clarify platform and artifacts Signed-off-by: Bjorn Neergaard --- descriptor.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/descriptor.md b/descriptor.md index 0dc349b31..cfbe3d6ba 100644 --- a/descriptor.md +++ b/descriptor.md @@ -54,11 +54,13 @@ The following fields contain the primary properties that constitute a Descriptor - **`artifactType`** *string* - This OPTIONAL property contains the type of an artifact when the descriptor points to an [artifact](artifacts-guidance.md). + This OPTIONAL property contains the type of an artifact when the descriptor points to an [Artifact](artifacts-guidance.md). This property MUST be the same as the `artifactType` of the referenced [manifest](manifest.md), or the `mediaType` of the `config` descriptor if an `artifactType` is not set. 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]. -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. +Descriptors referencing an Image (as defined in the [artifacts guidance](artifacts-guidance.md)) SHOULD include the extended field `platform`. +See [Image Index Property Descriptions](image-index.md#image-index-property-descriptions) for details. +Artifacts as defined in the artifacts guidance MAY include the extended field `platform` when it improves discoverability or interoperability of the artifact. ### Reserved