Fields
Fields are passed as a dictionary to the Schema classes:
import typesystem
user_schema = typesystem.Schema(fields={"name": typesystem.String()})
definitions = typesystem.Definitions()
definitions["User"] = user_schema
organization_schema = typesystem.Schema(
fields={
"name": typesystem.String(title="Name", max_length=100),
"date_created": typesystem.Date(title="Date created", default=datetime.date.today),
"owner": typesystem.Reference(to="User", allow_null=True, definitions=definitions),
}
)
Fields are always required in inputs, unless a default value is set.
- Setting
allow_null
toTrue
will set the default toNone
. (Unlessdefault
is already set.) - Setting
allow_blank
toTrue
will set the default to""
. (Unlessdefault
orallow_null
is already set.)
All fields support the following arguments.
Arguments:
title
- A string to use when labelling the input. Default:None
description
- A string describing the input. Default:None
default
- A value to be used if no input is provided for this field. May be a callable, such asdatetime.datetime.now
. Default:NO_DEFAULT
allow_null
- A boolean determining ifNone
values are valid. Default:False
read_only
- A boolean determining if field should be considered as read-only, this is usually used in form rendering. Default:False
Using fields directly
You can use fields to validate data directly, rather than using them on a schema class. This is useful if you have a general datastructure that requires validation.
For instance, we could validate a dictionary of integers, like so:
validator = typesystem.Object(properties=typesystem.Integer())
value = validator.validate(data) # May raise `ValidationError`
Or returning a two-tuple of (value, ValidationError)
:
validator = typesystem.Object(properties=typesystem.Integer())
value, error = validator.validate_or_error(data)
if error:
...
else:
...
Textual data types
String
Validates single-line text inputs.
For example: username = typesystem.String(max_length=100)
Arguments:
allow_blank
- A boolean indicating if the empty string should validate. Default:False
trim_whitespace
- A boolean indicating if leading/trailing whitespace should be removed on validation. Default:True
max_length
- A maximum number of characters that valid input stings may contain. Default:None
min_length
- A minimum number of characters that valid input stings may contain. Default:None
pattern
- A regular expression that must match. This can be either a string or a compiled regular expression. E.g.pattern="^[A-Za-z]+$"
Default:None
format
- A string used to indicate a semantic type, such as"email"
,"url"
, or"color"
. Default:None
coerce_types
- A boolean determining if type casting should be done, E.g. changingNone
to""
ifallow_blank
. Default:True
Text
Validates multi-line strings. Takes the same arguments as String
.
Represented in HTML forms as a <textarea>
.
Password
Similar to String
and takes the same arguments.
Represented in HTML forms as a <input type="password">
.
Similar to String
and takes the same arguments.
Represented in HTML forms as a <input type="email">
.
IPAddress
Validates IPv4 and IPv6 addresses.
Returns ipaddress.IPv4Address
or ipaddress.IPv6Address
based on input.
URL
Similar to String
and takes the same arguments.
Represented in HTML forms as a <input type="url">
.
Boolean data types
Boolean
Represented in HTML forms as a <checkbox>
.
For example:
is_admin = typesystem.Boolean(default=False)
Because all fields are required unless a default
is given, you'll typically
want to use default=False
. This is particularly true if you want to render
boolean fields as HTML checkboxes, since they do not submit any input if unchecked.
Numeric data types
Number
The base class for Integer
, Float
, and Decimal
.
You won't typically want to use this class directly, since the subclasses provide more precise behaviour.
Arguments:
minimum
- A number representing the minimum allowed value. Inputs must be greater than or equal to this to validate. Default:None
maximum
- A number representing the maximum allowed value. Inputs must be less than or equal to this to validate. Default:None
exclusive_minimum
- A number representing an exclusive minimum. Inputs must be greater than this to validate. Default:None
exclusive_maximum
- A number representing an exclusive maximum. Inputs must be less than this to validate. Default:None
precision
- A string representing the decimal precision to truncate input with. E.g.precision="0.001"
. Default:None
multiple_of
- A number giving a value that inputs must be a strict multiple of in order to validate. E.g.multiple_of=2
will only validate even integers. Default:None
Integer
Takes the same arguments as Number
. Returns instances of int
.
Float
Takes the same arguments as Number
. Returns instances of float
.
Decimal
Takes the same arguments as Number
. Returns instances of decimal.Decimal
.
Enumeration data types
Choice
Provides a fixed set of options to select from.
Represented in HTML forms as a <select>
.
Arguments:
choices
- A list of two-tuples of(choice, description)
. Default: None
Date and time data types
DateTime
Validates ISO 8601 formatted datetimes. For example "2020-02-29T12:34:56Z"
.
Returns datetime.datetime
instances.
Date
Validates ISO 8601 formatted dates. For example "2020-02-29"
.
Returns datetime.date
instances.
Time
Validates ISO 8601 formatted times. For example "12:34:56"
.
Returns datetime.time
instances.
Composite data types
Array
Used to validate a list of data. For example:
# Validates data like `[8, 7, 0, 8, 4, 5]`
ratings = typesystem.Array(items=typesystem.Integer(minimum=0, maximum=10))
Arguments:
items
- Either aField
, used to validate each item in the list. Or a list ofField
instances, used to validate each item in the list, positionally. Default:None
additional_items
- Only valid ifitems
is a list. EitherTrue
orFalse
, or aField
. Used to validate each additional item in the list. Default:False
min_items
- An integer, indicating the minimum number of items that must be present in the list. Default:None
max_items
- An integer, indicating the maximum number of items that may be present in the list. Default:None
exact_items
- An integer, indicating the exact number of items that must be present in the list. Default:None
unique_items
- A boolean. Used to determine if duplicate items are allowed in the list. Default:False
Object
Used to validate a dictionary of data.
# Validates data like `{"address": "12 Steeple close", "delivery note": "Leave by porch"}`
extra_metadata = typesystem.Object(properties=typesystem.String(max_length=100))
Schema classes implement their validation behaviour by generating an Object
field, and automatically determining the properties
and required
attributes.
You'll typically want to use typesystem.Reference(to="SomeSchema")
rather than
using the Object
field directly, but it can be useful if you have a more
complex data structure that you need to validate.
Arguments:
properties
- Either aField
, used to validate each value in the object. Or a dictionary ofField
instances, used to validate each item in the list, by field name. Default:None
pattern_properties
- A dictionary mapping regex-style strings to field instances. Used to validate any items not inproperties
that have a key matching the regex. Default:None
additional_properties
- Either a boolean, used to indicate if additional properties are allowed, or aField
used to validate any items not inproperties
orpattern_properties
. IfNone
then additional properties are allowed, but are not included in the validated value. Default:None
min_properties
- An integer representing the minimum number of properties that must be included.max_properties
- An integer representing the maximum number of properties that may be included.required
- A list of strings indicating any fields that are strictly required in the input.
Reference
Used to reference a nested schema.
For example:
owner = typesystem.Reference(to="User", allow_null=True, definitions=definitions)
Arguments:
to
- Name of schema defined in definitions. Requireddefinitions
-Definitions
instance. Required
Other data types
UUID
Validates UUID in the format of 32 hexadecimal characters, separated by hyphens.
For example "cd11b0d7-d8b3-4b5c-8159-70f5c9ea96ab"
.
Returns uuid.UUID
instances.