1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
==========
jsonschema
==========
|PyPI| |Pythons| |Travis| |AppVeyor| |Codecov| |ReadTheDocs|
.. |PyPI| image:: https://img.shields.io/pypi/v/jsonschema.svg
:alt: PyPI version
:target: https://pypi.org/project/jsonschema/
.. |Pythons| image:: https://img.shields.io/pypi/pyversions/jsonschema.svg
:alt: Supported Python versions
:target: https://pypi.org/project/jsonschema/
.. |Travis| image:: https://travis-ci.com/Julian/jsonschema.svg?branch=master
:alt: Travis build status
:target: https://travis-ci.com/Julian/jsonschema
.. |AppVeyor| image:: https://ci.appveyor.com/api/projects/status/adtt0aiaihy6muyn/branch/master?svg=true
:alt: AppVeyor build status
:target: https://ci.appveyor.com/project/Julian/jsonschema
.. |Codecov| image:: https://codecov.io/gh/Julian/jsonschema/branch/master/graph/badge.svg
:alt: Codecov Code coverage
:target: https://codecov.io/gh/Julian/jsonschema
.. |ReadTheDocs| image:: https://readthedocs.org/projects/python-jsonschema/badge/?version=stable&style=flat
:alt: ReadTheDocs status
:target: https://python-jsonschema.readthedocs.io/en/stable/
``jsonschema`` is an implementation of `JSON Schema <https://json-schema.org>`_
for Python (supporting 2.7+ including Python 3).
.. code-block:: python
>>> from jsonschema import validate
>>> # A sample schema, like what we'd get from json.load()
>>> schema = {
... "type" : "object",
... "properties" : {
... "price" : {"type" : "number"},
... "name" : {"type" : "string"},
... },
... }
>>> # If no exception is raised by validate(), the instance is valid.
>>> validate(instance={"name" : "Eggs", "price" : 34.99}, schema=schema)
>>> validate(
... instance={"name" : "Eggs", "price" : "Invalid"}, schema=schema,
... ) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
ValidationError: 'Invalid' is not of type 'number'
It can also be used from console:
.. code-block:: bash
$ jsonschema -i sample.json sample.schema
Features
--------
* Full support for
`Draft 7 <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.Draft7Validator>`_,
`Draft 6 <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.Draft6Validator>`_,
`Draft 4 <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.Draft4Validator>`_
and
`Draft 3 <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.Draft3Validator>`_
* `Lazy validation <https://python-jsonschema.readthedocs.io/en/latest/validate/#jsonschema.IValidator.iter_errors>`_
that can iteratively report *all* validation errors.
* `Programmatic querying <https://python-jsonschema.readthedocs.io/en/latest/errors/>`_
of which properties or items failed validation.
Installation
------------
``jsonschema`` is available on `PyPI <https://pypi.org/project/jsonschema/>`_. You can install using `pip <https://pip.pypa.io/en/stable/>`_:
.. code-block:: bash
$ pip install jsonschema
Demo
----
Try ``jsonschema`` interactively in this online demo:
.. image:: https://user-images.githubusercontent.com/1155573/56745335-8b158a00-6750-11e9-8776-83fa675939c4.png
:target: https://notebooks.ai/demo/gh/Julian/jsonschema
:alt: Open Live Demo
Online demo Notebook will look similar to this:
.. image:: https://user-images.githubusercontent.com/1155573/56820861-5c1c1880-6823-11e9-802a-ce01c5ec574f.gif
:alt: Open Live Demo
:width: 480 px
Release Notes
-------------
v3.1 brings support for ECMA 262 dialect regular expressions
throughout schemas, as recommended by the specification. Big
thanks to @Zac-HD for authoring support in a new `js-regex
<https://pypi.org/project/js-regex/>`_ library.
Running the Test Suite
----------------------
If you have ``tox`` installed (perhaps via ``pip install tox`` or your
package manager), running ``tox`` in the directory of your source
checkout will run ``jsonschema``'s test suite on all of the versions
of Python ``jsonschema`` supports. If you don't have all of the
versions that ``jsonschema`` is tested under, you'll likely want to run
using ``tox``'s ``--skip-missing-interpreters`` option.
Of course you're also free to just run the tests on a single version with your
favorite test runner. The tests live in the ``jsonschema.tests`` package.
Benchmarks
----------
``jsonschema``'s benchmarks make use of `pyperf
<https://pyperf.readthedocs.io>`_.
Running them can be done via ``tox -e perf``, or by invoking the ``pyperf``
commands externally (after ensuring that both it and ``jsonschema`` itself are
installed)::
$ python -m pyperf jsonschema/benchmarks/test_suite.py --hist --output results.json
To compare to a previous run, use::
$ python -m pyperf compare_to --table reference.json results.json
See the ``pyperf`` documentation for more details.
Community
---------
There's a `mailing list <https://groups.google.com/forum/#!forum/jsonschema>`_
for this implementation on Google Groups.
Please join, and feel free to send questions there.
Contributing
------------
I'm Julian Berman.
``jsonschema`` is on `GitHub <https://github.com/Julian/jsonschema>`_.
Get in touch, via GitHub or otherwise, if you've got something to contribute,
it'd be most welcome!
You can also generally find me on Freenode (nick: ``tos9``) in various
channels, including ``#python``.
If you feel overwhelmingly grateful, you can also woo me with beer money
via Google Pay with the email in my GitHub profile.
And for companies who appreciate ``jsonschema`` and its continued support
and growth, ``jsonschema`` is also now supportable via `TideLift
<https://tidelift.com/subscription/pkg/pypi-jsonschema?utm_source=pypi-j
sonschema&utm_medium=referral&utm_campaign=readme>`_.
|
