From 1fa7006f84375006ac80e6f13b7f104978b9a5fc Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 9 Nov 2018 16:19:32 -0500 Subject: [PATCH 01/21] Basic upgrading of the defaults to draft 7 --- source/conf.py | 6 +++--- source/conventions.rst | 12 ++++++------ source/index.rst | 6 +++--- source/reference/schema.rst | 1 + source/sphinxext/jsonschemaext.py | 3 ++- source/structuring.rst | 6 +++--- 6 files changed, 18 insertions(+), 16 deletions(-) diff --git a/source/conf.py b/source/conf.py index 0e398358..e36ed065 100644 --- 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 index 175b9a51..f38ec4d9 100644 --- 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/index.rst b/source/index.rst index 72dbf64d..39b4ff45 100644 --- 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/schema.rst b/source/reference/schema.rst index 9d002ee8..0ec81d71 100644 --- a/source/reference/schema.rst +++ b/source/reference/schema.rst @@ -24,6 +24,7 @@ If you need to declare that your schema was written against a specific version of the JSON Schema standard, you should include the draft name in the path, for example: +- ``http://json-schema.org/draft-07/schema#`` - ``http://json-schema.org/draft-06/schema#`` - ``http://json-schema.org/draft-04/schema#`` diff --git a/source/sphinxext/jsonschemaext.py b/source/sphinxext/jsonschemaext.py index d47881fd..8087f12c 100644 --- a/source/sphinxext/jsonschemaext.py +++ b/source/sphinxext/jsonschemaext.py @@ -12,7 +12,8 @@ def get_standard_cls(standard): return { 3: jsonschema.validators.Draft3Validator, 4: jsonschema.validators.Draft4Validator, - 6: jsonschema.validators.Draft6Validator}[standard] + 6: jsonschema.validators.Draft6Validator, + 7: jsonschema.validators.Draft7Validator}[standard] class jsonschema_node(nodes.Element): diff --git a/source/structuring.rst b/source/structuring.rst index 54649667..d33ea388 100644 --- a/source/structuring.rst +++ b/source/structuring.rst @@ -106,7 +106,7 @@ schema for a customer: .. schema_example:: { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "address": { @@ -159,7 +159,7 @@ For example, you might have a ``person`` schema that has an array of ``children` .. schema_example:: { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "person": { @@ -290,7 +290,7 @@ address schema, and refer to it by that instead. .. schema_example:: { - "$schema": "http://json-schema.org/draft-06/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "address": { From 5fc2a9464f519261ea7956ff1758a750fd2f868b Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 9 Nov 2018 16:23:56 -0500 Subject: [PATCH 02/21] Document new $comment keyword --- source/reference/generic.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/source/reference/generic.rst b/source/reference/generic.rst index ca7a63cd..0763ef9d 100644 --- a/source/reference/generic.rst +++ b/source/reference/generic.rst @@ -8,22 +8,29 @@ for all JSON types. single: metadata single: title single: description + single: default single: examples + single: $comment .. _metadata: Metadata -------- -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. +JSON Schema includes a few keywords, ``title``, ``description``, ``default``, +``examples``, and ``$comment`` 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". +|draft7| ``$comment`` + +The ``title``, ``description``, and ``$comment`` 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. +``$comment`` is intended for notes to schema maintainers, while ``title`` and +``description`` are meant for display to end users. This is somewhat analogous +to the distinction between comments and docstrings in source code. None of these +are required, but they are encouraged for good 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 From 71e9fcd37665874635a7358b7921c763900079ca Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 9 Nov 2018 17:40:30 -0500 Subject: [PATCH 03/21] Better errors from invalidation --- source/sphinxext/jsonschemaext.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/sphinxext/jsonschemaext.py b/source/sphinxext/jsonschemaext.py index 8087f12c..f600f46c 100644 --- a/source/sphinxext/jsonschemaext.py +++ b/source/sphinxext/jsonschemaext.py @@ -117,6 +117,7 @@ def run(self): cls=standard) except jsonschema.ValidationError as e: is_valid = False + message = str(e) except jsonschema.SchemaError as e: raise ValueError("Schema is invalid:\n{0}\n\n{1}".format( str(e), schema.content)) @@ -126,7 +127,8 @@ def run(self): raise ValueError( "Doc says fragment should pass, " "but it does not validate:\n" + - part.content) + part.content + "\n" + + message) else: raise ValueError( "Doc says fragment should not pass, " From e169b1d926c2851268814b7b21216e90f76a2b3c Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 9 Nov 2018 17:43:51 -0500 Subject: [PATCH 04/21] Describe conditionals --- source/reference/conditionals.rst | 161 ++++++++++++++++++++++++++++++ source/reference/index.rst | 3 +- 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 source/reference/conditionals.rst diff --git a/source/reference/conditionals.rst b/source/reference/conditionals.rst new file mode 100644 index 00000000..71075175 --- /dev/null +++ b/source/reference/conditionals.rst @@ -0,0 +1,161 @@ +.. 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 +==== ==== ==== ============ +✗ ✗ ✗ ✗ +✗ ✗ ✓ ✓ +✗ ✓ ✗ ✗ +✗ ✓ ✓ ✓ +✓ ✗ ✗ ✗ +✓ ✗ ✓ ✗ +✓ ✓ ✗ ✓ +✓ ✓ ✓ ✓ +==== ==== ==== ============ + +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/index.rst b/source/reference/index.rst index 2054127d..1f69a974 100644 --- a/source/reference/index.rst +++ b/source/reference/index.rst @@ -8,6 +8,7 @@ JSON Schema Reference type.rst string.rst + regular_expressions.rst numeric.rst object.rst array.rst @@ -15,5 +16,5 @@ JSON Schema Reference null.rst generic.rst combining.rst + conditionals.rst schema.rst - regular_expressions.rst From 1d52aa745a8f5f2b8116ecc9b921308ee283f501 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 15:34:04 -0500 Subject: [PATCH 05/21] Improve format index --- source/reference/string.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/source/reference/string.rst b/source/reference/string.rst index ecf4e8d1..38fd0183 100644 --- a/source/reference/string.rst +++ b/source/reference/string.rst @@ -130,15 +130,24 @@ custom format types. A JSON Schema validator will ignore any format type that it does not understand. .. index:: + single: format; date-time + single: format; email + single: format; hostname + single: format; ipv4 + single: format; ipv6 + single: format; json-pointer + single: format; uri + single: format; uri-reference + single: format; uri-template single: date-time single: email single: hostname single: ipv4 single: ipv6 + single: json-pointer single: uri single: uri-reference single: uri-template - single: json-pointer Built-in formats ^^^^^^^^^^^^^^^^ From d9e95f2aba3a605d244e6a74c132384f2ce031f0 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 15:34:11 -0500 Subject: [PATCH 06/21] Rename metadata -> annotation --- source/reference/generic.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/reference/generic.rst b/source/reference/generic.rst index 0763ef9d..86f4cd89 100644 --- a/source/reference/generic.rst +++ b/source/reference/generic.rst @@ -5,17 +5,17 @@ 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 single: $comment -.. _metadata: +.. _annotation: -Metadata --------- +Annotations +----------- JSON Schema includes a few keywords, ``title``, ``description``, ``default``, ``examples``, and ``$comment`` that aren't strictly used for validation, but are From bb7eaae8b5d67bf9c3c0d0aea805eadfb465d9ee Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:35:52 -0500 Subject: [PATCH 07/21] Add section on Media / non-JSON-data --- source/reference/index.rst | 1 + source/reference/non_json_data.rst | 87 ++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 source/reference/non_json_data.rst diff --git a/source/reference/index.rst b/source/reference/index.rst index 1f69a974..d5b95d2f 100644 --- a/source/reference/index.rst +++ b/source/reference/index.rst @@ -15,6 +15,7 @@ JSON Schema Reference boolean.rst null.rst generic.rst + non_json_data.rst combining.rst conditionals.rst schema.rst diff --git a/source/reference/non_json_data.rst b/source/reference/non_json_data.rst new file mode 100644 index 00000000..0e8f58c4 --- /dev/null +++ b/source/reference/non_json_data.rst @@ -0,0 +1,87 @@ +.. index:: + single: non-JSON data + single: media + +.. _media: + +Media: string-encoding non-JSON data +------------------------------------ + +|draft7| + +JSON schema has a set of keywords to describe and optionally validate non-JSON +data stored inside JSON strings. Since it would be difficult to write validators +for many media types, JSON schema validators are not required to validate the +contents of JSON strings based on these keywords. At the time of this writing, +it appears that most of them do not. However, these keywords are still useful +for an application that consumes validated JSON. + +.. index:: + single: contentMediaType + single: media; contentMediaType + +contentMediaType +```````````````` + +The ``contentMediaType`` keyword specifies the MIME type of the contents of a +string, as described in `RFC 2046 `_. +There is a list of `MIME types officially registered by the IANA +`_, but the set +of types supported will be application and operating system dependent. Mozilla +Developer Network also maintains a `shorter list of MIME types that are +important for the web +`_ + +.. index:: + single: contentEncoding + single: media; contentEncoding + +contentEncoding +``````````````` + +The ``contentEncoding`` keyword specifies the encoding used to store the +contents, as specified in `RFC 2054, part 6.1 +`_. + +The acceptable values are ``7bit``, ``8bit``, ``binary``, ``quoted-printable`` +and ``base64``. If not specified, the encoding is the same as the containing +JSON document. + +Without getting into the low-level details of each of these encodings, there are +really only two options useful for modern usage: + +- If the string contains a binary MIME type (``image/png``, for example), set + ``contentEncoding`` to ``base64`` and encode the contents using `Base64 + `_. + +- If the string contains a text MIME type (usually indicated with the ``text/`` + prefix), leave ``contentEncoding`` unspecified, and encode the contents using + the same encoding as the enclosing JSON document. + +Examples +```````` + +The following schema indicates that a string contains a `PNG +`_ image, encoded using Base64: + +.. schema_example:: + + { + "type": "string", + "contentEncoding": "base64", + "contentMediaType": "image/png" + } + -- + "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..." + +The following schema indicates the string contains an HTML document, encoded +using the same encoding as the surrounding document: + +.. schema_example:: + + { + "type": "string", + "contentMediaType": "text/html" + } + -- + "" From 715fb5ada209e2d7af6c8b92cfbf118c9b3280f9 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:37:51 -0500 Subject: [PATCH 08/21] Updates for new format types --- source/reference/string.rst | 152 ++++++++++++++++++++++++++++-------- 1 file changed, 118 insertions(+), 34 deletions(-) diff --git a/source/reference/string.rst b/source/reference/string.rst index 38fd0183..8650e116 100644 --- a/source/reference/string.rst +++ b/source/reference/string.rst @@ -130,24 +130,7 @@ custom format types. A JSON Schema validator will ignore any format type that it does not understand. .. index:: - single: format; date-time - single: format; email - single: format; hostname - single: format; ipv4 - single: format; ipv6 - single: format; json-pointer - single: format; uri - single: format; uri-reference - single: format; uri-template - single: date-time - single: email - single: hostname - single: ipv4 - single: ipv6 - single: json-pointer - single: uri - single: uri-reference - single: uri-template + single: format Built-in formats ^^^^^^^^^^^^^^^^ @@ -155,15 +138,67 @@ Built-in formats The following is the list of formats specified in the JSON Schema specification. -- ``"date-time"``: Date representation, as defined by `RFC 3339, section - 5.6 `_. +.. index:: + single: date-time + single: time + single: date + single: format; date-time + single: format; time + single: format; date + +Dates and times +*************** + +Dates and times are represented in `ISO8601 format +`_. + +- ``"date-time"``: Date and time together, for example, + ``2018-11-13T20:20:39+00:00``. + +- ``"time"``: |draft7| Time, for example, ``20:20:39+00:00`` + +- ``"date"``: |draft7| Date, for example, ``2018-11-13``. + +.. index:: + single: email + single: idn-email + single: format; email + single: format; idn-email + +Email addresses +*************** - ``"email"``: Internet email address, see `RFC 5322, section 3.4.1 `_. +- ``"idn-email"``: |draft7| The internationalized form of an Internet email address, see + `RFC 6531 `_. + +.. index:: + single: hostname + single: idn-hostname + single: format; hostname + single: format; idn-hostname + +Hostnames +********* + - ``"hostname"``: Internet host name, see `RFC 1034, section 3.1 `_. +- ``"idn-hostname"``: |draft7| An internationalized Internet host name, see + `RFC5890, section 2.3.2.3 + `_. + +.. index:: + single: ipv4 + single: ipv6 + single: format; ipv4 + single: format; ipv6 + +IP Addresses +************ + - ``"ipv4"``: IPv4 address, according to dotted-quad ABNF syntax as defined in `RFC 2673, section 3.2 `_. @@ -171,6 +206,19 @@ specification. - ``"ipv6"``: IPv6 address, as defined in `RFC 2373, section 2.2 `_. +.. index:: + single: uri + single: uri-reference + single: iri + single: iri-reference + single: format; uri + single: format; uri-reference + single: format; iri + single: format; iri-reference + +Resource identifiers +******************** + - ``"uri"``: A universal resource identifier (URI), according to `RFC3986 `_. @@ -178,24 +226,16 @@ specification. relative-reference), according to `RFC3986, section 4.1 `_. -- ``"json-pointer"``: |draft6| A JSON Pointer, according to `RFC6901 - `_. There is more discussion on the use - of JSON Pointer within JSON Schema in `structuring`. Note that this should be - used only when the entire string contains only JSON Pointer content, e.g. - ``/foo/bar``. JSON Pointer URI fragments, e.g. ``#/foo/bar/`` should use - ``"uri"`` or ``"uri-reference"``. - -- ``"uri-template"``: |draft6| A URI Template (of any level) according to - `RFC6570 `_. If you don't already know - what a URI Template is, you probably don't need this value. +- ``"iri"``: |draft7| The internationalized equivalent of a "uri", + according to `RFC3987 `_. -URI vs. URI reference -````````````````````` +- ``"iri-reference"``: |draft7| The internationalized equivalent of a + "uri-reference", according to `RFC3987 `_ If the values in the schema the ability to be relative to a particular source path (such as a link from a webpage), it is generally better practice to use -``"uri-reference"`` rather than ``"uri"``. ``"uri"`` should only be used when -the path must be absolute. +``"uri-reference"`` (or ``"iri-reference"``) rather than ``"uri"`` (or +``"iri"``). ``"uri"`` should only be used when the path must be absolute. .. draft_specific:: @@ -203,5 +243,49 @@ the path must be absolute. Draft 4 only includes ``"uri"``, not ``"uri-reference"``. Therefore, there is some ambiguity around whether ``"uri"`` should accept relative paths. +.. index:: + single: uri-template + single: format; uri-template + +URI template +************ + +- ``"uri-template"``: |draft6| A URI Template (of any level) according to + `RFC6570 `_. If you don't already know + what a URI Template is, you probably don't need this value. + +.. index:: + single: json-pointer + single: relative-json-pointer + single: format; json-pointer + single: format; relative-json-pointer + +JSON Pointer +************ + +- ``"json-pointer"``: |draft6| A JSON Pointer, according to `RFC6901 + `_. There is more discussion on the use + of JSON Pointer within JSON Schema in `structuring`. Note that this should be + used only when the entire string contains only JSON Pointer content, e.g. + ``/foo/bar``. JSON Pointer URI fragments, e.g. ``#/foo/bar/`` should us e + ``"uri"`` or ``"uri-reference"``. + +- ``"relative-json-pointer"``: |draft7| A `relative JSON pointer + `_. + +.. index:: + single: regex + single: format; regex + +Regular Expressions +******************* + +- ``"regex"``: |draft7| A regular expression, which should be valid according to + the `ECMA 262 + ` + dialect. + +Be careful, in practice, JSON schema validators are only required to accept the +safe subset of `regular_expressions` described elsewhere in this document. .. TODO: Add some examples for ``format`` here From 29ec90fdb259bcd2dba3ffcec86ec89fa3dd46b8 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:39:36 -0500 Subject: [PATCH 09/21] Small clarification --- source/reference/generic.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/reference/generic.rst b/source/reference/generic.rst index 86f4cd89..e1e7ac53 100644 --- a/source/reference/generic.rst +++ b/source/reference/generic.rst @@ -28,9 +28,10 @@ The ``title``, ``description``, and ``$comment`` keywords must be strings. A lengthy explanation about the purpose of the data described by the schema. ``$comment`` is intended for notes to schema maintainers, while ``title`` and ``description`` are meant for display to end users. This is somewhat analogous -to the distinction between comments and docstrings in source code. None of these -are required, but they are encouraged for good practice, and can make your -schema "self-documenting". +to the distinction between comments and docstrings in source code. + +None of these "annotation" keywords are required, but they are encouraged for +good 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 From fdaeb17fb203b61097b1bcbfc42bd6567370c30d Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:45:47 -0500 Subject: [PATCH 10/21] Update version of jsonschema --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 42a73030..bba48575 100644 --- 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: From 4c68a8690427ba35db3b9552602cc7e814203ca8 Mon Sep 17 00:00:00 2001 From: hongwei1 Date: Fri, 17 Aug 2018 12:17:05 +0200 Subject: [PATCH 11/21] fixed "birthday" in from `date` to `date-time` --- source/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/about.rst b/source/about.rst index ce1bfc81..0fdf83a8 100644 --- 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": { From 10a54b8a3e76fe878c0a1a303d4d27bfc7adcf52 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:50:41 -0500 Subject: [PATCH 12/21] Update credits --- source/credits.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/credits.rst b/source/credits.rst index 55bc6104..03642c66 100644 --- 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,11 @@ Michael Droettboom wishes to thank the following contributors: - Fenhl - forevermatt - goldaxe +- Hervé +- Hongwei - Jesse Claven - Koen Rouwhorst - Mike Kobit - Oliver Kurmis +- Sam Blackman - Vincent Jacques From 92074e2ea336bcfe03793ff26190a54572620349 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 16:55:40 -0500 Subject: [PATCH 13/21] Fix typos --- source/reference/string.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/string.rst b/source/reference/string.rst index 8650e116..c32cdd0e 100644 --- a/source/reference/string.rst +++ b/source/reference/string.rst @@ -282,10 +282,10 @@ Regular Expressions - ``"regex"``: |draft7| A regular expression, which should be valid according to the `ECMA 262 - ` + `_ dialect. Be careful, in practice, JSON schema validators are only required to accept the -safe subset of `regular_expressions` described elsewhere in this document. +safe subset of `regular-expressions` described elsewhere in this document. .. TODO: Add some examples for ``format`` here From 40ae42b01d968c09c7fccff5c002cf66cc3c7132 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 13 Nov 2018 17:08:56 -0500 Subject: [PATCH 14/21] Disable LaTeX output for now --- .travis.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index bba48575..fdba0aba 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,8 +15,7 @@ install: - bash -x ./install-texlive.sh - export PATH=$PWD/texlive/bin/x86_64-linux:$PATH script: -- make html latexpdf -- cp build/latex/*.pdf build/html +- make html - touch build/html/.nojekyll deploy: provider: pages From d386e5c1c2a625c932b891c1dd6541a90f3fb8ad Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 30 Nov 2018 14:11:55 -0500 Subject: [PATCH 15/21] Reinstate LaTeX --- .travis.yml | 2 +- install-texlive.sh | 2 +- source/reference/conditionals.rst | 15 +++++++-------- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/.travis.yml b/.travis.yml index fdba0aba..57ef6851 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,7 +15,7 @@ install: - bash -x ./install-texlive.sh - export PATH=$PWD/texlive/bin/x86_64-linux:$PATH script: -- make html +- make html latexpdf - touch build/html/.nojekyll deploy: provider: pages diff --git a/install-texlive.sh b/install-texlive.sh index 08d392ec..57e45f5f 100755 --- 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/reference/conditionals.rst b/source/reference/conditionals.rst index 71075175..17d32cc8 100644 --- a/source/reference/conditionals.rst +++ b/source/reference/conditionals.rst @@ -28,14 +28,13 @@ 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 From e14a6931408ce6ffeb493cccb4a64ad9fbccafc0 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:31:41 -0500 Subject: [PATCH 16/21] Describe $comment separately from description and title --- source/reference/generic.rst | 37 ++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/source/reference/generic.rst b/source/reference/generic.rst index e1e7ac53..4c883994 100644 --- a/source/reference/generic.rst +++ b/source/reference/generic.rst @@ -10,7 +10,6 @@ for all JSON types. single: description single: default single: examples - single: $comment .. _annotation: @@ -18,21 +17,16 @@ Annotations ----------- JSON Schema includes a few keywords, ``title``, ``description``, ``default``, -``examples``, and ``$comment`` that aren't strictly used for validation, but are -used to describe parts of a schema. - -|draft7| ``$comment`` - -The ``title``, ``description``, and ``$comment`` 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. -``$comment`` is intended for notes to schema maintainers, while ``title`` and -``description`` are meant for display to end users. This is somewhat analogous -to the distinction between comments and docstrings in source code. +``examples`` that aren't strictly used for validation, but are used to describe +parts of a schema. 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 for a missing key/value pair, though many JSON schema validators @@ -58,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 From 8606772a9f4cca7a4cb180af033a0432c8dc6880 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:32:18 -0500 Subject: [PATCH 17/21] Clarify text vs. binary document types --- source/reference/non_json_data.rst | 38 +++++++++++++++++------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/source/reference/non_json_data.rst b/source/reference/non_json_data.rst index 0e8f58c4..1af89efc 100644 --- a/source/reference/non_json_data.rst +++ b/source/reference/non_json_data.rst @@ -50,38 +50,42 @@ JSON document. Without getting into the low-level details of each of these encodings, there are really only two options useful for modern usage: -- If the string contains a binary MIME type (``image/png``, for example), set - ``contentEncoding`` to ``base64`` and encode the contents using `Base64 - `_. +- If the content is encoded in the same encoding as the enclosing JSON document + (which for practical purposes, is almost always UTF-8), leave + ``contentEncoding`` unspecified, and include the content in a string as-is. + This includes text-based content types, such as ``text/html`` or + ``application/xml``. -- If the string contains a text MIME type (usually indicated with the ``text/`` - prefix), leave ``contentEncoding`` unspecified, and encode the contents using - the same encoding as the enclosing JSON document. +- If the content is binary data, set ``contentEncoding`` to ``base64`` and + encode the contents using `Base64 `_. + This would include many image types, such as ``image/png`` or audio types, + such as ``audio/mpeg``. Examples ```````` -The following schema indicates that a string contains a `PNG -`_ image, encoded using Base64: +The following schema indicates the string contains an HTML document, encoded +using the same encoding as the surrounding document: .. schema_example:: { "type": "string", - "contentEncoding": "base64", - "contentMediaType": "image/png" - } + "contentMediaType": "text/html" + } -- - "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..." + "" -The following schema indicates the string contains an HTML document, encoded -using the same encoding as the surrounding document: +The following schema indicates that a string contains a `PNG +`_ image, encoded using Base64: .. schema_example:: { "type": "string", - "contentMediaType": "text/html" - } + "contentEncoding": "base64", + "contentMediaType": "image/png" + } -- - "" + "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..." + From 043dc0ba71390aaf5cc32945f5c68d52906c7173 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:32:45 -0500 Subject: [PATCH 18/21] Be more specific about time format used. --- source/reference/string.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/reference/string.rst b/source/reference/string.rst index c32cdd0e..10117af2 100644 --- a/source/reference/string.rst +++ b/source/reference/string.rst @@ -149,7 +149,9 @@ specification. Dates and times *************** -Dates and times are represented in `ISO8601 format +Dates and times are represented in `RFC 3339, section 5.6 +`_. This is +a subset of the date format also commonly known as `ISO8601 format `_. - ``"date-time"``: Date and time together, for example, From f7c10903cd81eae31ddacf673609acc72b187d31 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:33:06 -0500 Subject: [PATCH 19/21] Use `url-reference` rather than `url` for JSON schema fragment --- source/reference/string.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/string.rst b/source/reference/string.rst index 10117af2..fe6ec3f5 100644 --- a/source/reference/string.rst +++ b/source/reference/string.rst @@ -269,8 +269,8 @@ JSON Pointer `_. There is more discussion on the use of JSON Pointer within JSON Schema in `structuring`. Note that this should be used only when the entire string contains only JSON Pointer content, e.g. - ``/foo/bar``. JSON Pointer URI fragments, e.g. ``#/foo/bar/`` should us e - ``"uri"`` or ``"uri-reference"``. + ``/foo/bar``. JSON Pointer URI fragments, e.g. ``#/foo/bar/`` should use + ``"uri-reference"``. - ``"relative-json-pointer"``: |draft7| A `relative JSON pointer `_. From 34693e293324a4afe7d9840e79b6f7e178f48bbb Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:41:01 -0500 Subject: [PATCH 20/21] Credit Henry Andrews --- source/credits.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/credits.rst b/source/credits.rst index 03642c66..800e899d 100644 --- a/source/credits.rst +++ b/source/credits.rst @@ -19,6 +19,7 @@ Michael Droettboom wishes to thank the following contributors: - Fenhl - forevermatt - goldaxe +- Henry Andrews - Hervé - Hongwei - Jesse Claven From cb6907024aa7bd9e03207b6944fb81ff6d487ea0 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Tue, 22 Jan 2019 09:42:02 -0500 Subject: [PATCH 21/21] Reinstate installation of PDF file --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index 57ef6851..bba48575 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,6 +16,7 @@ install: - export PATH=$PWD/texlive/bin/x86_64-linux:$PATH script: - make html latexpdf +- cp build/latex/*.pdf build/html - touch build/html/.nojekyll deploy: provider: pages