azure/opendigitaltwins-dtdl

Digital Twins Definition Language

Digital Twins Definition Language

The Digital Twins Definition Language (DTDL) is 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, or logical entities that participate in IoT solutions. Using DTDL to describe a digital twin's capabilities enables the IoT solutions to leverage the semantics of the entity.

DTDL is open to the community and Microsoft welcomes collaboration with customers, partners, and the industry. It is based on open W3C standards such as JSON-LD and RDF which allow for easier adoption across services and tooling.

🎯 DTDL Versions

DTDL has evolved over time, resulting in the next versions:

Version	Docs	Notes
v1-preview	dtdlv1.md	Out of support
v2	DTDL.v2.md	Supported in ADT, IoTCentral and IoT Plug and Play
v3	DTDL.v3.md	Supported in ADT and IoT Plug and Play

👉 A Simple Example

The next interface describes a thermostat reporting temperature as degreeCelsius:

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1"
  ],
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature.",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "displayName" : "Temperature",
      "description" : "Temperature in degrees Celsius.",
      "schema": "double",
      "unit": "degreeCelsius"
    }
  ]
}

☁️ Services using DTDL

• Azure Digital Twins
• Azure IoT Plug and Play
• Azure Device Models Repository
• Azure IoT Central

🛠️ Developer Tools for DTDL

• DTDL Parser for .NET
• VSCode DTDL extension
• Azure IoT Explorer

📖 Modeling Guides

• IoT Plug and Play modeling guide
• ADT modeling guide
• DTDL ontologies

opendigitaltwins-dtdl's Issues

Remove additivity constraint from DTDL model versions

Currently, when a new version of a DTDL interface is created (e.g. dtmi:com:example:MyModel;1 --> dtmi:com:example:MyModel;2) there are many constraints on what can change from version to version. Most notably, in almost all cases, nothing can be removed from an existing interface when going from vN to vN+1. In practice, this causes deprecated and unused cruft in interfaces that can never be removed short of starting over with a completely different interface.

This change, to remove the additivity constraint, intends to put control for what changes in an interface from version to version in the hands of the interface author. If the interface author is working closely with the code that implements and/or consumes the interface, then any number of changes may be appropriate. If the interface author is publishing an interface for use across multiple devices or digital twins and/or multiple solutions, compatible changes from version to version may be more appropriate.

Mapping of IoT Plug+Play to W3C Web of Things

It would be interesting to attempt defining a mapping of the DTDL to the W3C Web of Things specifications, which are candidate recommendations and are currently in community review:

• https://www.w3.org/TR/wot-architecture/
• https://www.w3.org/TR/wot-thing-description/

This analysis would help to understand interoperability and could be beneficial for evolution of the DTDL and the Web of Things specifications.

Example for acutal data of type "Map"

When define a "Property" of type "Map", how do we actually assigned / formatted value for this property? Is there any example?

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

Does it look like this:

"modules" : [  
      { "moduleName" : "moduel1", "moduleState" : "on" }, 
      { "moduelName" : "module2", "moduleState" : "off" } 
]

Or looks like this:

"modules" : { 
      "moduel1" : "on",
      "module2" : "off"
}

Codegen v0.6.7 fails to create C code stubs for Schema: Geopoint

This is the content definition that breaks:

    "@id": "urn:tXs:BleReader:location:1",
     "@type": [
       "Telemetry",
       "SemanticType/Location"
     ],
     "displayName": {
       "en": "Location"
     },
     "name": "location",
     "schema": "geopoint"
   },

And this is the error I get from the tool:
[ERROR][PnPCodeGen] Failed to parse interface definition, @id: urn:tXs:BleReader:1, error: Microsoft.Azure.IoT.DigitalTwin.Parser.ModelParserException: Content is not valid

Name=location, Id=http://azureiot.com/v1/classes/geopoint, Description=Schema not found

Unit is not defined

Hello the data type Unit is not defined.

There are some exemples here and there but no specification.
Please provide this.

Thanks a lot.

Value of minMultiplicity

Value of minMultiplicity can only be set as 0 during public preview. Is there a plan to allow it be set as other number than 0 after GA since there is an example showing it can be set as 1?

Update documentation to say max fields in Object is 30

The maximum number of fields allowed in an Object is 30. The documentation should say this.

Add documentation for point, etc. schemas supported for telemetry

DTDL v2 supports point, etc. (the GeoJSON geometry types) as schemas for telemetry. The documentation should be updated to include this with same examples.

Update DTDL documentation to include JSON-LD details

Every DTDL document is a JSON-LD document. The language spec alludes to this but does not contain information about how the terms used in the documentation map to JSON-LD (such as how the term "Interface" maps to a JSON-LD IRI). The suggestion is to add a section that focuses on DTDL and JSON-LD for readers interested in those details.

Incorrect example for "Enum"

In following example, "enumValue" should be "value" based on "EnumValue" schema:
{
"@type": "Telemetry",
"name": "state",
"schema": {
"@type": "Enum",
"enumValues": [
{
"name": "offline",
"displayName": "Offline",
"enumValue": 1
},
{
"name": "online",
"displayName": "Online",
"enumValue": 2
}
]
}
}

Reach Out To Other Open Standards

This new data modeling language is interesting and I can see potential. However, I have to wonder would it be better to reach out to other open standards groups instead of reinventing the wheel. I'm sure there are many in the wild, but I sort of like the following example.

There is a BACnet (Building Automation and Control Networks) abstract model now released/published as Annex Y. Here is a link to early draft.

Understanding this is within the umbrella of BACnet (which has to do much about IoT), but you can actually use the model to describe almost anything (not just specific to BACnet) including devices, objects, people, buildings, protocols, etc.. In addition, the specification generally explains the modeling language and includes examples of how to format in XML and JSON.

Just curious. Keep up the good work and I look forward to future releases.

Clarify versioning rules around enums

My understanding is that once I define (e.g.) Enum Color {Red, Blue, Green} and publish the interface, then I can NEVER add a Yellow object.

This also flows from https://github.com/Azure/IoTPlugandPlay/tree/master/DTDL#enum describing the enumValues as immutable.

I think it would still be very useful in https://github.com/Azure/IoTPlugandPlay/tree/master/DTDL#enum and anywhere else discussing enums to explicitly call out this behavior. This probably makes sense for a modeling language that has versions, but devs coming from a language like C where enums can always be expanded need to be aware of DTDL behavior.

The links to DTMI in the DTDL v2 language spec doc do not work

In the DTDL v2 doc, the links to DTMIs in the tables of properties do not work.

[Query] DeviceConnected/DeviceDisconnected events

Query/Question
According to this page, it is possible to use Message Routing to receive Device Connect and Disconnected events and route them to the internal Event Hub

In practice, we receive DeviceCreated events, but do not receive DeviceConnected or DeviceDisconnected events.

We tried creating Routes for all available Data Sources, to no avail:

I can watch the DeviceTwin connectedState change from Connected to Disconnected and vice-versa, but we do not receive any events when this happens.

My hypothesis is that this particular functionality (ability to receive lifecycle events on the built-in eventhub) is in some sort of public preview and needs to be enabled by some unpublished mechanism.

The information about this is inconsistent and sparse.

There is this Stack Overflow post from 2018 suggesting that this is not a supported feature of the IoT Hub.

But then there is this blog post from March 2020 suggesting it is a supported feature:

In addition to telemetry data, routes can be created for other events such as Device Twin changes, Device Lifecycle events and Digital Twin changes (currently in public preview). If you create a route with the data source set to one of these other events, IoT Hub will send messages to the appropriate endpoint for that event (Device Twin, Digital Twin, Device Lifecycle).

@briancr-ms @ridomin

Description of Unit data type is missing

Remove "bytes" from list of DTDL primitive schemas

DTDL does not support a "bytes" primitive schema. This should be removed from the list of primitive schemas.

DTDL-Generalize messages with message types and related schemas

Hi,

Is there any plan to generalize message types and replace the telemetry type by a generic message structure with, for instance:

• messageType (ex: telemetry, error, system, etc)
• messageSchema
• messageSchemaVersion
  and allowing a device (or module) to send different types of messages.

Unless I have misunderstood something, this is not possible today.
I have been confronted with this need in different projects and it is actually quite useful.

How to handle commands with multiple arguments?

My preference for a command with multiple arguments is just to have them as a top-level object in the JSON. Let's say that I have a command named "configuration-set-boolean" which should get 2 arguments - the name of the configuration to set and the new value for the given configuration. In such scenario the IoTHub device just gets a following payload:

{
    "name": "feature-5-enable",
    "value": true
}

This works perfectly fine via direct communication using Azure's portal or when executing direct method directly from Visual Studio Code.

However - in my understanding - it is impossible to describe such thing in DTDL, as the specs seems to suggest that command request (as well as the response) can have only ONE argument which has to be named. It seems logical to use an Object schema type in that case - then the multiple arguments are just fields of the object. However to actually describe such a thing in DTDL it seems that the payload must no longer be "flat", but it actually has to contain a named object like this:

{
    "arguments": {
        "name": "feature-5-enable",
        "value": true
    }
}

A description for such a thing would then have to look more-or-less like this:

{
          "@type": "Command",
          "name": "configuration-set-boolean",
          "commandType": "asynchronous",
          "request": {
            "name": "arguments",
            "schema": {
              "@type": "Object",
              "fields": [
                {
                  "name": "name",
                  "schema": "string"
                },
                {
                  "name": "value",
                  "schema": "boolean"
                }
              ]
            }
          }
        },

Having this "arguments":{...} wrapper is completely pointless from my perspective and it's just a waste of bandwidth (the device uses an LTE modem) and memory (it's just an ARM Cortex-M microcontroller).

Is this really the case? Maybe this should be handled some other way (e.g. maybe "request" can actually be an array with multiple elements, each corresponding to one argument)? Maybe the specs could be changed somehow to allow a scenario of multiple arguments?

C# NuGet Package

Is there a C# NuGet package in the works for this modeling language?

Question regarding telemetry types

Hi and thanks for the awesome documentation!

I have one question regarding the DTDL documentation where it is saying that the telemetry @type should be Telemetry. But then when I read the samples I see a telemetry written as:

"@type": [
        "Telemetry",
        "SemanticType/Temperature"
      ],

I thought the type had to be the string Telemetry, but it seems that it is more capable than that. Is there any documentation regarding the Telemetry metamodel class?

Common Data Model and Open Data Initiative

I originally added the following in issue #10, but feel there should be more detailed discussions/thoughts around the topic as DTDL & CDM could fit very nicely with each other.

Another area to see how it could fit is the Open Data Initiative and Common Data Model that Microsoft is driving.

While I briefly looked at CDM, it seems like you could make standard entities for the telemetry, interfaces, commands and such based on the CDM standard instead. That way the data could be used with the same tooling, APIs, apps, services and systems that already work with CDM.

Any thoughts on how DTDL could be based on the CDM and eventual APIs/SDKs?

Is it possible to specify if data is sent together across interfaces

Does/will the standard allow us specify whether data is sent together across interfaces?
Such as if we have two interfaces for a device, a conveyor interfaces that has a speed telemetry and thermostat interface that has a temperature telemetry. Both of these would be sent together in the same message from the device.

Support within MSFT

Can you describe if/what the support for this effort is within Microsoft?

Array of Enum

Greetings,

I need to define an array of enums.
The only way to do that is to target the array from Telemetry, but I don't want that cuz it's not a stream on data, it should be defined when adding a new twin and it would be best to put it in Property, but Property don't contain definition for Array.

Is there a way to do this?

Thanks for the answer.
Kind regards

Data Types Should Include Optional Limits

Data types should have a way to represent limits like minimum and maximum.

Example:

{
            "@id": "http://MyDevice.com/MySensor/1.0.0",
            "@type": "Interface",
            "displayName": "My Sensor",
            "contents": {
                "@id": "http://MyDevice.com/MySensor/1/input",
                "@type": "Telemetry",
                "description": "Voltage",
                "displayName": "Input Monitor",
                "name": "input",
                "displayUnit": "volts",
                "schema": "double",
                "minimum": "0",
                "maximum": "5.0",
            }
        },

Please better define "Developer" and "Human Readable"

For the comment attribute it says "a Developer comment" and then for description, displayName, 'displayUnit' it says "A localizable name for human display."

Last I checked almost all developers were humans. Can you clarify these descriptions and can you elaborate on how these attribute values are used upstream in IoT Central, IoT Solution Accelertors, etc..

I believe the description, displayName, 'displayUnit' are surfaces to application users in IoT Central where as the comment is not an only meant to aid the DTDL author(s). Who may not be developers but also probably human. ;-)

Thanks!

Define IRI and Link Appropriately

IRI is referenced in the doc but never defined.

It refers to the JSON-LD IRI.

Someplace in the document this should be noted.

Documentation for Component does not say only one level of depth is supported

In DTDL v2, only one level of Component depth is supported (that is, a Component cannot contain a Component). The documentation needs to be updated to reflect this.

Clarify expected values for dateTime, date, and time schemas

The documentation for the expected values for dateTime, date, and time schemas should be clarified.

• Is dateTime the RFC 3339 profile of ISO 8601?
• Can a date have a time in it (e.g. 2020-08-07T01:02:03.1234Z)?
• Can a time have a date in it?

The formal model of DTDL v2?

Hi there, thanks for sharing the great project! It's really awesome that Azure steps up to share what they model for digital twins! I am one of the lead developers of Brick Schema (brickschema.org) for buildings and trying to see if Brick can fit other meta-frameworks like DTDL.

Is there any formal model of DTDLv2 that I can look into? I looked up the folder (https://github.com/Azure/opendigitaltwins-dtdl/tree/master/DTDL/v2) but only a context file is available. I'd be interested in how you model properties and constraints other than the markdown file. I expected to have a JSON-LD (possibly with SHACL Shapes as included in your context file) for example.

How to define Telemetry/State and Telemetry/Event

I created Device Template in IoT Central manually and export.
I see below:

            "@type": [
              "Telemetry",
              "SemanticType/Event"
            ],

But I cannot find information of SemanticType in DTDL.
Is this DTDL format correct?

Are multiple instances of the same interface supported?

Assume a connected Robot

As a builder, I would like to instantiate left arm and right arm.
Are named instances supported?

Assume a connected train
I would like to implement 'N' wagons and address them by index
Are array instances supported?

Assume and an interlocking vault
I would like to implement exterior and interior doors

If these examples are supported, I would love to review best practices and how to represent them on IoT Central dashboards.

Links to existing capability models and interfaces

I am unable to find where the capability models and interfaces defined by Azure, e.g. urn:azureiot:DeviceManagement:DeviceInformation:1. I'm guessing this isn't the only one?

A device manufacturer would be better off implementing interfaces defined by Azure instead of defining their own proprietary, or isn't that your idea regarding your interfaces. I mean, a thermostat is a thermostat is a thermostat 😄

A capability model can only implement one instance of each interface.

What is the rationale for this limitation?
Would it not make sense to allow for reusability of interfaces within a Device Capability Model and across many?
E.g. "robot A" that has two identical arms would use the same interface for both and "robot B" that has one arm identical to "robot A" would use the same interface.

Interface Schema Properties Example

I noticed the table for Interface Schema Property shows required properties for mapKey and mapValue. However, the example below table doesn't include the 2 said properties.

Is there a reason the properties are missing or am I overlooking something? Thx

Device Capability Model exported from IoT Central fails validation in PnPCodeGen

Not sure if it's an issue with IoT Central or an issue with the json schema document, but there seems to be a mismatch.

To reproduce this, we can create a new device template in IoT Central by importing the capability model for the MXChip IoT DevKit. I then exported the capability model and tried to run the "IoT Plug and Play: Generate Device Code Stub" within VS Code.

The error returned is

[ERROR][PnPCodeGen] Invalid content of the capabilityModel, error: Microsoft.Azure.IoT.DigitalTwin.Parser.ModelParserException: Content is not valid

Name=urn:szasDemo:szas_alert_device_v4:1, Id=http://azureiot.com/v1/classes/Interface/contents, Description=Extra Node found.http://azureiot.com/v1/classes/Interface/contents

I managed to fix it by deleting "contents": [], near the bottom of the json document.

Can't create Azure PnP code stub if interface schema contains an array.

Issue Type: Bug

Create an interface schema that contains the array sample shown below.

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

Try to build the code stub for this. The following error is displayed:

[ERROR][PnPCodeGen] Failed to parse interface definition, @id: urn:................:.....................:1, error: Microsoft.Azure.IoT.DigitalTwin.Parser.ModelParserException: Content is not valid

Name=ledState:elementSchema, Id=Name, Description=Name is required
Name=ledState:elementSchema, Description=Schema should be provided

[IoT Plug and Play] generate PnP device code failed.

The same interface schema can be uploaded to Azure successfully.

VS Code version: Code 1.40.2 (f359dd6, 2019-11-25T14:54:45.096Z)
OS version: Windows_NT x64 10.0.18362

No schema/description for data type "Unit"

In "Field" or "Telemetry" schema description, there exists "displayUnit" and "unit". For "displayUnit" is of data type "string", and "unit" is of data type "Unit", there's no description in further to define schema for "Unit". Is it a primitive data type? How does it looks like?

Thanks!

Do the PNP only support C sample currently?

At present, when I use vscode to generate framework code according to PNP file, it seems that only C version can be supported. Is it at the preview stage or has it been so ever since? If only C language is supported, how can I integrate code written in other languages,Is there any official advice?

It's valid an interface without contents?

Given

{
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:m1;1",
    "@type": "Interface"
}

The parser reports it as valid

model size = 1
id=dtmi:com:m1;1 type=DTInterfaceInfo
JSON-LD text:
{
  "@context": [
    "dtmi:dtdl:context;2"
  ],
  "@id": "dtmi:com:m1;1",
  "@type": "Interface"
}
    property=IsPartition type=Boolean value=True (Boolean)
    property=EntityKind type=DTEntityKind value=Interface (DTEntityKind)
    property=Id type=Dtmi value=dtmi:com:m1;1 (Dtmi)
    property=LanguageVersion type=Int32 value=2 (Int32)
    property=IsPartition type=Boolean value=True (Boolean)

But uploading to the model repository fails

/c @briancr-ms

Download All Certified Device JSON Files

It would be nice to have a link to download all provided JSON files from the Certified Device category page. This would be helpful for users to quickly get various types of device capabilities so they can 1) review format to become familiar and 2) use content to test their own parsing/generation APIs/tooling.

Understanding we can currently download individual, getting all docs would be even better 😄

Should @context be string array?

The docs show @context as string, but downloaded device templates have it a string array

Publish your contexts please :)

"@context": "dtmi:dtdl:context;2",

While this valid... its less helpful than a public URL.

I suggest publishing the context via github pages.

Without the context, these JSON-LD cannot be signed or compressed with semantic awareness.

Primitive Schema Should Support More Data Types

The following data types should be added to the Primitive Schema list/table.

Digital twin primitive schema	Description
byte	An unsigned 8-bit integer.
short	A signed 2-byte integer.
uint	An unsigned 4-byte integer.
ulong	An unsigned 8-byte integer.
ushort	An unsigned 2-byte integer.

Example for Major Version Change

We have an example for minor version change. Can we also have one for the major version change? It will help partners to better understand how they should organize/name their IDs.

Unit in complex types

In DTDL v1 every level in a DCM could have a displayUnit property. In DTDL v2 this property is removed. Display units in v2 are derived from the unit property. The unit property can only be present when a semantic type is defined. A semantic type is only valid on telemetry or a property that has a numeric schema (integer, long, float, double). This means that it’s not possible to define a unit for fields of an object. So if you want to have units as part of the definition you cannot use complex types in a DCM (object, map, array).

Is this true?

Correct localization documentation

In DTDL v2, localization for localizable properties (such as displayName and description) are only available inline through JSON-LD "language maps". Update the documentation by removing this line, "Because of the composable nature of JSON-LD graphs, localized strings can be prepared in a separate file and merged with an existing graph."

What about unit conversions?

What if the data that comes in is not the actual data it represents and needs conversion/kalibration? Would it be possible to include this in the plug and play definition?
F.i, "temperature" can be represented in Fahrenheid, Celcius or Kelvin:

        {
            "@type": "Telemetry",
            "name": "temp",
            "displayName": "Measured temp",
            "schema": "double",
            "displayUnit": "F" ? "C" ? "K" ?...
        }

This requires conversion between units.
You could even see data coming in as "voltage", but actually meaning "temperature" or "resistance" or something else. Will simple unit conversion be part of PnP?

Wrong documentation about maxMultiplicity in ver. 2

DTDL v.2 descritpion says that the default value of maxMultiplicity for Relationship is positive infinity, but when uploaded a model to the ADT, I got the following message:

{
   "error":{
      "code":"DTDLParserError",
      "message":"None of the models in this request could be created due to a problem with one or more models: Element dtmi:test:Main:_contents:_consistsOf;1 path minMultiplicity has value 1, which violates maxInclusive constraint value 0 | Element dtmi:test:Part:_contents:_manages;1 path minMultiplicity has value 1, which violates maxInclusive constraint value 0. See model documentation(http://aka.ms/ADTv2Models) for supported format."
   }
}

As I understand that means that the default value of maxMultiplicity is actually 0.

The model that I uploaded consists of two interfaces:

{
    "@id": "dtmi:test:Main;1",
    "@type": "Interface",
    "displayName": "Main",
    "contents": [
        {
            "@type": "Relationship",
            "name": "consistsOf",
            "displayName": "Consists of",
            "minMultiplicity": 1,
            "target": "dtmi:test:Part;1"
        }
    ],
    "@context": "dtmi:dtdl:context;2"
}

and

{
    "@id": "dtmi:test:Part;1",
    "@type": "Interface",
    "displayName": "Part",
    "contents": [
        {
            "@type": "Property",
            "name": "id",
            "displayName": "Id",
            "schema": "string"
        }
    ],
    "@context": "dtmi:dtdl:context;2"
}

Using DTDL other than just devices

DTDL includes the name "Digital Twin". However, it seems like Digital Twin can be considered more than IoT devices and the current schemas appear to be targeting just devices. What is the thinking on defining other types like people, site layouts, etc.?