Skip to main content

DTDL Tutorial

Welcome to the Digital Twins Definition Language (DTDL) tutorial page. This tutorial is designed to give you a foundational understanding of DTDL — what it is, its benefits, syntax, and how to use it.

Introduction to DTDL

What is DTDL?

Digital Twins Definition Language (DTDL) is a language developed by Microsoft for defining models for Plug and Play (PnP) devices, IoT devices, and Digital Twins. It's JSON-LD-based, making it straightforward to work with and widely applicable. It enables the description of the semantics of data, capabilities, and the relationships between digital twins.

Why Use DTDL?

  • Interoperability: By defining a common language for IoT solutions, DTDL allows for the seamless integration and interoperability of devices and systems.

  • Consistency: DTDL models ensure a consistent approach to IoT solutions, making them more manageable and scalable.

  • Efficiency: DTDL models help to streamline IoT development processes, reducing the need for custom code and thereby saving time and resources.

DTDL Syntax

DTDL Basics

DTDL is JSON-LD-based, which means it's fundamentally a JSON object with additional @context and @type fields.

A basic DTDL model might look like this:

{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"displayName": "Thermostat",
"description": "A thermostat device.",
"contents": [
{
"@type": "Property",
"name": "targetTemperature",
"schema": "double"
}
]
}

Key Components

  • @context: This is a required field that provides the context for interpreting the rest of the model. For DTDL, it should always be set to "dtmi:dtdl:context;2".

  • @id: This is a required field that provides a globally unique identifier for the model.

  • @type: This is a required field that specifies the type of the model. The primary types are "Interface", "Telemetry", "Property", and "Command".

  • name: The name of the telemetry, property, or command.

  • schema: The data type of the telemetry or property. This can be a primitive type (like "double" or "string") or a complex type (like an object or array).

Using DTDL

Let's walk through a typical process of using DTDL:

  1. Define your device: This involves creating a DTDL model that describes your device's capabilities. This might include telemetry it sends, properties it reports, and commands it responds to.

  2. Upload your model: Once your model is defined, you can upload it to your solution. This is typically done using the Azure IoT Model Repository.

  3. Implement your device: Now that your model is available, you can implement your device. This typically involves using a device SDK that understands DTDL, like the Azure IoT Device SDK.

  4. Connect your device: Once your device is implemented, it can connect to your solution. At this point, it will identify itself using the DTDL model id.

  5. Interact with your device: Now that your device is connected and its capabilities are understood, your solution can interact with it in a meaningful way. This might involve visualizing its telemetry, setting its properties, or invoking its commands.

Remember, DTDL is a flexible and powerful tool, but it's important to understand how to use it effectively to maximise its benefits.

Advanced Concepts

Relationships

DTDL allows for the expression of relationships between different digital twins. These relationships are directed and typed links between twins. They're defined in an Interface with the @type field set to "Relationship".

For instance, a car can be related to its engine through a "contains" relationship, defined as follows:

{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Car;1",
"@type": "Interface",
"displayName": "Car",
"contents": [
{
"@type": "Relationship",
"name": "contains",
"minMultiplicity": 0,
"maxMultiplicity": 1,
"target": "dtmi:com:example:Engine;1"
}
]
}

Components

DTDL also supports the concept of components, which are reusable chunks of DTDL that can be included in other models. They're defined in an Interface with the @type field set to "Component".

For instance, a car may have a component representing its engine, defined as follows:

{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Car;1",
"@type": "Interface",
"displayName": "Car",
"contents": [
{
"@type": "Component",
"name": "engine",
"schema": "dtmi:com:example:Engine;1"
}
]
}

DTDL Best Practices

  • Versioning: When defining your DTDL models, it's important to consider versioning. Models are immutable, meaning once published, they cannot be changed. However, you can create a new version of a model by incrementing the version number in its ID.

  • Reuse: Make use of components to factor out common parts of your models. This not only makes your models easier to manage, but it also promotes reuse across your solution.

  • Relationships: Use relationships to express how your digital twins are connected. This can provide additional context for your solution and can enhance analytics and insights.

We hope this training guide provides a solid understanding of DTDL. Remember, the best way to learn is by doing, so consider putting these concepts into practice with your own DTDL models. Happy modeling!