contentEncoding : String
contentEncoding
StringThe string instance should be interpreted as encoded binary data and decoded using the encoding named by this property.
| Value |
This keyword should be set to a standard (to increase interoperability) encoding name such as those defined in RFC 4648 and RFC 2045
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.3 |
| Metaschema | https://json-schema.org/draft/2020-12/meta/content |
| Official Tests | draft2020-12/content.json |
| Default | None |
| Annotation |
String
The content encoding name set by this keyword
Hint: Use the jsonschema validate command to collect annotations from the command-line
|
| Affected By | None |
| Affects | None |
| Also See |
|
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
It is recommended to set this keyword along with the contentMediaType keyword to declare the type of data
being encoded (for example, an image in PNG format). Otherwise, the receiver
must treat the instance value as a binary blob without knowing for sure the
type of information it represents.
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-Transfer-Encoding
MIME header used in conjunction with the
Content-Type 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.
RFC 4648 (The Base16, Base32,
and Base64 Data Encodings) and RFC
2045 (Format of Internet
Message Bodies) define the following standard encodings. In the interest of
interoperability, avoid defining new content encodings. While the JSON Schema
specification does not provide explicit guidance on this, RFC 2045 Section
6.3 suggests that
if a custom content encoding is really needed, it must be prefixed with x-.
For example, x-my-new-encoding.
| Encoding | Description | Reference |
|---|---|---|
"base64" |
Encoding scheme using a 64-character hexadecimal alphabet | RFC 4648 Section 4 |
"base32" |
Encoding scheme using a 32-character hexadecimal alphabet | RFC 4648 Section 6 |
"base16" |
Encoding scheme using a 16-character hexadecimal alphabet | RFC 4648 Section 8 |
"7bit" |
Encoding scheme that constrains ASCII to disallow octets greater than 127, disallow NUL, and restricts CR and LF to CRLF sequences |
RFC 2045 Section 2.7 |
"8bit" |
Encoding scheme that constrains ASCII to permit octets greater than 127, disallow NUL, and restrict CR and LF to CRLF sequences |
RFC 2045 Section 2.8 |
"binary" |
Encoding scheme where any sequence of octets is allowed | RFC 2045 Section 2.9 |
"quoted-printable" |
Encoding scheme that preserves ASCII printable characters and escapes the rest using a simple algorithm based on an hexadecimal alphabet | RFC 2045 Section 6.7 |
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": "https://json-schema.org/draft/2020-12/schema",
"contentEncoding": "base64"
}"SGVsbG8gV29ybGQ=" // Hello World{ "keyword": "/contentEncoding", "instance": "", "value": "base64" }"This is not Base 64"{ "keyword": "/contentEncoding", "instance": "", "value": "base64" }1234