Improve contentMediaType explanation

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

content/2020-12/content/contentEncoding.markdown

@@ -20,12 +20,12 @@ related:
     keyword: contentSchema
 ---
 
-The `contentEncoding` keyword signifies that an instance value (such as a
-specific object property) should be considered binary data encoded into a JSON
-string using the given encoding. This keyword does not affect validation, but
-the evaluator will collect its value as an annotation.  The use of this and
-related keywords is a common technique to encode and describe arbitrary binary
-data (such as image, audio, and video) in JSON.
+The `contentEncoding` keyword signifies that a string instance value (such as a
+specific object property) should be considered binary data serialised using the
+given encoding. This keyword does not affect validation, but the evaluator will
+collect its value as an annotation.  The use of this and related keywords is a
+common technique to encode and describe arbitrary binary data (such as image,
+audio, and video) in JSON.
 
 {{<best-practice>}}
 
@@ -51,10 +51,12 @@ supports content encoding/decoding and how to enable it.
 
 This keyword is inspired by the
 [`Content-Transfer-Encoding`](https://www.rfc-editor.org/rfc/rfc2045.html#section-6)
-RFC 2045 MIME header used to transmit non-ASCII data over e-mail. For example,
-if you send a picture as an e-mail attachment, your e-mail client will likely
-send a multipart message that includes the Base64-encoded representation of
-such picture, while setting the `Content-Transfer-Encoding` header to `base64`.
+MIME header used in conjunction with the
+[`Content-Type`](https://www.rfc-editor.org/rfc/rfc2045.html#section-5) header
+to transmit non-ASCII data over e-mail. For example, if you send a PNG image as
+an e-mail attachment, your e-mail client will likely send a multipart message
+that includes the Base64-encoded image, sets the `Content-Transfer-Encoding`
+header to `base64`, and sets the `Content-Type` header to `image/png`.
 
 {{</learning-more>}}
 

content/2020-12/content/contentMediaType.markdown

@@ -21,11 +21,59 @@ related:
     keyword: contentEncoding
 ---
 
-The `contentMediaType` keyword in JSON Schema specifies the MIME type of the contents of a string. It is used to annotate the type of media contained within a string. It should be noted that:
+When the [`contentEncoding`]({{< ref "2020-12/content/contentencoding" >}})
+keyword is set, the `contentMediaType` keyword signifies that a string instance
+value (such as a specific object property) should be considered binary data
+that represents the given type. This keyword does not affect validation, but
+the evaluator will collect its value as an annotation.  The use of this and
+related keywords is a common technique to encode and describe arbitrary binary
+data (such as image, audio, and video) in JSON.
 
-* This keyword is purely an annotation and does not directly affect validation.
-* It describes the media type of the binary string after it has been decoded as specified in `contentEncoding`.
-* It is recommended to set `contentEncoding` if `contentMediaType` is declared.
+{{<best-practice>}}
+
+It is recommended to set this keyword along with the [`contentEncoding`]({{<
+ref "2020-12/content/contentencoding" >}}) keyword to declare the encoding used
+to serialised the data (for example, Base 64 encoding).  Otherwise, the
+receiver must treat the instance value as a binary blob without knowing for
+sure how to decode it.
+
+{{</best-practice>}}
+
+{{<common-pitfall>}}
+
+The JSON Schema specification prohibits implementations, for security reasons,
+from automatically attempting to decode, parse, or validate encoded data
+without the consumer explicitly opting in to such behaviour. If you require
+this feature, consult the documentation of your tooling of choice to see if it
+supports content encoding/decoding and how to enable it.
+
+{{</common-pitfall>}}
+
+{{<learning-more>}}
+
+This keyword is inspired by the
+[`Content-Type`](https://www.rfc-editor.org/rfc/rfc2045.html#section-5) MIME
+header used in conjunction with the
+[`Content-Transfer-Encoding`](https://www.rfc-editor.org/rfc/rfc2045.html#section-6)
+header to transmit non-ASCII data over e-mail. For example, if you send a PNG
+image as an e-mail attachment, your e-mail client will likely send a multipart
+message that includes the Base64-encoded image, sets the `Content-Type` header
+to `image/png`, and sets the `Content-Transfer-Encoding` header to `base64`.
+
+{{</learning-more>}}
+
+The Internet Assigned Numbers Authority (IANA) standards organization is the
+source of truth for the exhaustive official list of registered content media
+types. You can find the complete list at
+[https://www.iana.org/assignments/media-types/media-types.xhtml](https://www.iana.org/assignments/media-types/media-types.xhtml).
+
+In the interest of interoperability, avoid using custom unregistered content
+media types. If required, register a new content media type with the IANA
+[here](https://www.iana.org/form/media-types).  Alternatively, [RFC 2046
+Section 6.3](https://datatracker.ietf.org/doc/html/rfc2046) suggests that if a
+custom unregistered content media type is really needed, it must live within a
+registered category and prefixed with `x-`.  For example,
+`application/x-my-custom-media-type`.
 
 ## Examples