Skip to content

Commit aa07af6

Browse files
jviottijviotti
committed
Fully document JSON Schema Draft 7
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
1 parent c61017e commit aa07af6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+3715
-19
lines changed

‎content/draft7/core/comment.markdown‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,56 @@ metaschema: "http://json-schema.org/draft-07/schema#"
1010
introduced_in: draft7
1111
index: -9
1212
---
13+
14+
The [`$comment`]({{< ref "draft7/core/comment" >}}) keyword is a
15+
standardised placeholder for explanatory string schema comments. This
16+
keyword is completely ignored by the evaluation process and it is possible
17+
to strip instances of this keyword when distributing your schemas for the
18+
purpose of space-efficiency. This keyword is commonly used to declare [TODO
19+
comments](https://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags)
20+
in various parts of a schema.
21+
22+
{{<common-pitfall>}}
23+
24+
Compared to other similar keywords such as [`title`]({{< ref
25+
"draft7/validation/title" >}}) and [`description`]({{< ref
26+
"draft7/validation/description" >}}), this keyword does not produce any
27+
semantic meaning. Furthermore, the specification explicitly prohibits any JSON
28+
Schema tooling from inferring meaning from this keyword or elevating its
29+
contents to the end user in any way.
30+
31+
{{</common-pitfall>}}
32+
33+
{{<learning-more>}}
34+
35+
The JSON data format does not support any form of comments at the grammar
36+
level. While this is a common point of contention, comment support (or any
37+
other improvement) will be never added. The [ECMA
38+
404](https://ecma-international.org/publications-and-standards/standards/ecma-404/)
39+
JSON standard declares that: *"it is not expected that the JSON grammar will
40+
ever change"*. If this keyword is not enough, there are various other data
41+
formats that operate on the JSON data model that have comment support, like
42+
[YAML](https://yaml.org) and [JSON5](https://json5.org). However, JSON remains
43+
by far the preferred data format within the community, both when authoring
44+
schemas and over the wire.
45+
46+
{{</learning-more>}}
47+
48+
## Examples
49+
50+
{{<schema `A schema that declares a top level and a nested comment`>}}
51+
{
52+
"$schema": "http://json-schema.org/draft-07/schema#",
53+
"$comment": "This is an internal note about the schema that is ignored by the evaluation process",
54+
"properties": {
55+
"name": {
56+
"$comment": "TODO: Add `pattern` to better validate names",
57+
"type": "string"
58+
}
59+
}
60+
}
61+
{{</schema>}}
62+
63+
{{<instance-pass `Any string value is valid`>}}
64+
{ "name": "John Doe" }
65+
{{</instance-pass>}}

‎content/draft7/core/id.markdown‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,170 @@ related:
1818
- vocabulary: core
1919
keyword: $schema
2020
---
21+
22+
The [`$id`]({{< ref "draft7/core/id" >}}) keyword explicitly turns a schema
23+
into a _schema resource_ (a schema that is associated with a URI). Relative
24+
URIs are resolved against the _current_ base URI, which is either the closest
25+
parent [`$id`]({{< ref "draft7/core/id" >}}) keyword (applicable in the case
26+
of compound schemas), or the base URI as determined by the context on which the
27+
schema is declared (i.e. serving a schema over HTTP _may_ implicitly award it
28+
such URL as the base).
29+
30+
{{<learning-more>}}
31+
32+
This keyword directly applies (without modifications or extensions) the concept
33+
of URIs to schemas. **If you are having a hard time following the concepts
34+
discussed in this page, it is probably because you don't have a strong grasp of
35+
URIs yet** (a notably hard but universal pre-requisite!).
36+
37+
To learn more about URIs, we strongly suggest studying the [IETF RFC
38+
3986](https://www.rfc-editor.org/info/rfc3986) URI standard. To avoid
39+
confusion, note that there is also a [WHATWG URL
40+
Standard](https://url.spec.whatwg.org) that targets URLs in the context of web
41+
browsers. However, JSON Schema only implements and expects the IETF original
42+
standard.
43+
44+
{{</learning-more>}}
45+
46+
{{<common-pitfall>}}
47+
48+
In JSON Schema, schema identifiers are merely identifiers and no behaviour is
49+
imposed on them. In particular, JSON Schema does not guarantee that a schema
50+
with an HTTP URL identifier is actually resolvable at such URL. To avoid
51+
surprises, JSON Schema implementations must be careful with automatically
52+
sending remote network requests when encountering supposely resolvable schema
53+
identifiers.
54+
55+
{{</common-pitfall>}}
56+
57+
{{<best-practice>}}
58+
59+
It is strongly recommended for every schema file to explicitly declare an
60+
_absolute_ URI using this keyword. By doing so, you completely avoid various
61+
complex URI resolution edge cases, mainly when the base URI is implicit and
62+
context-dependent.
63+
64+
If you are serving schemas over the network (i.e. over HTTP), it is common to
65+
set this keyword to the target URL. However, if your schemas are not accessible
66+
over the network, prefer using a
67+
[URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) (with a valid
68+
namespace registered by
69+
[IANA](https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml))
70+
or a non-locatable URI scheme such as a [Tag URI](https://www.taguri.org).
71+
72+
{{</best-practice>}}
73+
74+
To debug the role of the [`$id`]({{< ref "draft7/core/id" >}}) keyword on
75+
a schema (particularly schemas with embedded resources), try the [`jsonschema
76+
inspect`](https://github.com/sourcemeta/jsonschema/blob/main/docs/inspect.markdown)
77+
command. This command prints detailed information about each schema resource,
78+
subschema, location, and reference present in the schema. For example:
79+
80+
```sh
81+
$ jsonschema inspect schema.json
82+
(RESOURCE) URI: https://example.com/schema
83+
Type : Static
84+
Root : https://example.com/schema
85+
Pointer :
86+
Base : https://example.com/schema
87+
Relative Pointer :
88+
Dialect : http://json-schema.org/draft-07/schema#
89+
Base Dialect : http://json-schema.org/draft-07/schema#
90+
Parent : <NONE>
91+
Instance Location :
92+
93+
...
94+
95+
(SUBSCHEMA) URI: https://example.com/schema#/properties/foo
96+
Type : Static
97+
Root : https://example.com/schema
98+
Pointer : /properties/foo
99+
Base : https://example.com/schema
100+
Relative Pointer : /properties/foo
101+
Dialect : http://json-schema.org/draft-07/schema#
102+
Base Dialect : http://json-schema.org/draft-07/schema#
103+
Parent :
104+
Instance Location : /foo
105+
106+
...
107+
108+
(REFERENCE) ORIGIN: /$schema
109+
Type : Static
110+
Destination : http://json-schema.org/draft-07/schema
111+
- (w/o fragment) : http://json-schema.org/draft-07/schema
112+
- (fragment) : <NONE>
113+
```
114+
115+
## Examples
116+
117+
{{<schema `A schema that declares a potentially resolvable HTTP absolute URL identifier`>}}
118+
{
119+
"$schema": "http://json-schema.org/draft-07/schema#",
120+
"$id": "https://example.com/schemas/even-number.json",
121+
"type": "number",
122+
"multipleOf": 2
123+
}
124+
{{</schema>}}
125+
126+
{{<schema `A schema that declares a non-resolvable Tag URI identifier`>}}
127+
{
128+
"$schema": "http://json-schema.org/draft-07/schema#",
129+
"$id": "tag:example.com,2025:even-number",
130+
"type": "number",
131+
"multipleOf": 2
132+
}
133+
{{</schema>}}
134+
135+
{{<schema `A schema that declares a non-resolvable URN example identifier`>}}
136+
{
137+
"$schema": "http://json-schema.org/draft-07/schema#",
138+
"$id": "urn:example:even-number",
139+
"type": "number",
140+
"multipleOf": 2
141+
}
142+
{{</schema>}}
143+
144+
{{<schema `A schema that uses fragment identifiers to create reusable anchors`>}}
145+
{
146+
"$schema": "http://json-schema.org/draft-07/schema#",
147+
"$id": "https://example.com/schemas/user.json",
148+
"type": "object",
149+
"properties": {
150+
"name": { "$ref": "#nonEmptyString" },
151+
"email": { "$ref": "#nonEmptyString" }
152+
},
153+
"definitions": {
154+
"nonEmptyString": {
155+
"$id": "#nonEmptyString",
156+
"type": "string",
157+
"minLength": 1
158+
}
159+
}
160+
}
161+
{{</schema>}}
162+
163+
{{<schema `A compound schema that declares relative and absolute nested URIs`>}}
164+
{
165+
"$schema": "http://json-schema.org/draft-07/schema#",
166+
"$comment": "This is the root schema resource",
167+
"$id": "https://example.com/schemas/root.json",
168+
"properties": {
169+
"foo": {
170+
"$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/foo.json",
171+
"$id": "foo.json"
172+
},
173+
"bar": {
174+
"$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/bar.json",
175+
"$id": "/schemas/bar.json"
176+
},
177+
"baz": {
178+
"$comment": "The resolved URI of this nested schema resource is https://absolute.example/baz.json",
179+
"$id": "https://absolute.example/baz.json",
180+
"items": {
181+
"$comment": "The resolved URI of this nested schema resource is https://absolute.example/deep",
182+
"$id": "deep"
183+
}
184+
}
185+
}
186+
}
187+
{{</schema>}}

0 commit comments

Comments
 (0)