opendigitaltwins-dtdl

Digital Twin Definition Language

Preview, Version 1

This version of DTDL was used for IoT Plug and Play preview support in IoT Hub and IoT Central.

If you are using IoT Central, refer to DTDL version 2. If you are using Azure Digital Twins, or Azure IoT Hub, refer to DTDL version 3

CapabilityModel
Interface
Telemetry
Property
Command
Primitive Schemas
Array
Enum
Map
Object
Interface Schemas
Model Versioning

Introduction

This document specifies the Digital Twin Definition Language (DTDL), a language for describing models and interfaces for IoT digital twins. Digital twins are models of entities in the physical environment such as shipping containers, rooms, factory floors, and other entities that participate in IoT solutions. Broadly, modeling enables IoT solutions to provision, use, and configure IoT devices and logical entities from multiple sources in a single solution. Using DTDL to describe a digital twin’s capabilities enables the IoT platform and IoT solutions to leverage the semantics of the entity.

Digital Twin Definition Language

Digital twins are described using a variant of JSON called JSON-LD. JSON-LD is designed to be usable directly as JSON as well as usable in Resource Description Framework (RDF) systems. RDF is a widely adopted standard for describing resources in a distributed, extensible way. We chose JSON-LD because it is JSON and it is an easy-to-use language for RDF. Developers can use DTDL with no knowledge of RDF, but equally important, can take advantage of semantic annotations and RDF using the same entity definitions.

DTDL is made up of a set of metamodel classes (described in the rest of this document) that define the capabilities of digital twins. There are two top-level classes, CapabilityModel and Interface, that describe digital twins and the capabilities of digital twins, respectively. There are three metamodel classes that describe capabilities: Telemetry, Property, and Command. In addition, because data is a key element in IoT solutions, DTDL provides a data description language that is compatible with many popular serialization formats, including JSON and binary serialization formats. When a digital twin uses DTDL, it describes its capabilities using these metamodel classes (Interfaces, Telemetry, Properties, Commands, and data types) and often implements those capabilities using an SDK in terms of these metamodel classes.

Lastly, DTDL provides semantic type annotations of capabilities, so that analytics, machine learning, UIs, and other computation can reason about the semantics of the data, not just the schema of the data. For example, properties that are semantically annotated as “temperature” can be reasoned about as temperature (charted together, compared, converted to like units, etc.) instead of simply double data types.

When writing a digital twin definition, it’s necessary to specify the version of DTDL being used. Because DTDL is based on JSON-LD, we use the JSON-LD context (the @context statement) to specify the version of DTDL being used.

CapabilityModel

A CapabilityModel describes a device and defines the set of interfaces implemented by the device.

A capability model includes the identifiers of the interfaces that it implements (including the version number). A new version of the capability model must be created when the device implements a new version of an interface, or when the device implements a new interface.

Capability models must follow these rules for the interfaces they implement.

A capability model can only implement one instance of each interface.
A capability model can only implement one version of each interface. A capability model cannot implement two versions of the same interface.
A newer version of a capability model must include all the interfaces implemented by the previous version (although the version numbers of the interfaces can be the same or greater than the interface versions in the previous capability model version).

CapabilityModel properties

CapabilityModel examples

This CapabilityModel example shows a thermostat that implements two Interfaces.

{
    "@id": "urn:example.com:thermostat_T_1000:1",
    "@type": "CapabilityModel",
    "displayName": "Thermostat T-1000",
    "implements": [
        {
            "name": "thermostat",
            "schema": "urn:example:thermostat:1"
        },
        {
            "name": "urn_azureiot_DeviceManagement_DeviceInformation",
            "schema": "urn:azureiot:DeviceManagement:DeviceInformation:1"
        }
    ],
    "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

This example shows defining an Interface inline with a CapabilityModel.

{
    "@id": "urn:example:thermostat_T_1000:1",
    "@type": "CapabilityModel",
    "displayName": "Thermostat T-1000",
    "implements": [
        {
            "name": "thermostat",
            "schema": {
                "@id": "urn:example:thermostat:1",
                "@type": "Interface",
                "displayName": "Thermostat",
                "contents": [
                ],
                "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
            }
        },
        {
            "name": "urn_azureiot_DeviceManagement_DeviceInformation",
            "schema": "urn:azureiot:DeviceManagement:DeviceInformation:1"
        }
    ],
    "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

Capability Model Interface (Implements)

A Capability Model Interface describes a part of a capability model. Interfaces enable capability models to be composed of many interfaces and for those interfaces to be named (so that name collisions across interfaces composed in a single capability model are mitigated).

Capability Model Interface properties

Interface

An Interface describes related capabilities that are implemented by a device or digital twin. Interfaces are reusable and can be reused across different capability models.

Interface properties

Interface examples

This Interface example shows a thermostat interface that implements one telemetry that reports the temperature measurement and one read/write property that controls the desired temperature.

{
    "@id": "urn:example:thermostat:1",
    "@type": "Interface",
    "displayName": "Thermostat",
    "contents": [
        {
            "@type": "Telemetry",
            "name": "temp",
            "schema": "double"
        },
        {
            "@type": "Property",
            "name": "setPointTemp",
            "writable": true,
            "schema": "double"
        }
    ],
    "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

Telemetry

Telemetry describes the data emitted by a device or digital twin, whether the data is a regular stream of sensor readings or an occasional error or information message.

Telemetry properties

Telemetry examples

{
    "@type": "Telemetry",
    "name": "temp",
    "schema": "double"
}

Property

A Property describes the read-only and read-write state of a device or digital twin. For example, a device serial number may be a read-only property and the temperature set point on a thermostat may be a read-write property.

Property properties

Property Examples

{
    "@type": "Property",
    "name": "setPointTemp",
    "schema": "double",
    "writable": true
}

Command

A command describes a function or operation that can be performed on a device or digital twin.

Command properties

Command examples

{
    "@type": "Command",
    "name": "reboot",
    "commandType": "asynchronous",
    "request": {
        "name": "rebootTime",
        "displayName": "Reboot Time",
        "description": "Requested time to reboot the device.",
        "schema": "dateTime"
    },
    "response": {
        "name": "scheduledTime",
        "schema": "dateTime"
    }
}

CommandType

Command types are defined for the command’s commandType property.

`commandType` value	Description
asynchronous	The command completes sometime after control returns to the caller. After the command completes, the result, and any outputs, are available.
synchronous	The command is complete when control returns to the caller. The result, and any outputs, are available immediately. This is the default value for `commandType`.

CommandPayload

A CommandPayload describes the inputs to or the outputs from a command.

CommandPayload properties

Schemas

Schemas describe the on-the-wire or serialized format of the data in a digital twin interface. A full set of primitive data types are provided, along with support for a variety of complex schemas in the forms of Arrays, Enums, Maps, and Objects. Schemas described using DTDL are compatible with popular serialization formats, including JSON, Avro, Protobuf, and others.

Primitive schemas

A full set of primitive data types are provided and can be specified directly as the value in a schema statement in a digital twin interface.

Digital twin primitive schema	Description
boolean	A boolean value.
date	A date in ISO 8601 format.
datetime	A date and time in ISO 8601 format.
double	An IEEE 8-byte floating point number.
duration	A duration in ISO 8601 format.
float	An IEEE 4-byte floating point number.
integer	A signed 4-byte integer.
long	A signed 8-byte integer.
string	A UTF8 string.
time	A time in ISO 8601 format.

Complex schemas

Complex schemas are designed for supporting complex data types made up of primitive data types. Currently the following complex schemas are provided: Array, Enum, Map, and Object. A complex schema can be specified directly as the value in a schema statement or described in the interface schemas set and referenced in the schema statement.

Array

An Array describes an indexable data type where each element is of the same schema. The schema of an array element can itself be a primitive or complex schema.

Array properties

Array examples

{
    "@type": "Telemetry",
    "name": "ledState",
    "schema": {
        "@type": "Array",
        "elementSchema": "boolean"
    }
}

Enum

An Enum describes a data type with a set of named labels that map to values. The values in an enum can be either integers or strings, but the labels are always strings.

Enum properties

Enum examples

{
    "@type": "Telemetry",
    "name": "state",
    "schema": {
        "@type": "Enum",
        "valueSchema": "integer",
        "enumValues": [
            {
                "name": "offline",
                "displayName": "Offline",
                "enumValue": 1
            },
            {
                "name": "online",
                "displayName": "Online",
                "enumValue": 2
            }
        ]
    }
}

EnumValue

An EnumValue describes an element of an enum.

EnumValue properties

Map

A Map describes a data type of key-value pairs where the values share the same schema. The key in a map must be a string. The values in a map can be any schema.

Map properties

Map examples

{
    "@type": "Property",
    "name": "modules",
    "writable": true,
    "schema": {
        "@type": "Map",
        "mapKey": {
            "name": "moduleName",
            "schema": "string"
        },
        "mapValue": {
            "name": "moduleState",
            "schema": "string"
        }
    }
}

MapKey

A MapKey describes the key in a map. The schema of a MapKey must be string.

MapKey properties

MapValue

A MapValue describes the values in a map.

MapValue properties

Object

An Object describes a data type made up of named fields (like a struct in C). The fields in an object map can be primitive or complex schemas.

Object properties

Object examples

{
    "@type": "Telemetry",
    "name": "accelerometer",
    "schema": {
        "@type": "Object",
        "fields": [
            {
                "name": "x",
                "schema": "double"
            },
            {
                "name": "y",
                "schema": "double"
            },
            {
                "name": "z",
                "schema": "double"
            }
        ]
    }
}

Field

A Field describes a field in an object.

Field properties

Interface schemas

Within an interface definition, complex schemas may be defined for reusability across telemetry, properties, and commands. This is designed to promote readability and improved maintenance because schemas that are reused can be defined once (per interface). Interface schemas are defined in the schemas property of an interface. When an interface is defined within a capability model, any schemas defined in that interface may only be used in that interface, not across interfaces within the same capability model.

Interface schema properties

Interface schema examples

{
    "@id": "urn:example:reusableTypeExample:1",
    "@type": "Interface",
    "contents": [
        {
            "@type": "Telemetry",
            "name": "accelerometer1",
            "schema": "urn:example:acceleration:1"
        },
        {
            "@type": "Telemetry",
            "name": "accelerometer2",
            "schema": "urn:example:acceleration:1"
        }
    ],
    "schemas": [
        {
            "@id": "urn:example:acceleration:1",
            "@type": "Object",
            "fields": [
                {
                    "name": "x",
                    "schema": "double"
                },
                {
                    "name": "y",
                    "schema": "double"
                },
                {
                    "name": "z",
                    "schema": "double"
                }
            ]
        }
    ],
    "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

Model versioning

In DTDL, capability models and interfaces are versioned by a single version number (positive integer) in the last segment of their identifiers. Once a version of a capability model or interface is finalized (published, used in production, etc.), its definition is immutable.

DTDL provides two ways to create new versions of capabilities models and interfaces.

Entirely new capability models and interfaces can be created to describe major changes, including breaking changes, such as removing a capability (telemetry, property, or command). Each major version has new identifier and starts its version number at 1.
New versions of capability models and interfaces can be created to describe minor changes, such as adding a new capability (telemetry, property, or command) or fixing a bug in a display name or description. Each minor version increments the version number of the capability model or interface.

In general, minor changes include adding new capabilities (telemetry, properties, and commands) or changing metadata, such as display names or descriptions. Changing capability names or schemas or removing capabilities is not allowed from version to version. The specific rules for versioning are described with each model element in this document.

Model Versioning Examples

This example shows the kinds of changes that are allowed in new versions of an interface. In this example,

The interface’s @id is updated to reflect the new version.
The interface’s description is updated.
The temp telemetry’s displayName and displayUnit are updated.

A new humidity telemetry is added.

{
  "@id": "urn:example:thermostat:1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Thermostat that measures temperature.",
  "contents": [
      {
          "@type": "Telemetry",
          "name": "temp",
          "displayName": "Measured temp",
          "schema": "double",
          "displayUnit": "F"
      }
  ],
  "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

{
  "@id": "urn:example:thermostat:2",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Thermostat that measures temperature and humidity.",
  "contents": [
      {
          "@type": "Telemetry",
          "name": "temp",
          "displayName": "Measured temperature",
          "schema": "double",
          "displayUnit": "Fahrenheit"
      },
      {
          "@type": "Telemetry",
          "name": "humidity",
          "schema": "integer"
      }
  ],
  "@context": "http://azureiot.com/v1/contexts/IoTModel.json"
}

Additional concerns

Digital Twin identifier format

Identities for all digital twin model elements must follow the digital twin identifier format. The digital twin model element identifier format is a simple URN, summarized here.

Identifiers must start with the string “urn:”.
Each segment may only contain the characters a-z, A-Z, 0-9, and underscore, conforming to this regular expression ^[a-zA-Z_][a-zA-Z0-9_]*$.
The only separator allowed is the colon character ‘:’.
Identifiers are case sensitive.
A valid identifier has at least four segments.
1. The “urn” segment.
2. A namespace segment. This segment may be made up of one or more segments.
3. The name segment (second-to-last segment).
4. The version segment (last segment).

Examples of digital twin model element identifiers.

urn:example:Thermostat:1
urn:iot:area51:dept42:Thruster:345
urn:contoso:AHU:dischargeAirTempSensor:6

Display string localization

Some string properties in digital twins are meant for human display and, therefore, support localization. Localizable string in digital twin use JSON-LD’s string internationalization support. Each localizable property (i.e. displayName, displayUnit, and description) is defined to be a JSON-LD language map ("@container": "@language"). The default language for digital twin documents is English. Localized string values are declared using their language code (as defined in BCP47). Because of the composable nature of JSON-LD graphs, localized strings can be prepared in a separate file and merged with an existing graph.

Localization examples

In this example, no language code is used for the displayName property, so the default language English is used.

{
    "@id": "urn:example:thermostat:1",
    "@type": "Interface",
    "displayName": "Thermostat"
}

In this example, the displayName property is localized into multiple languages.

{
    "@id": "urn:example:thermostat:1",
    "@type": "Interface",
    "displayName": {
        "en": "Thermostat",
        "it": "Termostato"
    }
}

Context

For this version of DTDL, the context is exactly http://azureiot.com/v1/contexts/IoTModel.json.

This site is open source. Improve this page.

opendigitaltwins-dtdl

Digital Twin Definition Language

Contents

Introduction

Digital Twin Definition Language

CapabilityModel

CapabilityModel properties

CapabilityModel examples

Capability Model Interface (Implements)

Capability Model Interface properties

Interface

Interface properties

Interface examples

Telemetry

Telemetry properties

Telemetry examples

Property

Property properties

Property Examples

Command

Command properties

Command examples

CommandType

CommandPayload

CommandPayload properties

Schemas

Primitive schemas

Complex schemas

Array

Array properties

Array examples

Enum

Enum properties

Enum examples

EnumValue

EnumValue properties

Map

Map properties

Map examples

MapKey

MapKey properties

MapValue

MapValue properties

Object

Object properties

Object examples

Field

Field properties

Interface schemas

Interface schema properties

Interface schema examples

Model versioning

Model Versioning Examples

Additional concerns

Digital Twin identifier format

Display string localization

Localization examples

Context