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 of encode_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