Text representation of data types

Introduction

Since YQL is a strongly typed language, the data type is important for many of its aspects. To make data type management easy, YQL has a data type definition convention in text format. It's mentioned in many places in the documentation. There's also a library that provides functions for building a data type based on a text description (for example, when manually defining the signature for the called value) or for serializing the data type into a string for debugging purposes.

Functions for data types are described in the article. Below is the format of text representation of data types.

General conventions

• Primitive data types are represented in text format simply by referencing their name.
• A complex data type is composed of other data types. If you depict this structure as a tree, it has primitive data types as leaves and containers as other nodes. You may treat special data types as exceptions, because they can function as both.
• The text representation repeats the structure of this tree from the root to the leaves: each node of the tree specifies the name of the current data type, and proceeding to a deeper level is denoted by different types of brackets.
• Feel free to use spaces and line breaks if they improve readability.
• If the ID contains something else except the Latin letters and numbers, put it in single quotes and use C-escaping.

Containers

• Use angle brackets to specify the types of container elements.

  Example: List<Int32>.

• If a container can hold multiple heterogeneous elements, they are listed inside angle brackets with a comma.

  Example: Tuple<Int32, String>.

• If a container can hold named elements, use comma-separated name-type pairs with a colon in-between instead of comma-separated data types.

  Example: Struct<a:Int32, b:String>.

• The underlying Variant container type is chosen based on the presence of names in arguments.

  Example: Variant<Int32, String> is a variant on tuple, Variant<a:Int32, b:String> is a variant on structure.

Types that allow NULL

• They are called Optional in YQL terms, or nullable in the classic SQL terms.

• Formally, this type is a container. So, you may declare it as Optional<...>, but the shortcut notation of a question mark suffix is usually used instead.

  Example: String?.

Called values

• The basic form of the called values looks as follows: (arg1, arg2, ...) -> result.

  An example of declaring a function signature that accepts two strings and returns a number: (String, String) -> Int64.

• The called values can return the called values: in this case, they make up a chain of the required length.

  Example: (String, String) -> (String, String) -> Int64.

• Optional arguments must have the Optional type at the top level and be enclosed in square brackets.

  Example: (String, [String?, Double?]) -> Int64.

• The arguments of the called values can contain flags.

  Currently, the only possible flag is AutoMap. It means that if NULL is passed to this argument, the result must also be set to NULL without running the function.

  Example: (String{Flags: AutoMap}) -> Int64.

• Use this particular format if you need Optional<Callable...>, because the trailing question mark refers to the result of the called value.

Resources

• Unlike containers, a resource isn't parameterized by the element type (it's a pointer in memory and YQL knows nothing about its contents). Instead, a resource is parameterized by a string label that can safeguard against passing resources between incompatible functions.

  Example: Resource<Foo>.