Schema

A collection of fields is represented by:

class resource_api.schema.Schema(validate_required_constraint=True, with_errors=True)

Base class for containers that would hold one or many fields.

it has one class attribute that may be used to alter shcema’s validation flow

has_additional_fields (bool = False)
If True it shall be possible to have extra fields inside input data that will not be validated

NOTE: when defining schemas do not use any of the following reserved keywords:

  • find_fields
  • deserialize
  • get_schema
  • serialize
  • has_additional_fields

Schema example

A schema for a page with title, text, creation timestamp and a 5 star rating would look the following way:

class PageSchema(Schema):
    title = StringField(max_length=70)
    text = StringField()
    creation_time = DateTimeField()
    rating = IntegerField(min_value=1, max_value=5)

General field API

All fields inherit from BaseField and thus have its attributes in common.

class resource_api.schema.BaseField(description=None, required=True, **kwargs)

Superclass for all fields

description (None|string = None)
help text to be shown in schema. This should include the reasons why this field actually needs to exist.
required (bool = False)
flag that specifes if the field has to be present
**kwargs
extra parameters that are not programmatically supported

There are two extra parameters supported by Resource API:

readonly (bool=False)
if True field cannot be set nor changed but is a logical part of the resource. Resource creation time would be a good example.
changeable (bool=False)
if True field can be set during creation but cannot be change later on. User’s birth date is a valid example.

Primitive fields

There are two types of digit fields supported by schema. Integers and floats. Fields that represent them have a common base class:

class resource_api.schema.DigitField(min_val=None, max_val=None, **kwargs)

Base class for fields that represent numbers

min_val (int|long|float = None)
Minumum threshold for incoming value
max_val (int|long|float = None)
Maximum threshold for imcoming value

The fields representing integers and floats respecively are:

class resource_api.schema.IntegerField(min_val=None, max_val=None, **kwargs)

Transforms input data that could be any number or a string value with that number into long

class resource_api.schema.FloatField(min_val=None, max_val=None, **kwargs)

Transforms input data that could be any number or a string value with that number into float


Time related fields are represented by:

class resource_api.schema.DateTimeField(description=None, required=True, **kwargs)

datetime object serialized into YYYY-MM-DDThh:mm:ss.sTZD.

E.g.: 2013-09-30T11:32:39.984847

class resource_api.schema.DateField(description=None, required=True, **kwargs)

date object serialized into YYYY-MM-DD.

E.g.: 2013-09-30

class resource_api.schema.TimeField(description=None, required=True, **kwargs)

time object serialized into hh:mm:ssTZD.

E.g.: 11:32:39.984847

class resource_api.schema.DurationField(description=None, required=True, **kwargs)

timedelta object serialized into PnYnMnDTnHnMnS.

E.g.: P105DT9H52M49.448422S


Strings are represented by:

class resource_api.schema.StringField(regex=None, min_length=None, max_length=None, **kwargs)

Represents any arbitrary text

regex (string = None)
Python regular expression used to validate the string.
min_length (int = None)
Minimum size of string value
max_length (int = None)
Maximum size of string value

Various boolean flags exist in the schape of:

class resource_api.schema.BooleanField(default=None, **kwargs)

Expects only a boolean value as incoming data

Composite fields

class resource_api.schema.ListField(item_type, **kwargs)

Represents a collection of primitives. Serialized into a list.

item_type (python primitve|Field instance)
value is used by list field to validate individual items python primitive are internally mapped to Field instances according to PRIMITIVE_TYPES_MAP
PRIMITIVE_TYPES_MAP = {
    int: IntegerField,
    float: FloatField,
    str: StringField,
    unicode: StringField,
    basestring: StringField,
    bool: BooleanField
}
class resource_api.schema.ObjectField(schema, **kwargs)

Represents a nested document/mapping of primitives. Serialized into a dict.

schema (class):
schema to be used for validation of the nested document, it does not have to be Schema subclass - just a collection of fields

ObjectField can be declared via two different ways.

First, if there is a reusable schema defined elsewhere:

>>> class Sample(Schema):
>>>     object_field = ObjectField(ExternalSchema, required=False, description="Zen")

Second, if the field is supposed to have a unique custom schema:

>>> class Sample(Schema):
>>>     object_field = ObjectField(required=False, description="Zen", schema=dict(
>>>         "foo": StringField()
>>>     ))