contentMediaType : String
contentMediaType
StringThis 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 | Draft 7 |
| Changed In | None |
| Introduced In | Draft 7 |
| Vocabulary | Validation |
| Specification | https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01#rfc.section.8.4 |
| Metaschema | http://json-schema.org/draft-07/schema# |
| Official Tests | draft7/optional/content.json |
| Default | None |
| Annotation | None |
| Affected By | None |
| Affects | None |
| Also See |
|
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 is merely descriptive and
does not affect validation. 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 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
{
"$schema": "http://json-schema.org/draft-07/schema#",
"contentEncoding": "base64",
"contentMediaType": "text/html"
}"PHA+SlNPTiBTY2hlbWE8L3A+" // <p>JSON Schema</p>"PFwvZm9v" // <\/foo1234