Merge pull request #84 from mdboom/draft7

mdboom · web-flow · commit dbd6b03b28d4 · 2019-02-05T16:23:58.000-05:00
Main updates for Draft 7
diff --git a/.travis.yml b/.travis.yml
@@ -11,7 +11,7 @@ branches:
 install:
 - pip install sphinx
 - pip install sphinx_bootstrap_theme
-- pip install git+https://github.com/Julian/jsonschema@97e42bfe2ec8767ffbb76ddb84625c06cbaf0184
+- pip install git+https://github.com/Julian/jsonschema@8cc6a5af0b5ab343707c0c71021c477651aa479b
 - bash -x ./install-texlive.sh
 - export PATH=$PWD/texlive/bin/x86_64-linux:$PATH
 script:
diff --git a/install-texlive.sh b/install-texlive.sh
@@ -19,4 +19,4 @@ tlmgr install cmap ec fancybox titlesec framed fancyvrb threeparttable mdwtools
               changepage xcolor mdframed l3kernel l3packages etoolbox needspace \
               pgf times upquote helvetic fontaxes mweights ms float fncychap \
               tabulary capt-of eqparbox environ trimspaces latexmk ucs varwidth \
-              overlock xkeyval
+              overlock xkeyval niceframe-type1
diff --git a/source/about.rst b/source/about.rst
@@ -156,7 +156,7 @@ for now.  They are explained in subsequent chapters.
       "properties": {
         "first_name": { "type": "string" },
         "last_name": { "type": "string" },
-        "birthday": { "type": "string", "format": "date-time" },
+        "birthday": { "type": "string", "format": "date" },
         "address": {
           "type": "object",
           "properties": {
diff --git a/source/conf.py b/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 = 6
+jsonschema_standard = 7
 
 rst_prolog = """
 .. role:: new
@@ -63,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '6.0'
+version = '7.0'
 # The full version, including alpha/beta/rc tags.
-release = '6.0'
+release = '7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/source/conventions.rst b/source/conventions.rst
@@ -39,16 +39,16 @@ 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
+most important are Draft 7, 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.
+The text is written to encourage the use of Draft 7 and gives priority to the
+latest conventions and features, but where it differs from earlier drafts, those
+differences are highlighted in special call-outs. If you only wish to target
+Draft 7, you can safely ignore those sections.
 
-|draft6|
+|draft7|
 
 .. draft_specific::
 
diff --git a/source/credits.rst b/source/credits.rst
@@ -4,11 +4,12 @@ Acknowledgments
 Michael Droettboom wishes to thank the following contributors:
 
 - Alexander Kjeldaas
+- Alexander Lang
 - Anders D. Johnson
 - Armand Abric
 - Ben Hutton
 - Brandon Wright
-- btubbs
+- Brent Tubbs 
 - Chris Carpenter
 - Christopher Mark Gore
 - David Branner
@@ -18,8 +19,12 @@ Michael Droettboom wishes to thank the following contributors:
 - Fenhl
 - forevermatt
 - goldaxe
+- Henry Andrews
+- Hervé
+- Hongwei
 - Jesse Claven
 - Koen Rouwhorst
 - Mike Kobit
 - Oliver Kurmis
+- Sam Blackman
 - Vincent Jacques
diff --git a/source/index.rst b/source/index.rst
@@ -24,9 +24,9 @@ validator---just yet.
 
 .. note::
 
-    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.
+    This book describes JSON Schema draft 7. Earlier versions of JSON Schema
+    are not completely compatible with the format described here, but for the
+    most part, those differences are noted in the text.
 
 **Where to begin?**
 
diff --git a/source/reference/conditionals.rst b/source/reference/conditionals.rst
@@ -0,0 +1,160 @@
+.. index::
+   single: conditionals
+   single: conditionals; if
+   single: conditionals; then
+   single: conditionals; else
+   single: if
+   single: then
+   single: else
+
+.. _conditionals:
+
+Applying subschemas conditionally
+=================================
+
+|draft7| ``if``, ``then`` and ``else`` keywords
+
+The ``if``, ``then`` and ``else`` keywords allow the application of a subschema
+based on the outcome of another schema, much like the ``if/then/else``
+constructs you've probably seen in traditional programming languages.
+
+If ``if`` is valid, ``then`` must also be valid (and ``else`` is ignored.) If
+``if`` is invalid, ``else`` must also be valid (and ``then`` is ignored).
+
+We can put this in the form of a truth table, showing the combinations of when
+``if``, ``then``, and ``else`` are valid and the resulting validity of the
+entire schema:
+
+==== ==== ==== ============
+if   then else whole schema
+==== ==== ==== ============
+          X    X
+     X          
+     X    X    X
+X               
+X         X     
+X    X         X
+X    X    X    X
+==== ==== ==== ============
+
+For example, let's say you wanted to write a schema to handle addresses in the
+United States and Canada. These countries have different postal code formats,
+and we want to select which format to validate against based on the country. If
+the address is in the United States, the ``postal_code`` field is a "zipcode":
+five numeric digits followed by an optional four digit suffix. If the address is
+in Canada, the ``postal_code`` field is a six digit alphanumeric string where
+letters and numbers alternate.
+
+.. schema_example::
+
+    {
+      "type": "object",
+      "properties": {
+        "street_address": {
+          "type": "string"
+        },
+        "country": {
+          "enum": ["United States of America", "Canada"]
+        }
+      },
+      "if": {
+        "properties": { "country": { "const": "United States of America" } }
+      },
+      "then": {
+        "properties": { "postal_code": { "pattern": "[0-9]{5}(-[0-9]{4})?" } }
+      },
+      "else": { 
+        "properties": { "postal_code": { "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]" } }
+      }
+    }
+    --
+    {
+      "street_address": "1600 Pennsylvania Avenue NW",
+      "country": "United States of America",
+      "postal_code": "20500"
+    } 
+    --
+    {
+      "street_address": "24 Sussex Drive",
+      "country": "Canada",
+      "postal_code": "K1M 1M4"
+    }
+    --X
+    {
+      "street_address": "24 Sussex Drive",
+      "country": "Canada",
+      "postal_code": "10000"
+    }
+
+Unfortunately, this approach above doesn't scale to more than two countries. You
+can, however, wrap pairs of ``if`` and ``then`` inside an ``allOf`` to create
+something that would scale. In this example, we'll use United States and
+Canadian postal codes, but also add Netherlands postal codes, which are 4 digits
+followed by two letters. It's left as an exercise to the reader to expand this
+to the remaining postal codes of the world.
+
+.. schema_example::
+
+    {
+      "type": "object",
+      "properties": {
+        "street_address": {
+          "type": "string"
+        },
+        "country": {
+          "enum": ["United States of America", "Canada", "Netherlands"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "country": { "const": "United States of America" } }
+          },
+          "then": {
+            "properties": { "postal_code": { "pattern": "[0-9]{5}(-[0-9]{4})?" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "country": { "const": "Canada" } }
+          },
+          "then": {
+            "properties": { "postal_code": { "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "country": { "const": "Netherlands" } }
+          },
+          "then": {
+            "properties": { "postal_code": { "pattern": "[0-9]{4} [A-Z]{2}" } }
+          }
+        }
+      ]
+    }
+    --
+    {
+      "street_address": "1600 Pennsylvania Avenue NW",
+      "country": "United States of America",
+      "postal_code": "20500"
+    } 
+    --
+    {
+      "street_address": "24 Sussex Drive",
+      "country": "Canada",
+      "postal_code": "K1M 1M4"
+    }
+    --
+    {
+      "street_address": "Adriaan Goekooplaan",
+      "country": "Netherlands",
+      "postal_code": "2517 JX"
+    }
+    --X
+    {
+      "street_address": "24 Sussex Drive",
+      "country": "Canada",
+      "postal_code": "10000"
+    }
+
+
diff --git a/source/reference/generic.rst b/source/reference/generic.rst
@@ -5,25 +5,27 @@ This chapter lists some miscellaneous properties that are available
 for all JSON types.
 
 .. index::
-   single: metadata
+   single: annotation
    single: title
    single: description
+   single: default
    single: examples
 
-.. _metadata:
+.. _annotation:
 
-Metadata
---------
+Annotations
+-----------
 
-JSON Schema includes a few keywords, ``title``, ``description``, ``default``, and
+JSON Schema includes a few keywords, ``title``, ``description``, ``default``,
 ``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, and can make your schema "self-documenting".
+None of these "annotation" keywords are required, but they are encouraged for
+good practice, and can make your schema "self-documenting".
+
+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.
 
 The ``default`` keyword specifies a default value for an item.  JSON
 processing tools may use this information to provide a default value
@@ -50,6 +52,25 @@ required. There is no need to duplicate the ``default`` value in the
       ]
     }
 
+.. index::
+   single: comment
+   single: $comment
+
+.. _comments:
+
+Comments
+--------
+
+|draft7| ``$comment``
+
+The ``$comment`` keyword is strictly intended for adding comments to the JSON
+schema source. Its value must always be a string. Unlike the annotations
+``title``, ``description`` and ``examples``, JSON schema implementations aren't
+allowed to attach any meaning or behavior to it whatsoever, and may even strip
+them at any time. Therefore, they are useful for leaving notes to future editors
+of a JSON schema, (which is quite likely your future self), but should not be
+used to communicate to users of the schema.
+
 .. index::
    single: enum
    single: enumerated values
diff --git a/source/reference/index.rst b/source/reference/index.rst
@@ -8,12 +8,14 @@ JSON Schema Reference
 
     type.rst
     string.rst
+    regular_expressions.rst
     numeric.rst
     object.rst
     array.rst
     boolean.rst
     null.rst
     generic.rst
+    non_json_data.rst
     combining.rst
+    conditionals.rst
     schema.rst
-    regular_expressions.rst
diff --git a/source/reference/non_json_data.rst b/source/reference/non_json_data.rst
diff --git a/source/reference/schema.rst b/source/reference/schema.rst
diff --git a/source/reference/string.rst b/source/reference/string.rst
diff --git a/source/sphinxext/jsonschemaext.py b/source/sphinxext/jsonschemaext.py
diff --git a/source/structuring.rst b/source/structuring.rst
