Update document to Draft 6

source/basics.rst

@@ -25,6 +25,28 @@ completely valid schema that will accept any valid JSON.
    --
    { "an": [ "arbitrarily", "nested" ], "data": "structure" }
 
+|draft6|
+
+You can also use ``true`` in place of the empty object to represent a schema
+that matches anything, or ``false`` for a schema that matches nothing.
+
+.. schema_example::
+
+   true
+   --
+   // This accepts anything, as long as it's valid JSON
+   42
+   --
+   "I'm a string"
+   --
+   { "an": [ "arbitrarily", "nested" ], "data": "structure" }
+
+.. schema_example::
+
+   false
+   --X
+   "Resistance is futile...  This will always fail!!!"
+
 The type keyword
 ----------------
 
@@ -77,10 +99,17 @@ more information.
 Declaring a unique identifier
 -----------------------------
 
-It is also best practice to include an ``id`` property as a unique
+It is also best practice to include an ``$id`` property as a unique
 identifier for each schema.  For now, just set it to a URL at a domain
 you control, for example::
 
-   { "id": "http://yourdomain.com/schemas/myschema.json" }
+   { "$id": "http://yourdomain.com/schemas/myschema.json" }
 
 The details of `id` become more apparent when you start `structuring`.
+
+|draft6|
+
+.. draft_specific::
+
+    --Draft 4
+    In Draft 4, ``$id`` is just ``id`` (without the dollar-sign).

source/conf.py

@@ -20,7 +20,7 @@
 sys.path.insert(0, os.path.abspath(os.path.dirname('__file__')))
 
 # The standard of JSON Schema to test the examples against
-jsonschema_standard = 4
+jsonschema_standard = 6
 
 rst_prolog = """
 .. role:: new
@@ -55,17 +55,17 @@
 
 # General information about the project.
 project = u'Understanding JSON Schema'
-copyright = u'2013-{0}, Michael Droettboom, Space Telescope Science Institute'.format(
+copyright = u'2013-2016 Michael Droettboom, Space Telescope Science Institute; © 2016-{0} Michael Droettboom'.format(
     datetime.datetime.now().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.9alpha'
+version = '6.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.9alpha'
+release = '6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

source/conventions.rst

@@ -35,6 +35,27 @@ JSON in a few different languages:
     For C, you may want to consider using `Jansson
     <http://www.digip.org/jansson/>`_ to read and write JSON.
 
+Draft-specific notes
+--------------------
+
+The JSON Schema standard has been through a number of revisions or "drafts". The
+most important are Draft 6, the most recent at the time of this writing, and
+Draft 4, on which a lot of production software was built, and the draft for
+which an earlier version of this book was written.
+
+The text is written to encourage the use of Draft 6 and gives
+priority to the latest conventions and features, but where it differs from Draft
+4, those differences are highlighted in special call-outs. If you only wish to
+target Draft 6, you can safely ignore those sections.
+
+|draft6|
+
+.. draft_specific::
+
+   --Draft 4
+   This is where anything pertaining to an old draft would be mentioned.
+
+
 Examples
 --------
 

source/index.rst

@@ -24,7 +24,7 @@ validator---just yet.
 
 .. note::
 
-    This book describes JSON Schema draft 4. The most recent version is draft 7
+    This book describes JSON Schema draft 6. The most recent version is draft 7
     --- stay tuned, updates are coming! Earlier and later versions of JSON Schema
     are not completely compatible with the format described here.
 

source/reference/array.rst

@@ -34,14 +34,15 @@ array may be of a different type.
    single: array; items
    single: items
    single: additionalItems
+   single: contains
 
 Items
 '''''
 
 By default, the elements of the array may be anything at all.
 However, it's often useful to validate the items of the array against
-some schema as well.  This is done using the ``items`` and
-``additionalItems`` keywords.
+some schema as well.  This is done using the ``items``,
+``additionalItems``, and ``contains`` keywords.
 
 There are two ways in which arrays are generally used in JSON:
 
@@ -91,6 +92,29 @@ number:
    // The empty array is always valid:
    []
 
+|draft6|
+
+While the ``items`` schema must be valid for **every** item in the array, the
+``contains`` schema only needs to validate against one or more items in the
+array.
+
+.. schema_example::
+
+   {
+      "type": "array",
+      "contains": {
+        "type": "number"
+      }
+   }
+   --
+   // A single "number" is enough to make this pass:
+   ["life", "universe", "everything", 42]
+   --X
+   // But if we have no number, it fails:
+   ["life", "universe", "everything", "forty-two"]
+   --
+   // All numbers is, of course, also okay:
+   [1, 2, 3, 4, 5]
 
 .. index::
    single: array; tuple validation

source/reference/generic.rst

@@ -8,34 +8,46 @@ for all JSON types.
    single: metadata
    single: title
    single: description
+   single: examples
 
 .. _metadata:
 
 Metadata
 --------
 
-JSON Schema includes a few keywords, ``title``, ``description`` and
-``default``, that aren't strictly used for validation, but are used to
-describe parts of a schema.
+JSON Schema includes a few keywords, ``title``, ``description``, ``default``, and
+``examples`` that aren't strictly used for validation, but are used to describe
+parts of a schema.
 
 The ``title`` and ``description`` keywords must be strings.  A "title"
 will preferably be short, whereas a "description" will provide a more
 lengthy explanation about the purpose of the data described by the
 schema.  Neither are required, but they are encouraged for good
-practice.
+practice, and can make your schema "self-documenting".
 
 The ``default`` keyword specifies a default value for an item.  JSON
 processing tools may use this information to provide a default value
 for a missing key/value pair, though many JSON schema validators
 simply ignore the ``default`` keyword.  It should validate against the
 schema in which it resides, but that isn't required.
 
+|draft6| The ``examples`` keyword is a place to provide an array of examples
+that validate against the schema. This isn't used for validation, but may help
+with explaining the effect and purpose of the schema to a reader. Each entry
+should validate against the schema in which is resides, but that isn't strictly
+required. There is no need to duplicate the ``default`` value in the
+``examples`` array, since ``default`` will be treated as another example.
+
 .. schema_example::
 
     {
       "title" : "Match anything",
       "description" : "This is a schema that matches anything.",
-      "default" : "Default value"
+      "default" : "Default value",
+      "examples" : [
+        "Anything",
+        4035
+      ]
     }
 
 .. index::
@@ -97,3 +109,38 @@ be valid against the enclosing schema:
    // This is in the ``enum``, but it's invalid against ``{ "type":
    // "string" }``, so it's ultimately invalid:
    null
+
+.. index::
+   single: const
+   single: constant values
+
+.. _const:
+
+Constant values
+---------------
+
+|draft6|
+
+The ``const`` keyword is used to restrict a value to a single value.
+
+For example, to if you only support shipping to the United States for export reasons:
+
+.. schema_example::
+
+   {
+     "properties": {
+       "country": {
+         "const": "United States of America"
+       }
+     }
+   }
+   --
+   { "country": "United States of America" }
+   --X
+   { "country": "Canada" }
+
+It should be noted that ``const`` is merely syntactic sugar for an ``enum`` with a single element, therefore the following are equivalent::
+
+  { "const": "United States of America" }
+
+  { "enum": [ "United States of America" ] }

source/reference/numeric.rst

@@ -149,46 +149,78 @@ Range
 '''''
 
 Ranges of numbers are specified using a combination of the
-``minimum``, ``maximum``, ``exclusiveMinimum`` and
-``exclusiveMaximum`` keywords.
+``minimum`` and ``maximum`` keywords, (or ``exclusiveMinimum`` and
+``exclusiveMaximum`` for expressing exclusive range).
 
-- ``minimum`` specifies a minimum numeric value.
+If *x* is the value being validated, the following must hold true:
 
-- ``exclusiveMinimum`` is a boolean.  When ``true``, it indicates that
-  the range excludes the minimum value, i.e., :math:`x >
-  \mathrm{min}`.  When ``false`` (or not included), it indicates that
-  the range includes the minimum value, i.e., :math:`x \ge
-  \mathrm{min}`.
+  - *x* ≥ ``minimum``
+  - *x* > ``exclusiveMinimum``
+  - *x* ≤ ``maximum``
+  - *x* < ``exclusiveMaximum``
 
-- ``maximum`` specifies a maximum numeric value.
-
-- ``exclusiveMaximum`` is a boolean.  When ``true``, it indicates that
-  the range excludes the maximum value, i.e., :math:`x <
-  \mathrm{max}`.  When ``false`` (or not included), it indicates that
-  the range includes the maximum value, i.e., :math:`x \le
-  \mathrm{max}`.
+While you can specify both of ``minimum`` and ``exclusiveMinimum`` or both of
+``maximum`` and ``exclusiveMinimum``, it doesn't really make sense to do so.
 
 .. schema_example::
 
     {
       "type": "number",
       "minimum": 0,
-      "maximum": 100,
-      "exclusiveMaximum": true
+      "exclusiveMaximum": 100
     }
     --X
     // Less than ``minimum``:
     -1
     --
-    // ``exclusiveMinimum`` was not specified, so 0 is included:
+    // ``minimum`` is inclusive, so 0 is valid:
     0
     --
     10
     --
     99
     --X
-    // ``exclusiveMaximum`` is ``true``, so 100 is not included:
+    // ``exclusiveMaximum`` is exclusive, so 100 is not valid:
     100
     --X
     // Greater than ``maximum``:
     101
+
+.. language_specific::
+
+    --Draft 4
+    In JSON Schema Draft 4, ``exclusiveMinimum`` and ``exclusiveMaximum`` work
+    differently. There they are boolean values, that indicate whether
+    ``minimum`` and ``maximum`` are exclusive of the value. For example:
+
+    - if ``exclusiveMinimum`` is ``false``, *x* ≥ ``minimum``.
+    - if ``exclusiveMinimum`` is ``true``, *x* > ``minimum``.
+
+    This was changed to have better keyword independence.
+
+    Here is an example using the older Draft 4 convention:
+
+    .. schema_example:: 4
+
+        {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "exclusiveMaximum": true
+        }
+        --X
+        // Less than ``minimum``:
+        -1
+        --
+        // ``exclusiveMinimum`` was not specified, so 0 is included:
+        0
+        --
+        10
+        --
+        99
+        --X
+        // ``exclusiveMaximum`` is ``true``, so 100 is not included:
+        100
+        --X
+        // Greater than ``maximum``:
+        101