Metadata-Version: 2.1
Name: more.jsonschema
Version: 0.2
Summary: JSON Schema support for Morepath
Home-page: https://github.com/morepath/more.jsonschema
Author: Henri Hulski
Author-email: henri.hulski@gazeta.pl
License: BSD
Keywords: morepath validation
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: morepath (>=0.19)
Requires-Dist: jsonschema (>=3.2.0)
Provides-Extra: coverage
Requires-Dist: pytest-cov ; extra == 'coverage'
Provides-Extra: pep8
Requires-Dist: flake8 ; extra == 'pep8'
Requires-Dist: black ; extra == 'pep8'
Provides-Extra: test
Requires-Dist: pytest (>=2.9.1) ; extra == 'test'
Requires-Dist: pytest-remove-stale-bytecode ; extra == 'test'
Requires-Dist: webtest ; extra == 'test'

more.jsonschema: JSON Schema support for Morepath
=================================================

This package provides Morepath integration for `JSON Schema`_,
implemented with jsonschema_:

.. _JSON Schema: http://json-schema.org
.. _jsonschema: https://python-jsonschema.readthedocs.io/en/latest

JSON Schema can automate user input validation in a HTTP API.


Schema
------

The JSON schema need to be load into a Python dict
(you can use ``json.load()``):

.. code-block:: python

  user_schema = {
      'type': 'object',
      'properties': {
          'name': {
              'type': 'string',
              'minLength': 3
          },
          'age': {
              'type': 'integer',
              'minimum': 10
          }
      },
      'required': ['name', 'age']
  }

If you want to define JSON schemas in Python, you can use jsl_ for instance.

.. _jsl: http://jsl.readthedocs.io/en/latest


Validate
--------

The ``more.jsonschema`` integration helps
with validation of the request body as it is POSTed to a view.
First we must create a loader for our schema:

.. code-block:: python

  from more.jsonschema import loader

  user_schema_load = loader(user_schema)

We can use this loader to handle a POST request for instance:

.. code-block:: python

  @App.json(model=User, request_method='POST', load=user_schema_load)
  def user_post(self, request, json):
      # json is now a validated and normalized dict of whatever got
      # POST onto this view that you can use to update
      # self


Customize the Validator
-----------------------

By default ``more.jsonschema`` uses the ``Draft7Validator``.
But you can also use ``Draft3Validator``, ``Draft4Validator`` or ``Draft6Validator``.
You can even create your own Validator or extend an existent one.
Just pass the Validator to the ``loader``:

.. code-block:: python

  from jsonschema import Draft4Validator
  from more.jsonschema import loader

    user_schema_load = loader(user_schema, validator=Draft4Validator)

More information about creating or extending Validator classes
you can find in the `jsonschema documentation`_.

.. _jsonschema documentation:
  https://python-jsonschema.readthedocs.io/en/latest/creating


Error handling
--------------

If validation fails due to a validation error (a required field is
missing, or a field is of the wrong datatype, for instance), you want
to show some kind of error message. The ``load`` function created by
``more.jsonschema`` raise the ``more.jsonschema.ValidationError`` exception
in case of errors.

This exception object has an ``errors`` attribute with the validation errors.
You must define an exception view for it, otherwise validation errors are
returned as "500 internal server error" to API users.

This package provides a default exception view implementation. If you subclass
your application from ``more.jsonschema.JsonSchemaApp`` then you get a default
error view for ``ValidationError`` that has a 422 status code with an error
message:

.. code-block:: python

  from more.jsonschema import JsonSchemaApp

  class App(JsonSchemaApp):
      pass

Now your app has reasonable error handling built-in.


CHANGES
*******

0.2 (2020-04-26)
================

- **Removed**: Removed support for Python 2 and Python 3.4 and 3.5.

  You have to upgrade to Python 3 if you want to use this version.

- Added support for Python 3.6, 3.7 and 3.8 and PyPy 3.6.

- Make Python 3.7 the default testing environment.

- Upgrade jsonschema to version 3.2.0.

- Make JSON Schema Draft 7 the default validator.

- Add integration for the Black code formatter.


0.1 (2017-03-17)
================

* initial public release.


