jddf package

Submodules

jddf.schema module

class jddf.schema.Discriminator(**kwargs)

Bases: object

Represents a JSON Data Definition Format schema discriminator object.

This class is meant to be the discriminator property of a Schema.

static from_json(value: Any) → jddf.schema.Discriminator

Construct a discriminator from JSON data.

This method is typically not useful on its own; consider using Schema.from_json instead.

class jddf.schema.Form

Bases: enum.Enum

An enumeration of all the JDDF Schema forms.

Instances of this class are returned from Schema.form().

DISCRIMINATOR = 8

The discriminator form.

ELEMENTS = 5

The elements form.

EMPTY = 1

The empty form.

ENUM = 4

The enum form.

PROPERTIES = 6

The properties form.

REF = 2

The ref form.

TYPE = 3

The type form.

VALUES = 7

The values form.

class jddf.schema.Schema(**kwargs)

Bases: object

Represents a JSON Data Definition Format schema.

There are two ways to construct instances of this class: Schema.from_json parses a Schema from parsed JSON – that is, a dict which was returned from json.loads.

Instances of this class are not guaranteed to be “correct” JDDF schemas. To validate that a schema is correct, use the verify() method.

This constructor for this class understands the following kwargs, all of which are optional:

  • definitions is meant to be a dict with Schemas as values
  • ref is meant to be a string
  • enum is meant to be a list of strings
  • elements is meant to be a Schema
  • properties is meant to be a dict with Schemas as values
  • optional_properties is meant to be a dict with Schemas as values
  • additional_properties is meant to be a bool
  • values is meant to be a Schema
  • discriminator is meant to be a Discriminator

Construction this way does not do type checking or other sorts of input validation. To parse incoming JSON as a schema, you should use json.loads in combination with the from_json and verify methods of this class.

>>> Schema(type='string').type
'string'
TYPE_VALUES = ['boolean', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64', 'string', 'timestamp']
form() → jddf.schema.Form

Determine which of the eight JDDF Schema “forms” this schema takes on.

The return value of this method is meaningful only if the schema is a correct one, i.e. no errors were raised by verify().

static from_json(value: Any) → jddf.schema.Schema

Construct a Schema from JSON.

In combination with json.loads and verify, this method will thoroughly vet that a Schema is correct.

>>> import json
>>> data = '{"properties": {"age": {"type": "uint32"}, "name": {"type": "string"}}}'
>>> schema = Schema.from_json(json.loads(data)).verify()
>>> schema.properties["age"].type
'uint32'
>>> schema.properties["name"].type
'string'
verify(root=None) → jddf.schema.Schema

Check that a Schema represents a correct JDDF schema.

This method will raise TypeError if any of the constraints of JDDF are violated, and returns self if the schema is correct.

>>> Schema(definitions={}, ref="foo").verify()
Traceback (most recent call last):
    ...
TypeError: ref to nonexistent definition

jddf.validator module

exception jddf.validator.MaxDepthExceededError

Bases: Exception

Indicates that the configured maximum depth of a Validator was exceeded during validation.

Typically, this means that a schema was defined circularly, and so this error was raised instead of overflowing the stack.

class jddf.validator.ValidationError(instance_path: List[str], schema_path: List[str])

Bases: object

Represents a single JDDF validation error indicator. This class is not an exception; it is an ordinary class for storing data.

A list of instances of this class are returned by Validator.validate.

A validation error consists of two pieces of data. Both of these are lists of strings; one list of strings represents one JSON Pointer:

  • instance_path, a JSON Pointer pointing to the part of the instance which was rejected
  • schema_path, a JSON Pointer pointing to the part of the schema which rejected the instance

The precise values of instance_path and schema_path are formalized in the JDDF specification.

>>> err = ValidationError(['age'], ['properties', 'age', 'type'])
>>> err.instance_path
['age']
>>> err.schema_path
['properties', 'age', 'type']
class jddf.validator.Validator(**kwargs)

Bases: object

Validates JDDF schemas against JSON values.

To help defend against circularly-defined schemas, this class supports a “maximum depth” that, if exceeded, results in validate() raising a MaxDepthExceededError. By default, no maximum depth is imposed.

To optimize the case where only a limited number of errors are of interest (such as just knowing whether there’s at least one validation error), this class supports a “maximum errors” that guarantees that no more than a certain number of errors will be returned.

>>> validator = Validator(max_depth=128, max_errors=1)
>>> validator.max_depth
128
>>> validator.max_errors
1
validate(schema: jddf.schema.Schema, instance: Any) → List[jddf.validator.ValidationError]

Validate an input (“instance”) against a JDDF schema, returning a list of validation errors.

If max_depth is exceeded, this method raises MaxDepthExceededError. If max_errors is reached, this method immediately stops looking for further errors, and returns a list of length no greater than max_errors.

See documentation of this class for how to configure max_depth and max_errors.

>>> validator = Validator()
>>> schema = Schema(type="string")
>>> validator.validate(schema, 3.14)
[{'instance_path': [], 'schema_path': ['type']}]
>>> validator.validate(schema, "foobar")
[]

Module contents