Fast JSON schema for Python¶

pip install fastjsonschema

$ make performance
fast_compiled                  valid      ==>  0.0993900
fast_compiled                  invalid    ==>  0.0041089
fast_compiled_without_exc      valid      ==>  0.0465258
fast_compiled_without_exc      invalid    ==>  0.0023688
fast_file                      valid      ==>  0.0989483
fast_file                      invalid    ==>  0.0041104
fast_not_compiled              valid      ==> 11.9572681
fast_not_compiled              invalid    ==>  2.9512092
jsonschema                     valid      ==>  5.2233240
jsonschema                     invalid    ==>  1.3227916
jsonschema_compiled            valid      ==>  0.4447982
jsonschema_compiled            invalid    ==>  0.0231333
jsonspec                       valid      ==>  4.1450569
jsonspec                       invalid    ==>  1.0485777
validictory                    valid      ==>  0.2730411
validictory                    invalid    ==>  0.0183669

import fastjsonschema

point_schema = {
    "type": "object",
    "properties": {
        "x": {
            "type": "number",
        },
        "y": {
            "type": "number",
        },
    },
    "required": ["x", "y"],
    "additionalProperties": False,
}

point_validator = fastjsonschema.compile(point_schema)
try:
    point_validator({"x": 1.0, "y": 2.0})
except fastjsonschema.JsonSchemaException as e:
    print(f"Data failed validation: {e}")

exception fastjsonschema.JsonSchemaDefinitionException[source]¶

Exception raised by generator of validation function.

exception fastjsonschema.JsonSchemaException[source]¶

Base exception of fastjsonschema library.

exception fastjsonschema.JsonSchemaValueException(message, value=None, name=None, definition=None, rule=None)[source]¶

Exception raised by validation function. Available properties:

• message containing human-readable information what is wrong (e.g. data.property[index] must be smaller than or equal to 42),

• invalid value (e.g. 60),

• name of a path in the data structure (e.g. data.property[index]),

• path as an array in the data structure (e.g. ['data', 'property', 'index']),

• the whole definition which the value has to fulfil (e.g. {'type': 'number', 'maximum': 42}),

• rule which the value is breaking (e.g. maximum)

• and rule_definition (e.g. 42).

Changed in version 2.14.0: Added all extra properties.

fastjsonschema.compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)[source]¶

Generates validation function for validating JSON schema passed in definition. Example:

import fastjsonschema

validate = fastjsonschema.compile({'type': 'string'})
validate('hello')

This implementation supports keyword default (can be turned off by passing use_default=False):

validate = fastjsonschema.compile({
    'type': 'object',
    'properties': {
        'a': {'type': 'number', 'default': 42},
    },
})

data = validate({})
assert data == {'a': 42}

Supported implementations are draft-04, draft-06 and draft-07. Which version should be used is determined by $draft in your definition. When not specified, the latest implementation is used (draft-07).

validate = fastjsonschema.compile({
    '$schema': 'http://json-schema.org/draft-04/schema',
    'type': 'number',
})

You can pass mapping from URI to function that should be used to retrieve remote schemes used in your definition in parameter handlers.

Also, you can pass mapping for custom formats. Key is the name of your formatter and value can be regular expression, which will be compiled or callback returning bool (or you can raise your own exception).

validate = fastjsonschema.compile(definition, formats={
    'foo': r'foo|bar',
    'bar': lambda value: value in ('foo', 'bar'),
})

Note that formats are automatically used as assertions. It can be turned off by passing use_formats=False. When disabled, custom formats are disabled as well. (Added in 2.19.0.)

If you don’t need detailed exceptions, you can turn the details off and gain additional performance by passing detailed_exceptions=False.

Exception JsonSchemaDefinitionException is raised when generating the code fails (bad definition).

Exception JsonSchemaValueException is raised from generated function when validation fails (data do not follow the definition).

fastjsonschema.compile_to_code(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)[source]¶

Generates validation code for validating JSON schema passed in definition. Example:

import fastjsonschema

code = fastjsonschema.compile_to_code({'type': 'string'})
with open('your_file.py', 'w') as f:
    f.write(code)

You can also use it as a script:

echo "{'type': 'string'}" | python3 -m fastjsonschema > your_file.py
python3 -m fastjsonschema "{'type': 'string'}" > your_file.py

Exception JsonSchemaDefinitionException is raised when generating the code fails (bad definition).

fastjsonschema.validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)[source]¶

Validation function for lazy programmers or for use cases when you need to call validation only once, so you do not have to compile it first. Use it only when you do not care about performance (even though it will be still faster than alternative implementations).

import fastjsonschema

fastjsonschema.validate({'type': 'string'}, 'hello')
# same as: compile({'type': 'string'})('hello')

Preferred is to use compile function.