Digital Twin Definition Language (DTDL) A Complete Guide

In this article, I will describe to you and demonstrate how the Digital Twin Definition Language works. By the end of this article, you’ll be able to create complete digital twin models to represent complex physical objects and visualise the graphical connection of their instances. 


I’ll start by taking you through the basic concepts of DTDL, discuss the metamodel classes used to build a digital model of a physical entity, discuss concepts like semantic data, custom metadata, and historization in DTDL. Then I’ll show you how to build a complete model for a bottling plant and visualise it.

Digital Twin Definition Language (DTDL) Basic Concepts

Fundamentally, a digital twin is a virtual representation of a physical object, process, or system such as a car, an aeroplane, a building, a temperature sensor, a factory or the actual production process inside a factory. 

To help you create digital descriptions of physical assets and systems in a standardised manner, Microsoft developed and open sourced the Digital Twin Definition Language, also known as DTDL. 

DTDL uses a variant of JSON called JSON Linked Data, or JSON-LD.

JSON-LD is powerful because, as it’s name implies, it allows you to link data within JSON objects so as to express semantics inherent in the data.

As a simple example, let’s consider a JSON object describing the pressure sensor of a filling machine. The JSON object would have data that links to another JSON object with data describing the filling machine on which the sensor is installed. Consequently, the JSON object describing the filling machine would also have a link to the bottling line in which the machine is located. 

This allows you to hop from data point to data point, linking related information together, hence “linked data.” Essentially, JSON-LD is not a specific data format, it’s just a JSON serialization of linked data.

Therefore, using JSON-LD, the Digital Twin Definition Language provides a standardized way of not only digitally describing the structure and attributes of physical entities, but also the relationships between them.

Digital Twin Definition Language (DTDL) Metamodel Classes

To enable you to digitally describe the state and behavioural attributes of physical entities, DTDL defines a set of metamodel classes. In simple terms, metamodel classes are like digital templates that describe the structure and rules of how to represent different types of elements associated with a physical entity. 

For example, you can have a template that describes the structure and rules for representing data that doesn’t change such as a serial number, you could also have a template that describes the structure and rules for representing sensor readings such as temperature data, and you could also have a template that describes the structure and rules for representing commands that initiate a behaviour.

So, evidently, when used collectively, such metamodel classes or templates will allow you to comprehensively express a digital representation of a physical entity regardless of its size or complexity.

Now, let us go through the actual metamodel classes provided by DTDL. DTDL is composed of seven primary metamodel classes. The Interface, Property, Telemetry, Command, Component, Relationship, Data Type and classes.

First, we’ll explore each metamodel class, explain its structure, and give examples of how they can be used to digitally represent elements of a real-world entity. Later in the video, I’ll demonstrate how to combine these elements into a complete digital model of a complex object.

DTDL Property Metamodel Class

Let’s start by looking at the Property metamodel class. The Property class enables you to represent elements that don’t change frequently or don’t change at all. 

Using the example of a Filling Machine, Property elements would be its Serial Number, Power Supply Requirements (Kwatts), and Operating Speed (Bottles per hour)

Here’s how you would use JSON-LD to define a serial number Property element for the Filling Machine;


“@type” is used to identify the kind of information being described, in this case a Property element, “name” is the user defined name of the element, and “schema” is the data type of the element. 

DTDL elements can be of standard primitive types like integer, double, string, and boolean e.t.c. However, they can also be of Complex Data Types, we shall discuss more about complex types later in this video.

Moving on, the Property of a digital model can be read only or read and write. For example, a serial number property would be read only, while the operating speed property can also be writen to, to adjust the Operating Speed.

Now, it’s important to mention here that, a Property of a digital model requires a storage mechanism that will retain the data permanently and allow for it to be updated as required.

DTDL Telemetry Metamodel Class

Next, let’s take a look at the Telemetry metamodel class. The Telemetry class enables you to describe the data emitted by a physical entity. This is typically a stream of sensor readings or an occasional alert or information message.

In the case of a Filling Machine, Telemetry elements would be Tank Pressure, Liquid Temperature, Flow Rate, Fill Level and Viscosity of the Liquid.

Here’s how you would use JSON-LD to define a Flow Rate Telemetry element for a Filling Machine.

DTDL Command Metamodel Class

Then we have the Command metamodel class. A Command class enables you to describe a function or operation that can be performed by a physical entity.

Again, using our Filling Machine example, Command elements would be the Start Filling, and Stop Filling operations.

A Command in DTDL can take inputs and return a response.

Here’s an example of a Command element specifying an instruction to start filling at a specified time. The Command returns the scheduled filling time as a response.

DTDL Relationship Metamodel Class

Next, we have the Relationship metamodel class. A Relationship class enables you to describe how physical entities are linked together. 

For example, our bottling line would be related to a Filling Machine in that the Bottling Line contains the Filling Machine. And a Filling Machine would be related to a Capping Machine in that the Filler supplies filled bottles to the Capper. And so on. 

Connecting digital twins via relationships in this manner results in a set of digital twins forming what is called a twin graph. A twin graph sometimes called a knowledge graph represents physical entities in your entire environment while reflecting their interactions.

Here’s a Relationship element for a Bottling line digital model showing that a Bottling Line has a Filler.

You’ll notice that the name is typically used to represent the semantic meaning of the relationship, and the unique identifier of the related target model can be specified. We’ll discuss more about identities of DTDL models later.

However, Relationships can be defined with or without a target. Sometimes, you might want to define a relationship without a specific target, so that the relationship can connect to many different types of twins.

DTDL Component Metamodel Class

Next, we have the Component metamodel class. A Component class enables you to describe models that are components of other models. For example, the Filling machine may have a camera as its component. In that case, you’d want to first define the camera as a standalone model and then reference it when defining a Filling machine.

Now, the question is what criteria do I use to determine a component. If my filling machine has a motor do i treat it as a component as well? The answer is, use a component to describe something that is an integral part of your solution but doesn’t need a separate identity, and doesn’t need to be reflected in the twin graph independently. If you want your motor to have an independent existence in the twin graph, then you need to represent it as a separate digital model and only connect it to the Filling Machined using Relationships.

Here’s an example that shows how a camera would be referenced as a component within a Filling Machine digital model.

Leave a Reply

Your email address will not be published. Required fields are marked *