From 78a5b0d0af8e6df39402936161187b16f14ca40a Mon Sep 17 00:00:00 2001 From: Aaron Friel Date: Thu, 16 Mar 2023 10:20:27 -0700 Subject: [PATCH] spec: clarify descriptor, align with de facto artifact usage --- config.md | 2 +- considerations.md | 5 +++-- descriptor.md | 3 ++- image-index.md | 2 +- image-layout.md | 2 +- manifest.md | 11 ++++++++--- 6 files changed, 16 insertions(+), 9 deletions(-) diff --git a/config.md b/config.md index 7b69ce5c0..4784eb006 100644 --- a/config.md +++ b/config.md @@ -248,7 +248,7 @@ Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being a This field is used to mark if the history item created a filesystem diff. It is set to true if this history item doesn't correspond to an actual layer in the rootfs section (for example, Dockerfile's [ENV](https://docs.docker.com/engine/reference/builder/#/env) command results in no change to the filesystem). -Any extra fields in the Image JSON struct are considered implementation specific and MUST be ignored by any implementations which are unable to interpret them. +Any extra fields in the Image JSON struct are considered implementation specific and MUST NOT generate an error by any implementations which are unable to interpret them. Whitespace is OPTIONAL and implementations MAY have compact JSON with no whitespace. diff --git a/considerations.md b/considerations.md index d176c511f..87aae8bed 100644 --- a/considerations.md +++ b/considerations.md @@ -1,7 +1,8 @@ # Extensibility -Implementations that are reading/processing [manifests](manifest.md) or [image indexes](image-index.md) MUST NOT generate an error if they encounter an unknown property. -Instead they MUST ignore unknown properties. +Implementations storing or copying content MUST NOT generate error if they encounter an unknown manifest media type (e.g.: [image manifest](manifest.md)) or an unknown property in a manifest. + +Implementations processing content MUST NOT generate an error if they encounter an unknown property in a known media type. # Canonicalization diff --git a/descriptor.md b/descriptor.md index 82d303fe1..214899f9e 100644 --- a/descriptor.md +++ b/descriptor.md @@ -18,7 +18,8 @@ The following fields contain the primary properties that constitute a Descriptor - **`mediaType`** *string* - This REQUIRED property contains the media type of the referenced content. + This REQUIRED property MUST contain the media type of the referenced content unless this descriptor is the `config` property of an [image manifest](manifest.md). + Values MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2]. The OCI image specification defines [several of its own MIME types](media-types.md) for resources defined in the specification. diff --git a/image-index.md b/image-index.md index 7695bb6cb..d8f45cf63 100644 --- a/image-index.md +++ b/image-index.md @@ -43,7 +43,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma Image indexes concerned with portability SHOULD use one of the above media types. Future versions of the spec MAY use a different mediatype (i.e. a new versioned format). - An encountered `mediaType` that is unknown to the implementation MUST be ignored. + An encountered `mediaType` that is unknown to the implementation MUST NOT generate an error. - **`platform`** *object* diff --git a/image-layout.md b/image-layout.md index 19f9a7dc3..f2a6afb61 100644 --- a/image-layout.md +++ b/image-layout.md @@ -147,7 +147,7 @@ This index provides an established path (`/index.json`) to have an entry point f * No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors. * In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`. * Future versions of the spec MAY use a different mediatype (i.e. a new versioned format). -* An encountered `mediaType` that is unknown SHOULD be safely ignored. +* An encountered `mediaType` that is unknown MUST NOT generate an error. **Implementor's Note:** diff --git a/manifest.md b/manifest.md index 0fad19289..7db6f55d4 100644 --- a/manifest.md +++ b/manifest.md @@ -39,8 +39,14 @@ Unlike the [image index](image-index.md), which contains information about a set - **`mediaType`** *string* - This [descriptor property](descriptor.md#properties) has additional restrictions for `config`. - Implementations MUST support at least the following media types: + This [descriptor property](descriptor.md#properties) has different restrictions for `config`. + This value is the `artifactType` property of descriptors referencing this manifest. + + Implementations MUST NOT attempt to parse the referenced content if this media type is unknown and instead consider the referenced content as arbitrary binary data (e.g.: as `application/octet-stream`). + + If this manifest is intended for use by [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec) implementations, the following additional restrictions apply to this property: + + Manifests concerned with portability SHOULD use one of the following media types: - [`application/vnd.oci.image.config.v1+json`](config.md) @@ -80,7 +86,6 @@ Unlike the [image index](image-index.md), which contains information about a set - [`application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`](layer.md#gzip-media-types) Manifests concerned with portability SHOULD use one of the above media types. - An encountered `mediaType` that is unknown to the implementation MUST be ignored. Entries in this field will frequently use the `+gzip` types.