Defining datatypes

Datatype definitions are intended to look like the values they define, and are themselves defined as anonymous datatypes.

For example, the following values:

{'first_name': 'Bob', 'last_name': 'Smith'}
{'first_name': 'John', 'last_name': 'Doe'}

are both valid instances of this datatype:

{'first_name': 'str', 'last_name': 'str'}

Primitives

Primitive types are defined as strings bearing the python constructor name.

• String: “str”
• Integer: “int”
• Float: “float”
• Boolean: “bool”

Primitive datatypes are, by default, not-nullable. This can be overridden by prefixing the datatype with the “nullable” flag. Example:

"nullable str"

Lists

Lists-types are homogeneous, and are defined as a list of one datatype.

Example:

["int"]

Represents a list of ints. While:

[{'height': 'float', 'width': 'float'}]

Represents a list of dictionaries (or “objects”).

Tuples

Tuples can be heterogeneous, but are fixed width and must have at least two items. Again, these are defined as lists of other datatypes:

["int", "str"]

Represents a tuple with two items. The first is an integer, and the second is a string.

Dictionaries

Dictionaries, or anonymous objects, are defined as dictionaries. The key of each item in the dictionary is the property-name, and the value must be another datatype definition. Example:

{'id': 'int', 'name': 'str', 'description': 'str'}

By default, all properties listed on the dictionary are required. The following value is invalid, as it lacks the required “description” property:

{'id': 5, 'name': 'invalid value'}

This behavior can be overridden by prefixing the property-name with the “optional” flag. This datatype is valid for the value listed above:

{'id': 'int', 'name': 'str', 'optional description': 'str'}

Arbitrary properties are supported when the wild-card key “_any_” is defined on the dictionary:

{'_any_': 'str'}

Literals

The ‘literal’ type can be used to require a specific value:

{'_type_': 'literal', 'value': 'my_literal_value'}

This value, and only this value, is a valid value for this datatype:

'my_literal_value'

Choices

To give an option between several datatypes, the choice type can be used. A choice is defined as a special type of dictionary:

{'_type_': 'choice', 'choices': ['int', 'str']}

This type allows for either an integer or a string.

Choices can be used anywhere other types can be used. This type, for example, represents a heterogeneous list of integers and booleans:

[{'_type_': 'choice', 'choices': ['int', 'bool']}]

The following are all valid values of this type:

[5, True, False]
[1, 2, 3]
[False]

Named/Recursive Types

Recursion requires the use of two special types: named and reference:

{'_type_': 'named', 'name': 'mytype', 'value': {'foo': 'bar'}}

{'_type_': 'reference', 'name': 'mytype'}

The named type does nothing more than provide a name to a datatype. The reference type, then, is used to refer to this named type a later point for things like recursion. Here’s a complete example:

{
    '_type_': 'named',
    'name': 'person',
    'value': {
        'name': 'str',
        'children': [{'_type_': 'reference', 'name': 'person'}]
    }
}

This type represents a person who can have a list of children, each of which, can have their own children, etc. The following is a valid value of this type:

{
    'name': 'bob',
    'children': [
        {
            'name': 'frank',
            'children': []
        },
        {
            'name': 'jane',
            'children': [
                {'name': 'alfred', 'children': []}
            ]
        }
    ]
}