[](https://pypi.python.org/pypi/flask-expects-json)
[](https://pypi.python.org/pypi/flask-expects-json)
[](https://pypi.python.org/pypi/flask-expects-json)
[](https://travis-ci.org/Fischerfredl/flask-expects-json)
[](https://codecov.io/gh/Fischerfredl/flask-expects-json)
# flask-expects-json
Decorator for REST endpoints in flask. Validate JSON request data.
When building json REST services I find myself already specifying json-schema for POST data while defining swagger spec. This package brings json validation to flask. It omits the need to validate the data yourself while profiting from an already established standard (http://json-schema.org/). Defining the schema right before the route helps the self-documentation of an endpoint (see usage).
This package uses jsonschema to for validation: https://pypi.python.org/pypi/jsonschema
## Installation
Use pip to install the package from PyPI:
```bash
pip install flask-expects-json
```
If you are intending to install async version:
```bash
pip install flask-expects-json[async]
```
Note: the above command is not necessary in order to install a version
of flask-expect-json that supports async, however, the above command
will ensure `flask[async]` is installed as a dependency.
## Usage
This package provides a flask route decorator to validate json payload.
```python
from flask import Flask, jsonify, g, url_for
from flask_expects_json import expects_json
# example imports
from models import User
from orm import NotUniqueError
app = Flask(__name__)
schema = {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'email': {'type': 'string'},
'password': {'type': 'string'}
},
'required': ['email', 'password']
}
@app.route('/register', methods=['POST'])
@expects_json(schema)
def register():
# if payload is invalid, request will be aborted with error code 400
# if payload is valid it is stored in g.data
# do something with your data
user = User().from_dict(g.data)
try:
user.save()
except NotUniqueError as e:
# exception path: duplicate database entry
return jsonify(dict(message=e.message)), 409
# happy path: json response
resp = jsonify(dict(auth_token=user.encode_auth_token(), user=user.to_dict()))
resp.headers['Location'] = url_for('users.get_user', user_id=user.id)
return resp, 201
```
The expected json payload is recognizable through "schema". If schema is not met the requests aborts (400) with a hinting error message.
## Mimetype checking
As of 1.2.0 this decorator uses `flask.request.get_json(force=False)` to get the data. This means the mimetype of the request has to be 'application/json'. Can be disabled by setting `force=False`. Be aware that this creates a major security vulnerability to CSRF since CORS is not enforced for certain mimetypes. Thanks to Argishti Rostamian for noticing.
```python
@app.route('/strict')
@expects_json()
def strict():
return 'This view will return 400 if mimetype is not \'application/json\'
@app.route('/insecure')
@expects_json({}, force=False)
def insecure():
return 'This view will validate the data no matter the mimetype.'
```
## Format checking
As of 1.6.0 you can set `check_formats=True` or `check_formats=['list of format']` to enable validating formats such as `email` `date-time`. This is set to `False` by default.
## Default values
Normally validators wont touch the data. By default this package will not fill in missing default values provided in the schema. If you want to you can set `fill_defaults=True` explicitly. The validation will be performed after this action, so default values can lead to invalid data.
## Skip validation methods
If you want to skip the validation for certain HTTP methods, specify them with `ignore_for=[]`. Typical methods that do not expect a body are GET, HEAD and DELETE. Thanks to @mtheos for implementing this.
```python
@app.route('/', methods=['GET', 'POST'])
@expects_json(schema, ignore_for=['GET'])
def register():
return
```
## Error handling
On validation failure the library calls `flask.abort` and passes an 400 error code and the validation error.
By default this creates an HTML error page and displays the error message.
To customize the behavior use the error handling provided by flask ([docs](https://flask.palletsprojects.com/en/1.1.x/errorhandling/#error-handlers)).
This can be useful to e.g hide the validation message from users or provide a JSON response.
The original [ValidationError](https://python-jsonschema.readthedocs.io/en/latest/errors/#jsonschema.exceptions.ValidationError) is passed to `flask.abort`, which itself passes arguments to `werkzeug.exceptions.HTTPException` so it can be retrieved on `error.description` like this:
```python
from flask import make_response, jsonify
from jsonschema import ValidationError
@app.errorhandler(400)
def bad_request(error):
if isinstance(error.description, ValidationError):
original_error = error.description
return make_response(jsonify({'error': original_error.message}), 400)
# handle other "Bad Request"-errors
return error
```
## Testing
The following are the steps to create a virtual environment into a folder named "venv" and install the requirements.
```bash
# Create virtualenv
python3 -m venv venv
# activate virtualenv
source venv/bin/activate
# update packages
pip install --upgrade pip setuptools wheel
# install requirements
python setup.py install
```
Tests can be run with `python setup.py test` when the virtualenv is active.
# Changelog
## Unreleased
## 1.7.0 - 2021-11-08
- Feature: support flask async (thanks @jiashuChen)
## 1.6.0 - 2021-08-09
- Feature: added optional format validation (thanks @CrafterSvK)
## 1.5.0 - 2020-08-24
- Feature: ignore validation for certain HTTP methods. (thanks @mtheos)
## 1.4.0 - 2019-09-02
- Updated dependencies to new major versions.
- Removed Python 3.4 support (as jsonschema did)
- Fixed: Typo in readme
- Changed: Pass whole error object to the 400 abort on schema validation error
## [1.3.1]
- Changed error message when get_json() fails.
- Bugfix in DefaultValidatingDraft4Validator when trying to set a default value on strings.
## [1.3.0] - 2018-02-16
- Changed: Defaults wont be filled in request data by default. Set fill_defaults=True explicitly.
## [1.2.0] - 2018-02-15
- Security: set force=False as default argument for mimetype checking. Before: force=True for convenience
## [1.1.0] - 2018-02-03
- Added missing default values will be automatically filled into the request data
- Added parameter fill_defaults
## [1.0.6] - 2018-01-29
- Added tests for Python 3.4, 3.5, 3.6
- Added code coverage
- Changed code-style/readme.
## 1.0.0 - 2018-01-21
- Added initial version of expects_json() decorator
- Added simple validation of request data
- Added store data in g.data
[Unreleased]: https://github.com/fischerfredl/flask-expects-json/compare/1.3.1...HEAD
[1.3.1]: https://github.com/fischerfredl/flask-expects-json/compare/1.2.0...1.3.1
[1.3.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.2.0...1.3.0
[1.2.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.1.0...1.2.0
[1.1.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.0.6...1.1.0
[1.0.6]: https://github.com/fischerfredl/flask-expects-json/compare/1.0.0...1.0.6
Raw data
{
"_id": null,
"home_page": "https://github.com/fischerfredl/flask-expects-json",
"name": "flask-expects-json",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "flask,json,validation,schema,jsonschema",
"author": "Alfred Melch",
"author_email": "dev@melch.pro",
"download_url": "https://files.pythonhosted.org/packages/12/a5/b27cf21d62c2b5a0a32e2f92bde9658e74c34fcc2e004bb0d591f1bf7627/flask-expects-json-1.7.0.tar.gz",
"platform": "",
"description": "[](https://pypi.python.org/pypi/flask-expects-json)\n[](https://pypi.python.org/pypi/flask-expects-json)\n[](https://pypi.python.org/pypi/flask-expects-json)\n[](https://travis-ci.org/Fischerfredl/flask-expects-json)\n[](https://codecov.io/gh/Fischerfredl/flask-expects-json)\n\n# flask-expects-json\n\nDecorator for REST endpoints in flask. Validate JSON request data.\n\nWhen building json REST services I find myself already specifying json-schema for POST data while defining swagger spec. This package brings json validation to flask. It omits the need to validate the data yourself while profiting from an already established standard (http://json-schema.org/). Defining the schema right before the route helps the self-documentation of an endpoint (see usage).\n\n\nThis package uses jsonschema to for validation: https://pypi.python.org/pypi/jsonschema\n\n## Installation\n\nUse pip to install the package from PyPI:\n\n```bash\npip install flask-expects-json\n```\n\nIf you are intending to install async version:\n\n```bash\npip install flask-expects-json[async]\n```\nNote: the above command is not necessary in order to install a version\nof flask-expect-json that supports async, however, the above command\nwill ensure `flask[async]` is installed as a dependency.\n\n## Usage\n\nThis package provides a flask route decorator to validate json payload.\n\n```python\nfrom flask import Flask, jsonify, g, url_for\nfrom flask_expects_json import expects_json\n# example imports\nfrom models import User\nfrom orm import NotUniqueError\n\napp = Flask(__name__)\n\nschema = {\n 'type': 'object',\n 'properties': {\n 'name': {'type': 'string'},\n 'email': {'type': 'string'},\n 'password': {'type': 'string'}\n },\n 'required': ['email', 'password']\n}\n\n\n@app.route('/register', methods=['POST'])\n@expects_json(schema)\ndef register():\n # if payload is invalid, request will be aborted with error code 400\n # if payload is valid it is stored in g.data\n\n # do something with your data\n user = User().from_dict(g.data)\n try:\n user.save()\n except NotUniqueError as e:\n # exception path: duplicate database entry\n return jsonify(dict(message=e.message)), 409\n\n # happy path: json response\n resp = jsonify(dict(auth_token=user.encode_auth_token(), user=user.to_dict()))\n resp.headers['Location'] = url_for('users.get_user', user_id=user.id)\n return resp, 201\n```\n\nThe expected json payload is recognizable through \"schema\". If schema is not met the requests aborts (400) with a hinting error message.\n\n\n## Mimetype checking\n\nAs of 1.2.0 this decorator uses `flask.request.get_json(force=False)` to get the data. This means the mimetype of the request has to be 'application/json'. Can be disabled by setting `force=False`. Be aware that this creates a major security vulnerability to CSRF since CORS is not enforced for certain mimetypes. Thanks to Argishti Rostamian for noticing.\n\n```python\n@app.route('/strict')\n@expects_json()\ndef strict():\n return 'This view will return 400 if mimetype is not \\'application/json\\' \n \n@app.route('/insecure')\n@expects_json({}, force=False)\ndef insecure():\n return 'This view will validate the data no matter the mimetype.'\n```\n\n## Format checking\n\nAs of 1.6.0 you can set `check_formats=True` or `check_formats=['list of format']` to enable validating formats such as `email` `date-time`. This is set to `False` by default.\n\n## Default values\n\nNormally validators wont touch the data. By default this package will not fill in missing default values provided in the schema. If you want to you can set `fill_defaults=True` explicitly. The validation will be performed after this action, so default values can lead to invalid data.\n\n## Skip validation methods\n\nIf you want to skip the validation for certain HTTP methods, specify them with `ignore_for=[]`. Typical methods that do not expect a body are GET, HEAD and DELETE. Thanks to @mtheos for implementing this.\n\n```python\n@app.route('/', methods=['GET', 'POST'])\n@expects_json(schema, ignore_for=['GET'])\ndef register():\n return \n```\n\n## Error handling\n\nOn validation failure the library calls `flask.abort` and passes an 400 error code and the validation error.\nBy default this creates an HTML error page and displays the error message.\nTo customize the behavior use the error handling provided by flask ([docs](https://flask.palletsprojects.com/en/1.1.x/errorhandling/#error-handlers)).\nThis can be useful to e.g hide the validation message from users or provide a JSON response.\n\nThe original [ValidationError](https://python-jsonschema.readthedocs.io/en/latest/errors/#jsonschema.exceptions.ValidationError) is passed to `flask.abort`, which itself passes arguments to `werkzeug.exceptions.HTTPException` so it can be retrieved on `error.description` like this:\n\n```python\nfrom flask import make_response, jsonify\nfrom jsonschema import ValidationError\n\n@app.errorhandler(400)\ndef bad_request(error):\n if isinstance(error.description, ValidationError):\n original_error = error.description\n return make_response(jsonify({'error': original_error.message}), 400)\n # handle other \"Bad Request\"-errors\n return error\n```\n\n## Testing\n\nThe following are the steps to create a virtual environment into a folder named \"venv\" and install the requirements.\n\n```bash\n# Create virtualenv\npython3 -m venv venv\n# activate virtualenv\nsource venv/bin/activate\n# update packages\npip install --upgrade pip setuptools wheel\n# install requirements\npython setup.py install\n```\n\nTests can be run with `python setup.py test` when the virtualenv is active.\n\n# Changelog\n\n## Unreleased\n\n## 1.7.0 - 2021-11-08\n- Feature: support flask async (thanks @jiashuChen)\n\n## 1.6.0 - 2021-08-09\n- Feature: added optional format validation (thanks @CrafterSvK)\n\n## 1.5.0 - 2020-08-24\n- Feature: ignore validation for certain HTTP methods. (thanks @mtheos)\n\n## 1.4.0 - 2019-09-02\n- Updated dependencies to new major versions.\n- Removed Python 3.4 support (as jsonschema did)\n- Fixed: Typo in readme\n- Changed: Pass whole error object to the 400 abort on schema validation error\n\n## [1.3.1]\n- Changed error message when get_json() fails. \n- Bugfix in DefaultValidatingDraft4Validator when trying to set a default value on strings.\n\n## [1.3.0] - 2018-02-16\n- Changed: Defaults wont be filled in request data by default. Set fill_defaults=True explicitly.\n\n## [1.2.0] - 2018-02-15\n- Security: set force=False as default argument for mimetype checking. Before: force=True for convenience\n\n## [1.1.0] - 2018-02-03\n- Added missing default values will be automatically filled into the request data\n- Added parameter fill_defaults\n\n## [1.0.6] - 2018-01-29\n- Added tests for Python 3.4, 3.5, 3.6\n- Added code coverage\n- Changed code-style/readme. \n\n## 1.0.0 - 2018-01-21\n- Added initial version of expects_json() decorator\n- Added simple validation of request data\n- Added store data in g.data\n\n[Unreleased]: https://github.com/fischerfredl/flask-expects-json/compare/1.3.1...HEAD\n[1.3.1]: https://github.com/fischerfredl/flask-expects-json/compare/1.2.0...1.3.1\n[1.3.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.2.0...1.3.0\n[1.2.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.1.0...1.2.0\n[1.1.0]: https://github.com/fischerfredl/flask-expects-json/compare/1.0.6...1.1.0\n[1.0.6]: https://github.com/fischerfredl/flask-expects-json/compare/1.0.0...1.0.6\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Decorator for REST endpoints in flask. Validate JSON request data.",
"version": "1.7.0",
"project_urls": {
"Homepage": "https://github.com/fischerfredl/flask-expects-json"
},
"split_keywords": [
"flask",
"json",
"validation",
"schema",
"jsonschema"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12a5b27cf21d62c2b5a0a32e2f92bde9658e74c34fcc2e004bb0d591f1bf7627",
"md5": "3a77c4059f21e6e37e652c9dbbdc2e7c",
"sha256": "4ef186a86f10572a21af82e549546deda024326628b4a96cd14d3a0f71754d62"
},
"downloads": -1,
"filename": "flask-expects-json-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3a77c4059f21e6e37e652c9dbbdc2e7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6095,
"upload_time": "2021-11-08T10:42:59",
"upload_time_iso_8601": "2021-11-08T10:42:59.189227Z",
"url": "https://files.pythonhosted.org/packages/12/a5/b27cf21d62c2b5a0a32e2f92bde9658e74c34fcc2e004bb0d591f1bf7627/flask-expects-json-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-11-08 10:42:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fischerfredl",
"github_project": "flask-expects-json",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "flask-expects-json"
}
JSON
