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!

Contents