Skip to content

Commit 310c93b

Browse files
valeriahhdezjdesrosiers
valeriahhdez
and
jdesrosiers
authored
Modify non_json_data.md, document contentSchema keyword (#1028)
* Modify non_json_data.md, document contentSchema keyword * Update pages/understanding-json-schema/reference/non_json_data.md Co-authored-by: Jason Desrosiers <[email protected]> * Integrate review comments to non_json_data.md This version includes changes suggested by Jason, Benjamin, Blessing, and Anitha * Improve heading structure of non_json_data.md These changes introduce a better heading structure for scannability --------- Co-authored-by: Jason Desrosiers <[email protected]>
1 parent 9899bc7 commit 310c93b

File tree

2 files changed

+107
-48
lines changed

2 files changed

+107
-48
lines changed

‎pages/understanding-json-schema/reference/non_json_data.md‎

Lines changed: 107 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,88 +3,147 @@ title: "Media: string-encoding non-JSON data"
33
section: docs
44
---
55

6-
<Keywords label="single: non-JSON data single: media" />
6+
<Keywords label="single: non-JSON data single: media"/>
77

88
<Star label="New in draft 7" />
99

10-
JSON schema has a set of [keywords](../../learn/glossary#keyword) to describe and optionally validate
11-
non-JSON data stored inside JSON strings. Since it would be difficult to
12-
write validators for many media types, JSON schema validators are not
13-
required to validate the contents of JSON strings based on these
14-
keywords. However, these keywords are still useful for an application
15-
that consumes validated JSON.
10+
JSON schema has a set of [keywords](../../learn/glossary#keyword) to describe and optionally validate non-JSON data stored inside JSON strings. Due to the difficulty in writing validators for all media types, JSON schema validators are not required to validate the contents of JSON strings based on these keywords. However, applications that consume validated JSON use these keywords to encode and decode data during the storage and transmission of media types.
1611

1712
<Keywords label="single: contentMediaType single: media; contentMediaType" />
1813

19-
## contentMediaType
14+
## contentMediaType and contentEncoding
2015

21-
The `contentMediaType` keyword specifies the MIME type of the contents
22-
of a string, as described in [RFC 2046](https://tools.ietf.org/html/rfc2046).
23-
There is a list of [MIME types officially registered by the IANA](http://www.iana.org/assignments/media-types/media-types.xhtml),
24-
but the set of types supported will be application and operating system dependent.
25-
Mozilla Developer Network also maintains a [shorter list of MIME types that are important for the web](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)
16+
The `contentMediaType` keyword specifies the media type of the content of a string, as described in [RFC 2046](https://tools.ietf.org/html/rfc2046). The Internet Assigned Numbers Authority (IANA) has officially registered [a comprehensive list of media types](http://www.iana.org/assignments/media-types/media-types.xhtml), but the set of supported types depends on the application and operating system. Mozilla Developer Network maintains a [shorter list of media types that are important for the web](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)
2617

27-
<Keywords label="single: contentEncoding single: media; contentEncoding" />
18+
### Example
19+
20+
The following schema specifies a string containing an HTML file using the document's default encoding.
2821

29-
## contentEncoding
22+
```json
23+
// props { "isSchema": true }
24+
{
25+
"type": "string",
26+
"contentMediaType": "text/html"
27+
}
28+
```
29+
```json
30+
// props { "indent": true, "valid": true }
31+
"<!DOCTYPE html><html xmlns=\"http://www.w3.org/1999/xhtml\"><head></head></html>"
32+
```
3033

31-
The `contentEncoding` keyword specifies the encoding used to store the
32-
contents, as specified in [RFC 2054, part
33-
6.1](https://tools.ietf.org/html/rfc2045) and [RFC
34-
4648](https://datatracker.ietf.org/doc/html/rfc4648).
34+
<Keywords label="single: contentEncoding single: media; contentEncoding" />
3535

36-
The acceptable values are `quoted-printable`,
37-
`base16`, `base32`, and `base64`. If not specified, the encoding is the
38-
same as the containing JSON document.
3936

40-
Without getting into the low-level details of each of these encodings,
41-
there are really only two options useful for modern usage:
37+
The `contentEncoding` keyword specifies the encoding used to store the contents, as specified in [RFC 2054, part 6.1](https://tools.ietf.org/html/rfc2045) and [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).
4238

43-
- If the content is encoded in the same encoding as the enclosing JSON
44-
document (which for practical purposes, is almost always UTF-8),
45-
leave `contentEncoding` unspecified, and include the content in a
46-
string as-is. This includes text-based content types, such as
47-
`text/html` or `application/xml`.
48-
- If the content is binary data, set `contentEncoding` to `base64` and
49-
encode the contents using
50-
[Base64](https://tools.ietf.org/html/rfc4648). This would include
51-
many image types, such as `image/png` or audio types, such as
52-
`audio/mpeg`.
39+
The acceptable values are the following:
40+
- `quoted-printable`
41+
- `base16`
42+
- `base32`
43+
- `base64`
44+
45+
If not specified, the encoding is the same as the containing JSON document.
5346

54-
<Keywords label="single: contentSchema single: media; contentSchema" />
47+
There are two main scenarios:
5548

56-
## contentSchema
57-
<Star label="New in draft 2019-09" />
49+
1. **Same encoding as JSON document**: Leave `contentEncoding` unspecified and include the content in a string as-is. This is suitable for text-based content types (e.g., `text/html`, `application/xml`) and assumes UTF-8 encoding in most cases.
50+
2. **Binary data**: Set `contentEncoding` to `base64` and encode the content using Base64. This is appropriate for binary content types such as images (`image/png`) or audio files (`audio/mpeg`).
5851

59-
Documentation Coming soon
6052

61-
## Examples
53+
### Example
6254

63-
The following schema indicates the string contains an HTML document,
64-
encoded using the same encoding as the surrounding document:
55+
The following schema indicates that a string contains a PNG file and is encoded using Base64:
6556

6657
```json
6758
// props { "isSchema": true }
6859
{
6960
"type": "string",
70-
"contentMediaType": "text/html"
61+
"contentEncoding": "base64",
62+
"contentMediaType": "image/png"
7163
}
7264
```
7365
```json
7466
// props { "indent": true, "valid": true }
75-
"<!DOCTYPE html><html xmlns=\"http://www.w3.org/1999/xhtml\"><head></head></html>"
67+
"iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..."
7668
```
77-
The following schema indicates that a string contains a PNG image, encoded using Base64:
69+
70+
To better understand how `contentEncoding` and `contentMediaType` are applied in practice, let's consider the process of transmitting non-JSON data:
71+
72+
<!--
73+
![Role of contentEncoding and contenMediaType keywords in the transmission of non-JSON data](/img/media-keywords.png)
74+
-->
75+
76+
```mermaid
77+
block-beta
78+
columns 9
79+
A space B space C space D space E
80+
F space:5 G space:2
81+
82+
A{{"Sender"}} --> F{"contentEncoding
83+
contentMediaType"}
84+
F{"contentEncoding
85+
contentMediaType"} --> B{{"Encoded data"}}
86+
B{{"Encoded data"}} --> C(["Transmission"])
87+
C(["Transmission"]) --> D{{"Consumer application"}}
88+
D{{"Consumer application"}} --> G{"contentEncoding
89+
contentMediaType"}
90+
G{"contentEncoding
91+
contentMediaType"} --> E{{"Decoded data"}}
92+
```
93+
94+
1. The sender encodes the content, using `contentEncoding` to specify the encoding method (e.g., base64) and `contentMediaType` to indicate the media type of the original content.
95+
2. The encoded data is then transmitted.
96+
3. Upon receiving the data, the consumer application uses the `contentEncoding` and `contentMediaType` information to select the appropriate decoding method.
97+
4. Finally, the consumer application decodes the data, restoring it to its original form.
98+
99+
This process ensures that the non-JSON content is properly encoded for transmission and accurately decoded by the recipient, maintaining the integrity of the data throughout the process.
100+
101+
<Keywords label="single: contentSchema single: media; contentSchema" />
102+
103+
## contentSchema
104+
<Star label="New in draft 2019-09" />
105+
106+
The value of `contentSchema` must be a valid JSON schema that you can use to define the structure and constraints of the content. It is used in conjunction with `contentMediaType` when the instance is a string. If `contentMediaType` is absent, the value of `contentSchema` is ignored.
107+
108+
## Full example
109+
110+
The following schema indicates that a string contains a JSON object encoded using Base64:
78111

79112
```json
80113
// props { "isSchema": true }
81114
{
82-
"type": "string",
83-
"contentEncoding": "base64",
84-
"contentMediaType": "image/png"
115+
"$schema": "https://json-schema.org/draft/2020-12/schema",
116+
"type": "object",
117+
"properties": {
118+
"data": {
119+
"type": "string",
120+
"contentMediaType": "application/json",
121+
"contentEncoding": "base64",
122+
"contentSchema": {
123+
"type": "object",
124+
"properties": {
125+
"name": {
126+
"type": "string"
127+
},
128+
"age": {
129+
"type": "integer"
130+
}
131+
},
132+
"required": ["name", "age"]
133+
}
134+
}
135+
}
85136
}
86137
```
87138
```json
88139
// props { "indent": true, "valid": true }
89-
"iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..."
140+
"eyJuYW1lIjoiSm9obiBEb2UiLCJ0b21lIjoiMjUifQ=="
141+
```
142+
143+
```json
144+
// props { "indent": true, "valid": true }
145+
{
146+
"name": "John Doe",
147+
"age": 25
148+
}
90149
```

‎public/img/media-keywords.png‎

38.3 KB
Loading

0 commit comments

Comments
 (0)