Fields

Primitive Fields

class jsl.fields.NullField(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]

A null field.

class jsl.fields.BooleanField(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]

A boolean field.

class jsl.fields.NumberField(multiple_of=None, minimum=None, maximum=None, exclusive_minimum=None, exclusive_maximum=None, **kwargs)[source]

A number field.

Parameters:
  • multiple_of (number or Resolvable) – A value must be a multiple of this factor.
  • minimum (number or Resolvable) – A minimum allowed value.
  • exclusive_minimum (bool or Resolvable) – Whether a value is allowed to exactly equal the minimum.
  • maximum (number or Resolvable) – A maximum allowed value.
  • exclusive_maximum (bool or Resolvable) – Whether a value is allowed to exactly equal the maximum.
multiple_of = None
minimum = None
exclusive_minimum = None
maximum = None
exclusive_maximum = None
class jsl.fields.IntField(multiple_of=None, minimum=None, maximum=None, exclusive_minimum=None, exclusive_maximum=None, **kwargs)[source]

Bases: jsl.fields.primitive.NumberField

An integer field.

class jsl.fields.StringField(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]

A string field.

Parameters:
  • pattern (string or Resolvable) – A regular expression (ECMA 262) that a string value must match.
  • format (string or Resolvable) – A semantic format of the string (for example, "date-time", "email", or "uri").
  • min_length (int or Resolvable) – A minimum length.
  • max_length (int or Resolvable) – A maximum length.
pattern = None
format = None
min_length = None
max_length = None
class jsl.fields.EmailField(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]

Bases: jsl.fields.primitive.StringField

An email field.

class jsl.fields.IPv4Field(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]

Bases: jsl.fields.primitive.StringField

An IPv4 field.

class jsl.fields.DateTimeField(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]

Bases: jsl.fields.primitive.StringField

An ISO 8601 formatted date-time field.

class jsl.fields.UriField(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]

Bases: jsl.fields.primitive.StringField

A URI field.

Compound Fields

jsl.fields.RECURSIVE_REFERENCE_CONSTANT

A special value to be used as an argument to create a recursive DocumentField.

class jsl.fields.DocumentField(document_cls, as_ref=False, **kwargs)[source]

A reference to a nested document.

Parameters:
  • document_cls – A string (dot-separated path to document class, i.e. "app.resources.User"), RECURSIVE_REFERENCE_CONSTANT or a Document subclass.
  • as_ref (bool) – If True, the schema of document_cls` is placed into the definitions dictionary, and the field schema just references to it: {"$ref": "#/definitions/..."}. It may make a resulting schema more readable.
owner_cls = None

A Document this field is attached to.

as_ref = None
document_cls

A Document this field points to.

class jsl.fields.RefField(pointer, **kwargs)[source]

A reference.

Parameters:pointer (str) –

A JSON pointer.

pointer = None
class jsl.fields.ArrayField(items=None, additional_items=None, min_items=None, max_items=None, unique_items=None, **kwargs)[source]

An array field.

Parameters:
  • items

    Either of the following:

    • BaseField – all items of the array must match the field schema;
    • a list or a tuple of fields – all items of the array must be valid according to the field schema at the corresponding index (tuple typing);
    • a Resolvable resolving to either of the first two options.
  • min_items (int or Resolvable) – A minimum length of an array.
  • max_items (int or Resolvable) – A maximum length of an array.
  • unique_items (bool or Resolvable) – Whether all the values in the array must be distinct.
  • additional_items (bool or BaseField or Resolvable) – If the value of items is a list or a tuple, and the array length is larger than the number of fields in items, then the additional items are described by the BaseField passed using this argument.
items = None
min_items = None
max_items = None
unique_items = None
additional_items = None
class jsl.fields.DictField(properties=None, pattern_properties=None, additional_properties=None, min_properties=None, max_properties=None, **kwargs)[source]

A dictionary field.

Parameters:
  • properties (dict[str -> BaseField or Resolvable]) – A dictionary containing fields.
  • pattern_properties (dict[str -> BaseField or Resolvable]) – A dictionary whose keys are regular expressions (ECMA 262). Properties match against these regular expressions, and for any that match, the property is described by the corresponding field schema.
  • additional_properties (bool or BaseField or Resolvable) – Describes properties that are not described by the properties or pattern_properties.
  • min_properties (int or Resolvable) – A minimum number of properties.
  • max_properties (int or Resolvable) – A maximum number of properties
properties = None
pattern_properties = None
additional_properties = None
min_properties = None
max_properties = None
class jsl.fields.NotField(field, **kwargs)[source]
Parameters:field (BaseField or Resolvable) – A field to negate.
field = None
class jsl.fields.OneOfField(fields, **kwargs)[source]
Parameters:fields (list[BaseField or Resolvable]) – A list of fields, exactly one of which describes the data.
fields = None
class jsl.fields.AnyOfField(fields, **kwargs)[source]
Parameters:fields (list[BaseField or Resolvable]) – A list of fields, at least one of which describes the data.
fields = None
class jsl.fields.AllOfField(fields, **kwargs)[source]
Parameters:fields (list[BaseField or Resolvable]) – A list of fields, all of which describe the data.
fields = None

Base Classes

jsl.fields.Null = <jsl.fields.base.NullSentinel object>

A special value that can be used to set the default value of a field to null.

class jsl.fields.BaseField(name=None, required=False, **kwargs)[source]

A base class for fields of documents. Instances of this class may be added to a document to define its properties.

Implements the Resolvable interface.

Parameters:
  • required (bool or Resolvable) – Whether the field is required. Defaults to False.
  • name (str) –

    If specified, used as a key under which the field schema appears in document schema properties.

    New in version 0.1.3.

name = None

Name

required = None

Whether the field is required.

resolve(role)[source]

Implements the Resolvable interface.

Always returns a Resolution(self, role).

Return type:Resolution
iter_possible_values()[source]

Implements the Resolvable interface.

Yields a single value – self.

get_definitions_and_schema(role='default', res_scope=ResolutionScope( base=, current=, output= ), ordered=False, ref_documents=None)[source]

Returns a tuple of two elements.

The second element is a JSON schema of the data described by this field, and the first is a dictionary that contains definitions that are referenced from the schema.

Parameters:
  • role (str) – A role.
  • ordered (bool) – If True, the resulting schema dictionary is ordered. Fields are listed in the order they are added to the class. Schema properties are also ordered in a sensible and consistent way, making the schema more human-readable.
  • res_scope (ResolutionScope) – The current resolution scope.
  • ref_documents (set) – If subclass of Document is in this set, all DocumentField s pointing to it will be resolved to a reference: {"$ref": "#/definitions/..."}. Note: resulting definitions will not contain schema for this document.
Raises:

SchemaGenerationException

Return type:

(dict, dict or OrderedDict)

iter_fields()[source]

Iterates over the nested fields of the document examining all possible values of the occuring resolvables.

walk(through_document_fields=False, visited_documents=frozenset([]))[source]

Iterates recursively over the nested fields, examining all possible values of the occuring resolvables.

Visits fields in a DFS order.

Parameters:
  • through_document_fields (bool) – If True, walks through nested DocumentField fields.
  • visited_documents (set) – Keeps track of visited documents to avoid infinite recursion when through_document_field is True.
Returns:

iterable of BaseField

resolve_and_iter_fields(role='default')[source]

The same as iter_fields(), but resolvables are resolved using role.

resolve_and_walk(role='default', through_document_fields=False, visited_documents=frozenset([]))[source]

The same as walk(), but resolvables are resolved using role.

get_schema(ordered=False, role='default')[source]

Returns a JSON schema (draft v4) of the field.

Parameters:
  • role (str) – A role.
  • ordered (bool) – If True, the resulting schema dictionary is ordered. Fields are listed in the order they are added to the class. Schema properties are also ordered in a sensible and consistent way, making the schema more human-readable.
Raises:

SchemaGenerationException

Return type:

dict or OrderedDict

resolve_attr(attr, role='default')[source]

Resolves an attribure with the name field using role.

If the value of attr is resolvable, it resolves it using a given role and returns the result. Otherwise it returns the raw value and role unchanged.

Raises:AttributeError
Return type:Resolution
class jsl.fields.BaseSchemaField(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]

A base class for fields that directly map to JSON Schema validator.

Parameters:
  • required (bool or Resolvable) – If the field is required. Defaults to False.
  • id (str) – A string to be used as a value of the “id” keyword of the resulting schema.
  • default (any JSON-representable object, a callable or a Resolvable) – The default value for this field. May be Null (a special value to set the default value to null) or a callable.
  • enum (list, tuple, set, callable or Resolvable) – A list of valid choices. May be a callable.
  • title (str or Resolvable) – A short explanation about the purpose of the data described by this field.
  • description (str or Resolvable) – A detailed explanation about the purpose of the data described by this field.
id = None

A string to be used as a value of the “id” keyword of the resulting schema.

title = None

A short explanation about the purpose of the data.

description = None

A detailed explanation about the purpose of the data.

get_enum(role='default')[source]

Returns a list to be used as a value of the "enum" schema keyword.

get_default(role='default')[source]

Returns a value of the "default" schema keyword.