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