spec: clarify descriptor, align with de facto artifact usage

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,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 modify or alter the content in a way that would change the digest of the content.
+
+Implementations processing content MUST NOT generate an error if they encounter an unknown property in a known media type.
 
 # 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].
+  An encountered `artifactType` that is unknown to the implementation MUST NOT generate an error.
 
 - **`config`** *[descriptor](descriptor.md)*
 
@@ -39,8 +40,11 @@ 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:
+        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)
 
@@ -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.
+        An encountered `mediaType` that is unknown to the implementation MUST NOT generate an error.
 
         Entries in this field will frequently use the `+gzip` types.