Skip to content
This repository was archived by the owner on Nov 3, 2023. It is now read-only.

Commit 02c79aa

Browse files
authored
Merge pull request #74 from mdboom/draft-6
Update document to Draft 6
2 parents acabfc6 + 73134cf commit 02c79aa

11 files changed

+452
-88
lines changed

source/basics.rst

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,28 @@ completely valid schema that will accept any valid JSON.
2525
--
2626
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
2727

28+
|draft6|
29+
30+
You can also use ``true`` in place of the empty object to represent a schema
31+
that matches anything, or ``false`` for a schema that matches nothing.
32+
33+
.. schema_example::
34+
35+
true
36+
--
37+
// This accepts anything, as long as it's valid JSON
38+
42
39+
--
40+
"I'm a string"
41+
--
42+
{ "an": [ "arbitrarily", "nested" ], "data": "structure" }
43+
44+
.. schema_example::
45+
46+
false
47+
--X
48+
"Resistance is futile... This will always fail!!!"
49+
2850
The type keyword
2951
----------------
3052

@@ -77,10 +99,17 @@ more information.
7799
Declaring a unique identifier
78100
-----------------------------
79101

80-
It is also best practice to include an ``id`` property as a unique
102+
It is also best practice to include an ``$id`` property as a unique
81103
identifier for each schema. For now, just set it to a URL at a domain
82104
you control, for example::
83105

84-
{ "id": "http://yourdomain.com/schemas/myschema.json" }
106+
{ "$id": "http://yourdomain.com/schemas/myschema.json" }
85107

86108
The details of `id` become more apparent when you start `structuring`.
109+
110+
|draft6|
111+
112+
.. draft_specific::
113+
114+
--Draft 4
115+
In Draft 4, ``$id`` is just ``id`` (without the dollar-sign).

source/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
sys.path.insert(0, os.path.abspath(os.path.dirname('__file__')))
2121

2222
# The standard of JSON Schema to test the examples against
23-
jsonschema_standard = 4
23+
jsonschema_standard = 6
2424

2525
rst_prolog = """
2626
.. role:: new
@@ -63,9 +63,9 @@
6363
# built documents.
6464
#
6565
# The short X.Y version.
66-
version = '1.9alpha'
66+
version = '6.0'
6767
# The full version, including alpha/beta/rc tags.
68-
release = '1.9alpha'
68+
release = '6.0'
6969

7070
# The language for content autogenerated by Sphinx. Refer to documentation
7171
# for a list of supported languages.

source/conventions.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,27 @@ JSON in a few different languages:
3535
For C, you may want to consider using `Jansson
3636
<http://www.digip.org/jansson/>`_ to read and write JSON.
3737

38+
Draft-specific notes
39+
--------------------
40+
41+
The JSON Schema standard has been through a number of revisions or "drafts". The
42+
most important are Draft 6, the most recent at the time of this writing, and
43+
Draft 4, on which a lot of production software was built, and the draft for
44+
which an earlier version of this book was written.
45+
46+
The text is written to encourage the use of Draft 6 and gives
47+
priority to the latest conventions and features, but where it differs from Draft
48+
4, those differences are highlighted in special call-outs. If you only wish to
49+
target Draft 6, you can safely ignore those sections.
50+
51+
|draft6|
52+
53+
.. draft_specific::
54+
55+
--Draft 4
56+
This is where anything pertaining to an old draft would be mentioned.
57+
58+
3859
Examples
3960
--------
4061

source/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ validator---just yet.
2424

2525
.. note::
2626

27-
This book describes JSON Schema draft 4. The most recent version is draft 7
27+
This book describes JSON Schema draft 6. The most recent version is draft 7
2828
--- stay tuned, updates are coming! Earlier and later versions of JSON Schema
2929
are not completely compatible with the format described here.
3030

source/reference/array.rst

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,15 @@ array may be of a different type.
3434
single: array; items
3535
single: items
3636
single: additionalItems
37+
single: contains
3738

3839
Items
3940
'''''
4041

4142
By default, the elements of the array may be anything at all.
4243
However, it's often useful to validate the items of the array against
43-
some schema as well. This is done using the ``items`` and
44-
``additionalItems`` keywords.
44+
some schema as well. This is done using the ``items``,
45+
``additionalItems``, and ``contains`` keywords.
4546

4647
There are two ways in which arrays are generally used in JSON:
4748

@@ -91,6 +92,29 @@ number:
9192
// The empty array is always valid:
9293
[]
9394

95+
|draft6|
96+
97+
While the ``items`` schema must be valid for **every** item in the array, the
98+
``contains`` schema only needs to validate against one or more items in the
99+
array.
100+
101+
.. schema_example::
102+
103+
{
104+
"type": "array",
105+
"contains": {
106+
"type": "number"
107+
}
108+
}
109+
--
110+
// A single "number" is enough to make this pass:
111+
["life", "universe", "everything", 42]
112+
--X
113+
// But if we have no number, it fails:
114+
["life", "universe", "everything", "forty-two"]
115+
--
116+
// All numbers is, of course, also okay:
117+
[1, 2, 3, 4, 5]
94118

95119
.. index::
96120
single: array; tuple validation

source/reference/generic.rst

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,34 +8,46 @@ for all JSON types.
88
single: metadata
99
single: title
1010
single: description
11+
single: examples
1112

1213
.. _metadata:
1314

1415
Metadata
1516
--------
1617

17-
JSON Schema includes a few keywords, ``title``, ``description`` and
18-
``default``, that aren't strictly used for validation, but are used to
19-
describe parts of a schema.
18+
JSON Schema includes a few keywords, ``title``, ``description``, ``default``, and
19+
``examples`` that aren't strictly used for validation, but are used to describe
20+
parts of a schema.
2021

2122
The ``title`` and ``description`` keywords must be strings. A "title"
2223
will preferably be short, whereas a "description" will provide a more
2324
lengthy explanation about the purpose of the data described by the
2425
schema. Neither are required, but they are encouraged for good
25-
practice.
26+
practice, and can make your schema "self-documenting".
2627

2728
The ``default`` keyword specifies a default value for an item. JSON
2829
processing tools may use this information to provide a default value
2930
for a missing key/value pair, though many JSON schema validators
3031
simply ignore the ``default`` keyword. It should validate against the
3132
schema in which it resides, but that isn't required.
3233

34+
|draft6| The ``examples`` keyword is a place to provide an array of examples
35+
that validate against the schema. This isn't used for validation, but may help
36+
with explaining the effect and purpose of the schema to a reader. Each entry
37+
should validate against the schema in which is resides, but that isn't strictly
38+
required. There is no need to duplicate the ``default`` value in the
39+
``examples`` array, since ``default`` will be treated as another example.
40+
3341
.. schema_example::
3442

3543
{
3644
"title" : "Match anything",
3745
"description" : "This is a schema that matches anything.",
38-
"default" : "Default value"
46+
"default" : "Default value",
47+
"examples" : [
48+
"Anything",
49+
4035
50+
]
3951
}
4052

4153
.. index::
@@ -97,3 +109,38 @@ be valid against the enclosing schema:
97109
// This is in the ``enum``, but it's invalid against ``{ "type":
98110
// "string" }``, so it's ultimately invalid:
99111
null
112+
113+
.. index::
114+
single: const
115+
single: constant values
116+
117+
.. _const:
118+
119+
Constant values
120+
---------------
121+
122+
|draft6|
123+
124+
The ``const`` keyword is used to restrict a value to a single value.
125+
126+
For example, to if you only support shipping to the United States for export reasons:
127+
128+
.. schema_example::
129+
130+
{
131+
"properties": {
132+
"country": {
133+
"const": "United States of America"
134+
}
135+
}
136+
}
137+
--
138+
{ "country": "United States of America" }
139+
--X
140+
{ "country": "Canada" }
141+
142+
It should be noted that ``const`` is merely syntactic sugar for an ``enum`` with a single element, therefore the following are equivalent::
143+
144+
{ "const": "United States of America" }
145+
146+
{ "enum": [ "United States of America" ] }

source/reference/numeric.rst

Lines changed: 51 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -149,46 +149,78 @@ Range
149149
'''''
150150

151151
Ranges of numbers are specified using a combination of the
152-
``minimum``, ``maximum``, ``exclusiveMinimum`` and
153-
``exclusiveMaximum`` keywords.
152+
``minimum`` and ``maximum`` keywords, (or ``exclusiveMinimum`` and
153+
``exclusiveMaximum`` for expressing exclusive range).
154154

155-
- ``minimum`` specifies a minimum numeric value.
155+
If *x* is the value being validated, the following must hold true:
156156

157-
- ``exclusiveMinimum`` is a boolean. When ``true``, it indicates that
158-
the range excludes the minimum value, i.e., :math:`x >
159-
\mathrm{min}`. When ``false`` (or not included), it indicates that
160-
the range includes the minimum value, i.e., :math:`x \ge
161-
\mathrm{min}`.
157+
- *x* ≥ ``minimum``
158+
- *x* > ``exclusiveMinimum``
159+
- *x* ≤ ``maximum``
160+
- *x* < ``exclusiveMaximum``
162161

163-
- ``maximum`` specifies a maximum numeric value.
164-
165-
- ``exclusiveMaximum`` is a boolean. When ``true``, it indicates that
166-
the range excludes the maximum value, i.e., :math:`x <
167-
\mathrm{max}`. When ``false`` (or not included), it indicates that
168-
the range includes the maximum value, i.e., :math:`x \le
169-
\mathrm{max}`.
162+
While you can specify both of ``minimum`` and ``exclusiveMinimum`` or both of
163+
``maximum`` and ``exclusiveMinimum``, it doesn't really make sense to do so.
170164

171165
.. schema_example::
172166

173167
{
174168
"type": "number",
175169
"minimum": 0,
176-
"maximum": 100,
177-
"exclusiveMaximum": true
170+
"exclusiveMaximum": 100
178171
}
179172
--X
180173
// Less than ``minimum``:
181174
-1
182175
--
183-
// ``exclusiveMinimum`` was not specified, so 0 is included:
176+
// ``minimum`` is inclusive, so 0 is valid:
184177
0
185178
--
186179
10
187180
--
188181
99
189182
--X
190-
// ``exclusiveMaximum`` is ``true``, so 100 is not included:
183+
// ``exclusiveMaximum`` is exclusive, so 100 is not valid:
191184
100
192185
--X
193186
// Greater than ``maximum``:
194187
101
188+
189+
.. language_specific::
190+
191+
--Draft 4
192+
In JSON Schema Draft 4, ``exclusiveMinimum`` and ``exclusiveMaximum`` work
193+
differently. There they are boolean values, that indicate whether
194+
``minimum`` and ``maximum`` are exclusive of the value. For example:
195+
196+
- if ``exclusiveMinimum`` is ``false``, *x* ≥ ``minimum``.
197+
- if ``exclusiveMinimum`` is ``true``, *x* > ``minimum``.
198+
199+
This was changed to have better keyword independence.
200+
201+
Here is an example using the older Draft 4 convention:
202+
203+
.. schema_example:: 4
204+
205+
{
206+
"type": "number",
207+
"minimum": 0,
208+
"maximum": 100,
209+
"exclusiveMaximum": true
210+
}
211+
--X
212+
// Less than ``minimum``:
213+
-1
214+
--
215+
// ``exclusiveMinimum`` was not specified, so 0 is included:
216+
0
217+
--
218+
10
219+
--
220+
99
221+
--X
222+
// ``exclusiveMaximum`` is ``true``, so 100 is not included:
223+
100
224+
--X
225+
// Greater than ``maximum``:
226+
101

0 commit comments

Comments
 (0)