spec: clarify descriptor, align with de facto artifact usage

Signed-off-by: Aaron Friel <[email protected]>

Author: AaronFriel

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.
 

considerations.md

@@ -1,7 +1,12 @@
 # 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 modify or alter the content in a way that would change the digest of the content. Examples of these implementations include:
+* A [registry implementing the distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#definitions), including local registries, caching proxies
+* An application which copies content to disk or between registries
+
+Implementations processing content SHOULD NOT generate an error if they encounter an unknown property in a known media type. Examples of these implementations include:
+* A [runtime implementing the runtime specification](https://github.com/opencontainers/runtime-spec/blob/main/spec.md)
+* An implementation using OCI to retrieve and utilize artifacts, e.g.: a WASM runtime
 
 # Canonicalization
 

image-index.md

@@ -42,7 +42,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*
 

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:**

manifest.md

@@ -31,6 +31,7 @@ Unlike the [image index](image-index.md), which contains information about a set
   This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
   This MUST be set when `config.mediaType` is set to the [scratch value](#example-of-a-scratch-config-or-layer-descriptor).
   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].
+  Implementations storing or copying image manifests MUST NOT error on encountering an `artifactType` that is unknown to the implementation.
 
 - **`config`** *[descriptor](descriptor.md)*
 
@@ -40,6 +41,9 @@ 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 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`).
+
         Implementations MUST support at least the following media types:
 
         - [`application/vnd.oci.image.config.v1+json`](config.md)
@@ -83,7 +87,7 @@ 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.
+        Implementations storing or copying image manifests MUST NOT error on encountering a `mediaType` that is unknown to the implementation.
 
         Entries in this field will frequently use the `+gzip` types.