Skip to main content

Automatic JSON schema validation for Bottle

Project description


Bottle plugin for automatically validating JSON schemas for all relevant requests.


pip install bottle_jsonschema

Usage example

import bottle
from bottle.ext.jsonschema import JSONSchemaPlugin, SchemaValidationError


def handle_error_400(error):
    # This forwards the error directly to the user, which will display a nicely
    # formatted JSON object containing the validation errors.
    if isinstance(error, SchemaValidationError):
        return response

    # Handle other error situations...

    return json.dumps({"error": "invalid request"})

The error object contains a list of strings describing the validation errors. You can easily customize how the errors are displayed, here's how you can display them as a HTML list:

def handle_error_400(error):
    if isinstance(error, SchemaValidationError):
        response.content_type = "text/html"

        error_list = "\n".join(
            "<li>{}</li>".format(x) for x in error.validation_errors

        return """
            <h1>JSON schema validation failed</h1>

    return response

Output samples

Here are some samples of the output of the plugin, given the following error handler:

def handle_error_400(error):
    if isinstance(error, SchemaValidationError):
        return response

    response.content_type = "application/json"
    return json.dumps({"error": error.body})
$ curl -s -X PUT "" | jq .
  "error": "content type application/json required"
$ curl -s -X PUT -H "Content-Type: application/json" "" | jq .
  "error": "json payload required"
$ curl -s -X PUT -H "Content-Type: application/json" -d '{}' "" | jq .
  "error": "payload failed json schema validation",
  "validation_errors": [
    "failed constraint: required: ['email', 'password']"
$ curl -s -X PUT -H "Content-Type: application/json" -d '{"email": "x", "password": "123"}' "" | jq .
  "error": "payload failed json schema validation",
  "validation_errors": [
    "failed constraint: properties.password.minLength: 8",
    "failed constraint: 6"
$ curl -s -X PUT -H "Content-Type: application/json" -d '{"email": "", "password": "12345678"}' "" | jq .
  "code": "success"

More information

Here's basically everything the plugin does for every request:

  1. Check the HTTP method of the request. If it's one of POST, PATCH or PUT, then continue. Otherwise stop.
  2. Try to find a schema for the request. If a schema was found, continue, otherwise stop. The default logic for finding a schema is explained below, and can be overridden.
  3. Check that the request content type is "application/json". If it's not, raise a 400 Bad Request error.
  4. Check that the request contains a JSON parseable payload. If not, raise a 400 Bad Request error.
  5. Validate the payload using jsonschema. If there were no errors, stop. Otherwise raise a 400 Bad Request error.

How do I override which HTTP methods trigger schema validation?

bottle.install(JSONSchemaPlugin(methods=("GET", "POST")))

How does the plugin find schemas?

By default, the plugin finds schemas by checking your Bottle application's resource manager for "schemas/<name>.json". The default strategy for converting a route to a schema name is:

PUT /login                      -> schemas/login[.PUT].json
POST /admin/users               -> schemas/admin.users[.POST].json
PUT /admin/users/<id:int>       -> schemas/[.POST].json
PATCH /users/<name:re:\w(@\w)?> -> schemas/[.PATCH].json

Basically, it replaces slashes with dots, replaces wildcards with the wildcard name and strips leading and trailing slashes. The HTTP method is optional, as signified by the square brackets.

You can override the naming strategy like this:

def get_schema_name():
    # Generate one or more schema names for the current request.

    return ["list", "of", "names", "that", "will", "be", "tried", "in", "order"]


Or you can override the whole schema lookup altogether:

def find_schema():
    # Find the correct schema for the current request and return it as a dict.

    # Returning None will skip schema validation.
    return None


How do I set up the resource manager to work with this plugin?

Assuming you have a project folder layout like this:

├── assets
│   └── schemas
│       └── login.json

Then you just need this line:


Or, if you're using the default app:


Now JSONSchemaPlugin will validate requests against your schemas without any further configuration. You can make it work with any project layout by overriding the schema naming strategy as explained above, or you can skip the resource manager altogether by overriding the schema lookup function.

Project details

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
bottle_jsonschema-0.0.1-py3-none-any.whl (4.5 kB) Copy SHA256 hash SHA256 Wheel py3
bottle-jsonschema-0.0.1.tar.gz (4.5 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page