Fast JSON Schema

https://horejsek.github.io/python-fastjsonschema
Admin
Fast JSON Schema is a high-performance Python library for validating JSON documents against JSON...
Tokens:6,284
Snippets:36
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install fastjsonschema with pip

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Install the fastjsonschema library using pip. Requires Python 3.3 or higher.

```bash
pip install fastjsonschema

```

--------------------------------

### Run performance benchmarks with make performance

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Run the included performance benchmark script. Output shows timing comparisons for valid and invalid inputs across various validation methods.

```bash
$ 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

```

--------------------------------

### Compile and validate a JSON Schema with fastjsonschema

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Shows how to compile a JSON Schema with fastjsonschema and validate a dictionary. The schema requires x and y as numbers and disallows additional properties; a validation failure raises fastjsonschema.JsonSchemaException, which is caught and printed.

```python
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}")
```

--------------------------------

### Select JSON Schema draft with fastjsonschema.compile

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Specifies the JSON Schema draft version via the '$schema' keyword. Supported drafts are draft-04, draft-06, and draft-07; if not specified, the latest (draft-07) is used.

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

```

--------------------------------

### Generate validation code from the command line with python3 -m fastjsonschema

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Command-line usage of fastjsonschema to generate validation code. The first command pipes the schema definition via echo; the second passes it as an argument. Both write the generated code to your_file.py.

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

```

--------------------------------

### compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

Source: https://horejsek.github.io/python-fastjsonschema/modules/fastjsonschema.html

Generates a validation function for a JSON schema definition. This is the preferred method for repeated validations as it compiles the schema once for better performance.

```APIDOC
## compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

### Description
Generates a validation function for a JSON schema definition. This is the preferred method for repeated validations as it compiles the schema once for better performance.

### Method
Function call

### Endpoint
`fastjsonschema.compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)`

### Parameters
- **definition** (dict) - Required - The JSON schema definition to compile.
- **handlers** (dict) - Optional - Mapping from URI to function for retrieving remote schemas.
- **formats** (dict) - Optional - Mapping of custom format names to regex or callback functions.
- **use_default** (bool) - Optional - Whether to apply default values from the schema. Default is True.
- **use_formats** (bool) - Optional - Whether to use format assertions. Default is True.
- **detailed_exceptions** (bool) - Optional - Whether to include detailed exception information. Default is True.

### Request Example
```python
import fastjsonschema
validate = fastjsonschema.compile({'type': 'string'})
validate('hello')
```

### Response
#### Success Response
- Returns a validation function that takes data and returns the validated data (with defaults applied if applicable).

#### Response Example
```python
validate = fastjsonschema.compile({'type': 'string'})
result = validate('hello')  # returns 'hello'
```

### Error Handling
- Raises `JsonSchemaDefinitionException` if the definition is invalid.
- Raises `JsonSchemaValueException` from the generated function if validation fails.
```

--------------------------------

### fastjsonschema.compile_to_code(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Generates validation code (as a string) for the given JSON schema definition. This code can be saved to a file and used as a standalone validator.

```APIDOC
## fastjsonschema.compile_to_code(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

### Description
Generates validation code for validating JSON schema passed in `definition`. The code can be written to a file and used as a standalone validator.

### Method
compile_to_code

### Parameters
- **definition** (dict) - Required - The JSON schema definition to compile.
- **handlers** (dict) - Optional - Mapping from URI to function used to retrieve remote schemas.
- **formats** (dict) - Optional - Mapping of custom format names to regex or callback functions.
- **use_default** (bool) - Optional - Whether to support the `default` keyword. Defaults to True.
- **use_formats** (bool) - Optional - Whether to use formats as assertions. Defaults to True.
- **detailed_exceptions** (bool) - Optional - Whether to include detailed exception properties. Defaults to True.

### Returns
A string containing the generated Python validation code.

### Exceptions
- `JsonSchemaDefinitionException` - Raised when the definition is invalid.

### Example
```python
import fastjsonschema

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

--------------------------------

### fastjsonschema internal _factory and _get_code_generator_class

Source: https://horejsek.github.io/python-fastjsonschema/modules/fastjsonschema.html

Internal factory and generator selection functions from the fastjsonschema module. _factory builds a RefResolver and a code generator instance from a schema definition, returning both. _get_code_generator_class picks the generator class based on the $schema version, defaulting to Draft07 for missing or unknown versions.

```python
def _factory(definition, handlers, formats={}, use_default=True, use_formats=True, detailed_exceptions=True):
    resolver = RefResolver.from_schema(definition, handlers=handlers, store={})
    code_generator = _get_code_generator_class(definition)(
        definition,
        resolver=resolver,
        formats=formats,
        use_default=use_default,
        use_formats=use_formats,
        detailed_exceptions=detailed_exceptions,
    )
    return resolver, code_generator
```

```python
def _get_code_generator_class(schema):
    # Schema in from draft-06 can be just the boolean value.
    if isinstance(schema, dict):
        schema_version = schema.get('$schema', '')
        if 'draft-04' in schema_version:
            return CodeGeneratorDraft04
        if 'draft-06' in schema_version:
            return CodeGeneratorDraft06
    return CodeGeneratorDraft07
```

--------------------------------

### validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

Source: https://horejsek.github.io/python-fastjsonschema/modules/fastjsonschema.html

Validates data against a JSON schema definition in a single call. This is convenient for one-off validations where performance is not critical.

```APIDOC
## validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

### Description
Validates data against a JSON schema definition in a single call. This is convenient for one-off validations where performance is not critical.

### Method
Function call

### Endpoint
`fastjsonschema.validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)`

### Parameters
- **definition** (dict) - Required - The JSON schema definition to validate against.
- **data** (any) - Required - The data to validate.
- **handlers** (dict) - Optional - Mapping from URI to function for retrieving remote schemas.
- **formats** (dict) - Optional - Mapping of custom format names to regex or callback functions.
- **use_default** (bool) - Optional - Whether to apply default values from the schema. Default is True.
- **use_formats** (bool) - Optional - Whether to use format assertions. Default is True.
- **detailed_exceptions** (bool) - Optional - Whether to include detailed exception information. Default is True.

### Request Example
```python
import fastjsonschema
fastjsonschema.validate({'type': 'string'}, 'hello')
```

### Response
#### Success Response
- Returns the validated data (with defaults applied if applicable).

#### Response Example
```python
'hello'
```

### Error Handling
- Raises `JsonSchemaDefinitionException` if the definition is invalid.
- Raises `JsonSchemaValueException` if validation fails.
```

--------------------------------

### fastjsonschema.compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Generates a validation function for the given JSON schema definition. Supports draft-04, draft-06, and draft-07, and can handle custom formats and remote schemas.

```APIDOC
## fastjsonschema.compile(definition, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

### Description
Generates a validation function for validating JSON schema passed in `definition`. Supports draft-04, draft-06, and draft-07. Can handle custom formats and remote schemas via handlers.

### Method
compile

### Parameters
- **definition** (dict) - Required - The JSON schema definition to compile.
- **handlers** (dict) - Optional - Mapping from URI to function used to retrieve remote schemas.
- **formats** (dict) - Optional - Mapping of custom format names to regex or callback functions.
- **use_default** (bool) - Optional - Whether to support the `default` keyword. Defaults to True.
- **use_formats** (bool) - Optional - Whether to use formats as assertions. Defaults to True.
- **detailed_exceptions** (bool) - Optional - Whether to include detailed exception properties. Defaults to True.

### Returns
A validation function that takes data and returns the validated data (with defaults applied if enabled).

### Exceptions
- `JsonSchemaDefinitionException` - Raised when the definition is invalid.
- `JsonSchemaValueException` - Raised when validation fails.

### Example
```python
import fastjsonschema

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

--------------------------------

### Compile a JSON schema with fastjsonschema.compile

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Compiles a JSON schema definition into a validation function. The returned function validates data against the schema; here it checks that 'hello' is a string.

```python
import fastjsonschema

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

```

--------------------------------

### JsonSchemaException

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Base exception of the fastjsonschema library. All other exceptions inherit from this.

```APIDOC
## JsonSchemaException

### Description
Base exception of `fastjsonschema` library. All other exceptions in this library inherit from this class.

### Usage
Can be used to catch any fastjsonschema-related exception.

### Example
```python
import fastjsonschema

try:
    fastjsonschema.validate({'type': 'number'}, 'not a number')
except fastjsonschema.JsonSchemaException as e:
    print(e)
```
```

--------------------------------

### Generate validation code with fastjsonschema.compile_to_code

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Generates Python source code for a validation function and writes it to a file. The generated code can be imported and used later. Raises JsonSchemaDefinitionException if the definition is invalid.

```python
import fastjsonschema

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

```

--------------------------------

### fastjsonschema.validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Validates data against a JSON schema definition without explicitly compiling first. This is a convenience function for one-off validations.

```APIDOC
## fastjsonschema.validate(definition, data, handlers={}, formats={}, use_default=True, use_formats=True, detailed_exceptions=True)

### Description
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.

### Method
validate

### Parameters
- **definition** (dict) - Required - The JSON schema definition to validate against.
- **data** (any) - Required - The data to validate.
- **handlers** (dict) - Optional - Mapping from URI to function used to retrieve remote schemas.
- **formats** (dict) - Optional - Mapping of custom format names to regex or callback functions.
- **use_default** (bool) - Optional - Whether to support the `default` keyword. Defaults to True.
- **use_formats** (bool) - Optional - Whether to use formats as assertions. Defaults to True.
- **detailed_exceptions** (bool) - Optional - Whether to include detailed exception properties. Defaults to True.

### Returns
The validated data (with defaults applied if enabled).

### Exceptions
- `JsonSchemaDefinitionException` - Raised when the definition is invalid.
- `JsonSchemaValueException` - Raised when validation fails.

### Example
```python
import fastjsonschema

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

--------------------------------

### fastjsonschema.exceptions module source code

Source: https://horejsek.github.io/python-fastjsonschema/modules/fastjsonschema/exceptions.html

The full source code of the exceptions module, defining the base exception class and its subclasses. It includes the SPLIT_RE regex for splitting paths and the JsonSchemaValueException with properties like message, value, name, path, definition, rule, and rule_definition.

```python
import re


SPLIT_RE = re.compile(r'[\.\[\]]+')



[docs]class JsonSchemaException(ValueError):
    """
    Base exception of ``fastjsonschema`` library.
    """




[docs]class JsonSchemaValueException(JsonSchemaException):
    """
    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``).

    .. versionchanged:: 2.14.0
        Added all extra properties.
    """

    def __init__(self, message, value=None, name=None, definition=None, rule=None):
        super().__init__(message)
        self.message = message
        self.value = value
        self.name = name
        self.definition = definition
        self.rule = rule

    @property
    def path(self):
        return [item for item in SPLIT_RE.split(self.name) if item != '']

    @property
    def rule_definition(self):
        if not self.rule or not self.definition:
            return None
        return self.definition.get(self.rule)




[docs]class JsonSchemaDefinitionException(JsonSchemaException):
    """
    Exception raised by generator of validation function.
    """

```

--------------------------------

### Use default values in JSON schema with fastjsonschema.compile

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Shows the use of the 'default' keyword, which is enabled by default. When validating an empty object, the missing property 'a' is filled with its default value 42. Pass use_default=False to disable this behavior.

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

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

```

--------------------------------

### Validate data directly with fastjsonschema.validate

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Validates data directly without compiling first. This is convenient for one-off validations but is slower than using compile. The comment shows the equivalent compiled call.

```python
import fastjsonschema

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

```

--------------------------------

### Define custom formats with fastjsonschema.compile

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Passes custom format validators. The value can be a regular expression (compiled internally) or a callback returning a boolean. Formats are automatically used as assertions; pass use_formats=False to disable them (added in 2.19.0).

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

```

--------------------------------

### JsonSchemaValueException(message, value=None, name=None, definition=None, rule=None)

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Exception raised by validation functions when data does not conform to the schema. Provides detailed information about the validation failure.

```APIDOC
## JsonSchemaValueException(message, value=None, name=None, definition=None, rule=None)

### Description
Exception raised by validation function when data does not follow the definition. Provides detailed information about the failure.

### Parameters
- **message** (str) - Required - Human-readable information about what is wrong.
- **value** (any) - Optional - The invalid value.
- **name** (str) - Optional - The path in the data structure (e.g., `data.property[index]`).
- **definition** (dict) - Optional - The whole definition that the value has to fulfil.
- **rule** (str) - Optional - The rule that the value is breaking (e.g., `maximum`).

### Properties
- `message` - Human-readable information about what is wrong.
- `value` - The invalid value.
- `name` - The path in the data structure.
- `path` - The path as an array (e.g., `['data', 'property', 'index']`).
- `definition` - The whole definition that the value has to fulfil.
- `rule` - The rule that the value is breaking.
- `rule_definition` - The value of the rule (e.g., `42`).

### Usage
Raised by validation functions when validation fails.

### Example
```python
import fastjsonschema

try:
    fastjsonschema.validate({'type': 'number', 'maximum': 42}, 60)
except fastjsonschema.JsonSchemaValueException as e:
    print(e.message)
    print(e.value)
    print(e.name)
    print(e.path)
    print(e.definition)
    print(e.rule)
    print(e.rule_definition)
```
```

--------------------------------

### JsonSchemaDefinitionException

Source: https://horejsek.github.io/python-fastjsonschema/index.html

Exception raised by the generator of validation function when the definition is invalid.

```APIDOC
## JsonSchemaDefinitionException

### Description
Exception raised by generator of validation function. This occurs when the JSON schema definition is invalid or cannot be compiled.

### Usage
Raised by `compile()`, `compile_to_code()`, and `validate()` when the definition is bad.

### Example
```python
import fastjsonschema

try:
    fastjsonschema.compile({'type': 'invalid'})
except fastjsonschema.JsonSchemaDefinitionException as e:
    print(e)
```
```
Tokens:
Raw