A custom data type is always derived from an existing data type. This existing data type can be a built-in type or another custom type. To define a custom data type, refine the definition of an existing data type to meet your requirements by doing one or a combination of the following:

• Limiting the range of supported values

• Restricting the values to a particular format

• Adding or subtracting the criteria of another data type definition

Use the following syntax to define a custom data type. The required syntax is in bold.

The <type-name> argument specifies the name for identifying the custom data type. If this name includes any character other than a-z, A-Z, 0-9, or the underscore ( _ ) character, then you must enclose the name in single quotation marks ( ' ).

The <type-expression> argument specifies the SPL2 expression for deriving the definition of the custom data type from an existing type definition. The exact syntax of this expression varies depending on how you want to refine the data type that you're using as the starting point. For information about the supported syntax, see Supported custom data type expressions on this page.

For example, the following expression defines a custom data type named score that allows integer values ranging from 0 to 100:

type score = int WHERE $value BETWEEN 0 and 100

As another example, the following expression defines a custom data type named grade that allows the values A, B, C, D, and F:

type grade = string WHERE $value IN ("A", "B", "C", "D", "F")

Combining data types

Because custom data types are derived from existing types, you can combine and layer multiple data types together to create custom data types with finely tuned definitions that support your specific use cases.

For example, after defining the score and grade data types as described in the previous section, you can then define a custom data type named results that combines both of those types. This results data type allows the letter grade values A, B, C, D, and F as well as test score values between 0 and 100:

type results = grade | score

You can use parentheses to specify the order of operations in a type expression that has multiple parts to it. For example, the following data types are defined differently:

type final_course_results = grade | score[]

type assignment_marks = (grade | score)[]

The final_course_results data type allows values that are either a single letter grade or an array of the exam scores used to calculate the final letter grade. Examples of valid data values for the final_course_results type would be A and [97, 90, 87, 91].

The assignment_marks data type only allows an array of values, but the individual values in the array can be either letter grades or score numbers. Examples of valid data values for the assignment_marks data type would be [A, B, A, C], [97, 80, 91, 70], and [A, 80, 77, B].

SPL2 supports a variety of expressions that you can use to define a custom data type. You can use these expressions to limit the range of values that the type supports, restrict the values of that type to a particular format, and add or subtract criteria from another data type definition.

The following table categorizes and describes the type expressions that you can use to define a custom data type in SPL2:

type customer_details = customer + demographic

type fullnames = string[]

type http_error=int WHERE $value in([403, 404, 408])

type person =  { 
   firstname:string, 
   surname:string,
   age:int 
}

type customer = customer_details - demographic

type json = array | object

An additive data type is a derived data type that adds together the properties of 2 structured data types into a single structured data type. Use an additive type expression to describe data as a JSON object that contains properties that are already defined in existing structured data types.

If the structured types that you’re adding together contain properties that have the same name, then be aware of the following:

• Those properties must be associated with the same data type, or else an error occurs.

• If one property is required while another is optional, the resulting property in the additive data type will be required.

Syntax

The required syntax for structured types is in bold:

The required arguments are defined as follows:

Examples

Suppose you had created the following structured data types named customer and address:

type customer = { 
   id: int,
   name: string,
   age: int
}

type address = { 
   street: string,
   city: string,
   state: string,
   zip: int
}

The customer data type is a JSON object containing 3 properties: id, name, and age. The address data type is a JSON object containing 4 properties: street, city, state, and zip.

You can use the following expression to create an additive type named customerWithAddress that is a JSON object with all 7 of the properties defined in the customer and address types: id, name, age, street, city, state, and zip.

type customerWithAddress = customer + address

An array data type is a derived data type that defines an ordered collection of homogeneous values. Use an array type expression to describe data as a JSON array of same-typed values.

A constrained data type is a derived data type that adds constraints to an existing data type in order to make the type definition more narrow or precise. Use a constrained type expression to refine an existing data type by including more specific requirements.

When specifying the constraint, you can use the match function to require data values to match a regular expression. Regular expression matching allows you to define custom data types that capture complex and varied data values, such as IP addresses, credit card numbers, and social security numbers.

Syntax

The required syntax for structured types is in bold:

The required arguments are defined as follows:

Examples

The following expression defines a custom data type named positive_integer that is an integer greater than or equal to 0. Examples of valid positive_integer values include 1, 24, and 300.

type positive_integer = int WHERE $value >= 0

This next expression defines a custom data type named ipv4 that is a string that matches a regular expression for valid IPv4 addresses:

type ipv4 = string WHERE match($value, "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])")

As another example of using regular expression matches as the constraint, the following expression defines a custom data type named ipv6 that is a string that matches a regular expression for valid IPv6 addresses:

type ipv6 = string WHERE match($value, ("((([0-9a-fA-F]){1,4})\\:){7}([0-9a-fA-F]){1,4}"))

This next example demonstrates how to create a constrained data type that is based on a property in a structured data type. Consider the following structured data type called person:

type person =  { 
	firstname:string, 
	surname:string,
	age:int 
}

You can create a constrained data type called elderly_person that refers to the person data type and puts a constraint on the age property. In this example, the value for the age property in the person data type must be greater than 70:

type elderly_person = person WHERE $value.age > 70

A structured data type is a derived data type that defines an object containing one or more properties. Use a structured type expression to describe data as a JSON object.

A subtractive data type is a derived data type that subtracts the properties defined in one structured data type from the list of properties defined in another structured data type. Use a subtractive type expression to describe data as a JSON object that contains only a subset of the properties that are already defined in existing structured data types.

When you define a subtractive data type, you specify 2 structured data types, and the properties in the structured type that’s specified later are removed from the structured type that’s specified before it. The properties must meet the following requirements:

• The property in the later structured type must be of type any, or else an error occurs.

• If a property in the later structured type is required, then the same property must also exist in the earlier structured type, or else an error occurs.

• Wildcard fields denoted by asterisks ( * ) are treated like regular fields. If both structured types contain a wildcard field, the field will be removed and the resulting subtractive data type will not contain the wildcard field.

Syntax

The required syntax for structured types is in bold:

The required arguments are defined as follows:

Examples

type client = { 
   id: int,
   name: string,
   age: int
}

type person = { 
   name: string,
   age: int
}

type client_anonymized = client - person

A union data type is a derived data type that defines a collection of existing data types. Use union type expressions to create a custom data type that groups data of different types into a single data type.