Fields

Primitive Fields

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

A null field.

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

A boolean field.

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

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)

Bases: jsl.fields.primitive.NumberField

An integer field.

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

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)

Bases: jsl.fields.primitive.StringField

An email field.

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

Bases: jsl.fields.primitive.StringField

An IPv4 field.

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

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)

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)

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)

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)

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)

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)

Parameters:field (BaseField or Resolvable) – A field to negate.

field = None

class jsl.fields.OneOfField(fields, **kwargs)

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)

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)

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)

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)

Implements the Resolvable interface.

Always returns a Resolution(self, role).

Return type:Resolution

iter_possible_values()

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)

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()

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

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

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')

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

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

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

get_schema(ordered=False, role='default')

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')

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)

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')

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

get_default(role='default')

Returns a value of the "default" schema keyword.