DLI Type Description Reference
20210421T131028Z
Overview

The DLI type description specifies the interface of an object in a human- and machine-readable way. It is in a way similar to XML DTDs and the various attempts to create a JSON schema, because it can be used to understand what a serialized representation of the object is supposed to look like. However, it describes not only properties of the representation, but also of the object itself, which are useful in interacting with the object. Data are presented and manipulated as an hierarchy of interdependent objects, with possibly complex constraints, traits and permissions.

Target audience

The DLI type description is the basis of the REST-style API of modern DLI controllers. Though being tailor-made for this application, the description system itself is not limited to it, and can be used in other products as well.

Design goals

  • Human readability

    Basic DLI type descriptions are supposed to be readable by humans. Unfortunately this means that the same structure can have different meanings in different contexts, which slightly complicates automated processing.

  • Interoperability

    The type descriptions and the objects to be described are expected to be serializable to JSON, a popular interchange format.

  • Extensibility

    There are many extension points in the type description format. Clients reading unexpected description elements can understand whether the new elements are critical for their interaction with the object, or not.

Design non-goals

We explicitly choose not to consider:

  • Expressing description format in terms of itself

    There is no need for describing a type for "type description" itself in our applications.

  • Completely specifying behaviour and constraints

    Objects can have behaviour or constraints which are impossible or hard to model. You may need to handle error results even if your interaction with the object appears to be correct.