Defining New Datatypes¶
yggdrasil supports two methods for defining new datatypes, either by creating an alias for a complex datatype expressed in terms of the existing datatypes (as described here) or through a Python class. Reguardless of the method used, the datatype will automatically be registered and added to the metaschema.
JSON Defined Datatypes¶
To define a datatype in terms of the existing datatypes, developers can save the schema defining the datatype to a .json file in the yggdrasil/metaschema/datatypes/schemas directory. yggdrasil automatically loads schemas found in that directory and creates metaschema type classes from them. The created class’s name will be based on the ‘title’ field listed in the schema. Schemas must have, at minimum, values for the ‘title’, ‘description’, and ‘type’ metaschema properties and must be a valid schema (i.e. can be validated using the metaschema.
Class Defined Datatypes¶
Class defined data types should subclass the
yggdrasil.metaschema.datatypes.MetaschemaType.MetaschemaType
base.
The file containing the class definitions should reside in the
‘yggdrasil/metaschema/datatypes/’ directory.
At a minimum, classes for types defined in such a manner must override the following method:
encode_data
: Takes as input an object for encoding and a type definition and returns the encoded object which is of a type that is encodable by the standard JSON library.decode_data
: The reverse ofencode_data
. Takes as input an encoded object and the associated type definitions and returns the decoded object.
In addition, the behavior of types defined using classes are also controlled by the following class attributes:
Option |
Description |
Required |
Type |
---|---|---|---|
description |
A short description of the type. |
X |
str |
name |
Name of the type for use in YAML files & form options. |
X |
str |
cross_language_support |
If True, this indicates the types should be serializable across most (if not all) of the supported languages. If False, this type is not required to be serializable except to/from Python. Defaults to True. |
bool |
|
definition_properties |
Type properties that are required for YAML or form entries specifying the type. These will also be used to validate type definitions. These properties will be added to those from the parent type class unless inherit_properties is False. Defaults to [‘type’]. |
list |
|
extract_properties |
Properties that will be extracted from the metadata of a message to construct the type definition. These properties will be added to those from the parent class unless inherit_properties is False. Defaults to [‘type’, ‘title’]. |
list |
|
inherit_properties |
If True, a type class’s properties will be a combination of the parent class’s properties and those explicitly defined in the child class. If False, a type class’s properties will only be those explicitly defined in the child class. If a list of property attributes, only properties specified by those attributes will be inherited from the parent class. |
bool, list |
|
is_fixed |
True if the type is a fixed version of another type. See FixedMetaschemaType for details. |
bool |
|
loaded_schema_file |
The path to the file the schema for the type was loaded from if it was loaded. |
str, None |
|
metadata_properties |
Type properties that are required for deserializing instances of the type that have been serialized. These properties will be added to those from the parent class unless inherit_properties is False. Defaults to [‘type’]. |
list |
|
properties |
List of JSON schema properties that this type uses. These properties will be added to those form the paretn type class unless inherit_properties is False. Defaults to [‘type’, ‘title’]. |
list |
|
python_types |
List of python types that this type encompasses. [REQUIRED]. |
list |
|
schema_file |
If set, the class’s schema is loaded from the specified file at registration and moved to the loaded_schema_file class attribute. Defaults to None. |
str, None |
|
specificity |
Specificity of the type. Types with larger values are more specific while types with smaller values are more general. Base types have a specificity of 0. More specific types are checked first before more general ones. |
int |
For class defined data types, developers should also develop tests for the
new data types using
yggdrasil.metaschema.datatypes.tests.test_MetaschemaType.TestMetaschemaType
as a base class. Generally, developers should be able to control the testing of
their class by specifying values for the following class attributes:
Class Defined Properties¶
yggdrasil also supports the addition of new metaschema properties by subclassing
the yggdrasil.metaschema.properties.MetaschemaProperty.MetaschemaProperty
The file containing the class definitions should reside in the
‘yggdrasil/metaschema/properties/’ directory.
At a minimum, classes for properties defined in such a manner must override the following method:
encode
: Takes as input an object for encoding and a type definition and returns the value for the property describing the object.
In addition, the behavior of properties are also controlled by the following class attributes:
Option |
Description |
Required |
Type |
---|---|---|---|
name |
Name of the property. |
X |
str |
schema |
JSON schema describing valid values for the property. |
X |
dict |
python_types |
Python types of instances that the property is valid for. [AUTOMATED] |
list |
|
types |
Types of instances that the property is valid for. [AUTOMATED] |
list |