contentMediaType : String

contentMediaType

String

This keyword declares the media type of the string instance.

Value	This keyword should be set to a valid media type as defined in RFC 2046, like the registered IANA media types Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Annotation
Applies To	String
Base Dialect	2020-12
Changed In	None
Introduced In	Draft 7
Vocabulary	Content
Specification	https://json-schema.org/draft/2020-12/json-schema-validation.html#section-8.4
Metaschema	https://json-schema.org/draft/2020-12/meta/content
Official Tests	draft2020-12/content.json
Default	None
Annotation	String The content media type set by this keyword Hint: Use the `jsonschema validate` command to collect annotations from the command-line
Affected By	None
Affects	contentSchema (Vocabulary: Content)
Also See	contentEncoding (Vocabulary: Content)

When the 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.

Best Practice

It is recommended to set this keyword along with the 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.

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.

Digging Deeper

This keyword is inspired by the Content-Type MIME header used in conjunction with the Content-Transfer-Encoding 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.

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.

In the interest of interoperability, avoid using custom unregistered content media types. If required, register a new content media type with the IANA here. Alternatively, RFC 2046 Section 6.3 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.

Remember that JSON Schema is a constraint-driven language. Therefore, non-string instances successfully validate against this keyword. If needed, make use of the type keyword to constraint the accepted type accordingly.

Examples

A schema that describes HTML data encoded using Base 64 Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "contentEncoding": "base64",
  "contentMediaType": "text/html"
}

Valid A string value that represents a valid HTML document encoded in Base 64 is valid and an annotations are emitted Instance

"PHA+SlNPTiBTY2hlbWE8L3A+" // <p>JSON Schema</p>

Annotations

{ "keyword": "/contentEncoding", "instance": "", "value": "base64" }
{ "keyword": "/contentMediaType", "instance": "", "value": "text/html" }

Valid A string value that represents an invalid HTML document encoded in Base 64 is valid and an annotations are still emitted Instance

"PFwvZm9v" // <\/foo