Open Data Description Language (OpenDDL)

An OpenDDL file is composed of a sequence of structures. A single structure consists of a type identifier followed by an optional name, an optional list of properties, and then its data payload enclosed in braces, as shown in Figure 1. There are two general types of structures, those with built-in types that contain primitive data such as integers or strings, and those that represent custom data structures defined by a derivative file format. As an example, suppose that a derivative file format defined a data type called Vertex that contains the 3D coordinates of a single vertex position. This could be written as follows.

Vertex
{
    float {1.0, 2.0, 3.0}
}

The Vertex identifier represents a custom data structure defined by the derivative file format, and it contains another structure of type float, which is a built-in primitive data type. The data in the float structure consists of the three values 1.0, 2.0, and 3.0. In general, raw data values in a primitive data structure are specified as a homogeneous comma-separated list of unbounded size, as shown in Figure 2.

The raw data inside a primitive data structure may also be specified as a comma-separated list of subarrays of values, as shown in Figure 3. The size of each subarray is specified by placing a positive integer value inside brackets immediately following the primitive type identifier, preceding the structure's name if it has one. Each value contained in the primitive data structure is then written as a comma-separated array of values enclosed in braces. As an example, suppose that a VertexArray structure expects to contain an array of 3D positions, each of which is specified as an array of three floating-point values. This would be written as follows.

VertexArray
{
    float[3]
    {
        {1.0, 2.0, 3.0},
        {0.5, 0.0, 0.5},
        {0.0, -1.0, 4.0}
    }
}

The number of elements in each subarray must always match the array size specified inside the brackets following the primitive type identifier. If the array size is one, then the braces are still required.

Note that a reader would use its knowledge of the already-parsed data type to choose only a single rule in Figures 2 and 3, as opposed to allowing any of the types of data to appear inside the braces. (It is also not possible to disambiguate among the numerical data types without some extra information.) This restriction could be expressed in the grammar, but doing so would come at a significant cost in conciseness.

OpenDDL defines the 15 primitive data types shown in Figure 4, and they are described in the following table. Each of the primitive data types has a long type and a short type. There is no difference in the meaning, and the long and short types can be used interchangeably. Additionally, the three floating-point data types each have two long types and two short types that all have equivalent meanings.

When used as the identifier for a data structure, each entry in the above table indicates that the structure is a primitive structure and its data payload is composed of an array of literal values. Primitive structures cannot have substructures.

There is no implicit type conversion in OpenDDL. Data values belonging to a primitive structure must be parsable as literal values corresponding to the primitive data type.

The type data type is convenient for schemas built upon OpenDDL itself in order to define valid type usages in derivative file formats.

An identifier in OpenDDL is a sequence of characters composed from the set {A–Z, a–z, 0–9, _}, as shown in Figure 5. That is, an identifier is composed of uppercase and lowercase roman letters, the numbers 0–9, and the underscore. An identifier cannot begin with a number.

Identifiers are used to identify data structure types, structure names, and properties. The identifiers used for the 15 primitive data types shown in the above table are reserved as structure types, but they can still be used as structure names and property identifiers. All identifiers consisting of a single lowercase letter followed by zero or more numerical digits are also reserved as structure types for future use by the language.

Any structure in an OpenDDL file may have a name. Names are used to reference other structures from within primitive data structures or through property values. A name can be a global name or a local name. Each global name must be unique among all global names used inside the file containing it, and each local name must be unique among all local names used by its siblings in the structure tree. Local names can be reused inside different structures, and they can duplicate global names.

As shown in Figure 6, a name is composed of either a dollar sign character ($) or percent sign character (%) followed by an identifier with no intervening whitespace. A name that begins with a dollar sign is a global name, and a name that begins with a percent sign is a local name. A name is assigned to a structure by placing it right after the structure identifier (and no whitespace is technically required before the dollar sign), as in the following example.

Vertex $apex
{
    float {1.0, 2.0, 3.0}
}

This structure can be referenced from elsewhere in the file by using the name $apex.

A reference value is used to form a link to a specific structure within an OpenDDL file. If the target structure has a global name, then the value of a reference to it is simply the name of the structure, beginning with the dollar sign character. If the target structure has a local name, then the value of a reference to it depends on the scope in which the reference appears. If the reference appears in a structure that is a sibling of the target structure, then its value is the name of the target structure, beginning with the percent sign character. Otherwise, the value of the reference consists of a sequence of names, as shown in Figure 7, that identify a sequence of structures along a branch in the structure tree. Only the first name in the sequence can be a global name, and the rest must be local names.

The value of a reference can also be keyword null to indicate that a reference has no target structure.

In the following example, where the Person, Name, and Friends data types are defined by some derivative format, references are used to link a data structure representing a person to the data structures representing his friends.

Person $chuck
{
    Name {string {"Charles"}}

    Friends
    {
        ref {$alice, $bob}
    }
}

Person $alice {...}
Person $bob {...}

A custom data structure in a derivative format may define one or more properties that can be specified separately from the data that the structure contains. Properties are written in a comma-separated list inside parentheses following the name of the structure (or just following the structure identifier if there is no name). As shown in Figure 8, each property is composed of a property identifier followed by an equals character (=) and the value of the property. The type of the property’s value must be specified by some external source of information such as a schema or program associated with a derivative format. For example, a string cannot be specified for a property that was expecting an integer. The specified type determines which rule in Figure 8 is applied, and a mismatch must be detected at the time that the property is parsed.

As an example, suppose that a data structure called Model defined a property called lod that takes an integer representing the level of detail to which its contents belong. This property would be specified as follows.

Model (lod = 2)
{
    ...
}

If another property called part existed and accepted a string (perhaps to identify a body part), then that property could be added to the list as follows.

Model (lod = 2, part = "Left Hand")
{
    ...
}

The order in which properties are listed is insignificant. Derivative file formats may require that certain properties always be specified. Optional properties must always have a default value or be specially handled as being in an unspecified state. The same property can be specified more than once in the same property list, and in such a case, all but the final value specified for the same property must be ignored.

The syntax does not allow primitive data types to have a property list. (See Figure 1.)

A boolean value is one of the keywords false or true, as shown in Figure 9.

The language allows integers to be specified as a decimal number, a hexadecimal number, an octal number, a binary number, or a single-quoted character literal.

Between any two consecutive digits of each type of integer literal, a single underscore character may be inserted as a separator to enhance readability. The presence of underscore characters and their positions have no significance, and they do not affect the value of a literal.

A decimal literal is simply composed of a sequence of numerical digits, as shown in Figure 10, and leading zeros are permitted.

A hexadecimal literal is specified by prefixing a number with 0x or 0X, as shown in Figure 12. This is followed, without any intervening whitespace, by any number of hexadecimal digits that don't cause the underlying integer type to overflow. As shown in Figure 11, the use of the letters A–F in a hexadecimal literal is not case sensitive.

An octal literal is specified by prefixing a number with 0o or 0O, as shown in Figure 13. This is followed, without any intervening whitespace, by any number of digits between 0 and 7, inclusive, that don't cause the underlying integer type to overflow.

A binary literal is specified by prefixing a number with 0b or 0B, as shown in Figure 14. This is followed, without any intervening whitespace, by any number of zeros and ones that don't cause the underlying integer type to overflow.

A character literal is specified by a sequence of printable ASCII characters enclosed in single quotes, as shown in Figure 16. OpenDDL supports the escape sequences listed in the following table and illustrated in Figure 15. Escape sequences may be used to generate control characters or arbitrary byte values. The single quote (') and backslash (\) characters cannot be represented directly and must be encoded with escape sequences. The \x escape sequence is always followed by exactly two hexadecimal digits. Each character (after resolving escape sequences) corresponds to exactly one byte in the resulting integer value, and the right-most character corresponds to the least significant byte.

An integer literal is composed of an optional plus or minus sign followed by a decimal, hexadecimal, octal, binary, or character literal, as shown in Figure 17.

In the following example, the same integer value is repeated five times using different literal types.

unsigned_int32
{
    1094861636,
    0x41424344,
    0o10120441504,
    0b0100_0001_0100_0010_0100_0011_0100_0100,
    'ABCD'
}