Digital Twins Definition Language (DTDL) updates

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Community Hub.

DTDL, a language to define digital twins, is being updated to version 3, along with a new open-source parser that supports v2 and v3. In this article we are explaining the new features available in v3, such as new core language updates, new feature extensions, migrating from v2 to v3 as well the new DTDL parser for .NET.

If you are new to DTDL, check out the modeling guide for Azure Digital Twins and IoT Plug and Play to learn what it's designed and used for.

Feature Extensions

DTDL v3 has been designed to allow adding language features without requiring a new major language version. Instead, we can add extensions that can be versioned independently from the core language, allowing different services to choose which extensions they support. Feature extensions will make it easier for DTDL-enabled services to adopt different features over time. The official DTDL parser will be updated when new extensions are released.

Core Language Updates

Before describing the initial set of extensions, let us dive into new core language features in DTDL v3:

Arrays in Properties. Now you can define Arrays in DTDL properties, this is one of the most requested features we have in v2. Consequently, now we can use geospatial schemas in a Property.
Size Limits. The individual limits on set sizes of interface contents, relationship properties, enumValues and object fields have been replaced by a limit on the total count of elements in the contents hierarchy. Interface extends limits have been replaced by a limit on the total count of interfaces in the extends hierarchy to a total of 100,000 elements.
Element names, and displayNames sizes have been increased from 64 to 512 characters.

Digital Twin Model Identifiers now support a form with no version suffix, and a form with a two part (major.minor) version suffix
Semantic Types are no longer part of the native DTDL language, use of Semantic Types requires the QuantiativeTypes feature extension

Migrating from v2 to v3

In most cases updating the @context from dtmi:dtdl:context;2 to dtmi:dtdl:context;3 will be sufficient, however if the v2 model was using any semantic type, eg @type : [“Telemetry”, “Temperature”] the context identifier must register the quantitiveTypes extension.

{ "@context": [ "dtmi:dtdl:context;2" ], "@id": "dtmi:samples:basic;1", "@type": "Interface", "contents": [ { "@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "double", "unit": "kelvin" }, { "@type": "Property", "name": "interval", "schema": "integer" } ] }

{ "@context": [ "dtmi:dtdl:context;3" "dtmi:dtdl:extension:quantitativeTypes;1" ], "@id": "dtmi:samples:basic;1", "@type": "Interface", "contents": [ { "@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "double", "unit": "kelvin" }, { "@type": "Property", "name": "interval", "schema": "integer" } ] }

New Feature Extensions

With semantic types defined in this new extension, now we can update the supported semantic types by updating only the extension, without affecting the core language. Additionally those semantic types are applicable to Telemetry, Property, CommandRequest, CommandResponse, Field and MapValue.

{ "@context": [ "dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1" ], "@id": "dtmi:samplesv3:example;1", "@type": "Interface", "contents": [ { "@type": [ "Telemetry", "Temperature" ], "name": "temp", "schema": "double", "unit": "kelvin" }, { "@type": "Command", "name": "reboot", "request": { "@type": [ "CommandRequest", "TimeSpan" ], "name": "delay", "schema": "integer", "unit": "second" } } ] }

We added more quantitative types and units in response to customer feedback. The complete list can be found in the extension documentation: DTDL.quantitativeTypes.v1.md

Annotation is a DTDL language feature that enables a model to add custom metadata to a Property or a Telemetry. If a service supports the Annotation extension, it recognizes and understands the ValueAnnotation adjunct type and its annotates property if the Annotation context is specified.

{ "@context": [ "dtmi:dtdl:context;3", "dtmi:dtdl:extension:quantitativeTypes;1", "dtmi:dtdl:extension:annotation;1" ], "@id": "dtmi:samplesv3:annotationSample;1", "@type": "Interface", "contents": [ { "@type": [ "Telemetry", "Temperature" ], "name": "currentTemp", "schema": "double", "unit": "degreeFahrenheit" }, { "@type": [ "Telemetry", "ValueAnnotation" ], "name": "currentTempAccuracy", "annotates": "currentTemp", "schema": "double" } ] }

Message payload will look like:

{ "currentTemp": 62.6, "currentTempAccuracy": 4.0 }

Streaming is a DTDL language feature for indicating that a Property may be stored with reduced durability guarantees, thereby lowering storage cost and increasing data ingestion. If a service supports the Streaming extension, it recognizes and understands the Streaming adjunct type if the Streaming context is specified.

{ "@context": [ "dtmi:dtdl:context;3", "dtmi:dtdl:extension:streaming;1" ], "@id":"dtmi:samplesv3:streamingSample;1", "@type":"Interface", "displayName":"GasTurbine", "contents":[ { "@type":"Property", "name":"serialNumber", "schema":"string" }, { "@type":["Property", "Streaming"], "name":"flowRate", "schema":"double" } ] }

Historization is a DTDL language feature for indicating that the historical sequence of values of a Property or a Telemetry should be recorded, as should the times at which the Property or Telemetry value changes. If a service supports the Historization extension, it recognizes and understands the Historized adjunct type if the Historization context is specified.

{ "@context": [ "dtmi:dtdl:context;3", "dtmi:dtdl:extension:historization;1" ], "@id": "dtmi:samplesv3:historizationSample;1", "@type": "Interface", "contents": [ { "@type": [ "Property", "Historized" ], "name": "setPointTemp", "writable": true, "schema": "double" } ] }

New DTDL Parser for .NET

There is a new DTDL Parser for .NET and now is hosted as open source in GitHub: https://github.com/digitaltwinconsortium/DTDLParser

This repo contains the DTDL language metamodel (aka as digest), and the code generation tools we use to produce most of the parser source code.

There are some breaking changes from the previous DTDL Parser:

New ModelParser constructor accepting the new ParsingOptions.
New Parse and ParseAsync overloads
New namespace to host the DTInfo classes

And some new features like the ParseToJson API to enable integration with JavaScript solutions, don't miss the new JSInterop sample showing how to use the .NET parser from Web Assembly (thanks to .NET 7) and the new tutorials.

The new APIs are documented in https://digitaltwinconsortium.github.io/DTDLParser/api/DTDLParser.html.

This parser is published in NuGet.org as a preview DTDLParser in NuGet, once it’s released as GA we will deprecate the previous parser https://www.nuget.org/packages/Microsoft.Azure.DigitalTwins.Parser

Microsoft further increases contributions to the Digital Twin Consortium open-source initiative.

Microsoft has contributed the latest generation of the Digital Twin Definition Language (DTDL) Parser to the Digital Twin Consortium. This is the 4^th major contribution this year alone and the 6^th overall. Just like Microsoft, the DTC fully understands the importance of open-source reference implementations to accelerate the adoption of digital twin technology. With these contributions, DTC members and the general public can ramp up on digital twin technology quickly and even integrate the reference code into their own products. Both Microsoft and the DTC encourage everyone in the community to participate in this open-source project, by creating issues or improving docs and samples. Contributions can be made by opening GitHub Pull Requests (PRs).

Where can I use DTDL v3

The Azure Digital Twins service is accepting nominations to participate in a private preview to support DTDL v3, and the public preview will be announced very soon. We expect to make DTDL v3 support in ADT GA by this summer.

You can use DTDL v3 today with Azure IoT Hub and Azure IoT Explorer.

The Device Model Repository CLI will be updated to support DTDL V3, we would like to get your feedback to determine if the global device model repository should support v3.

What’s next.

With these updates we expect to be more agile adding new features to the language, producing new parser versions, and updating the DTDL ecosystem, starting with the VSCode DTDL extension.

We’d love to hear from you, how are you using DTDL and what features can be added to the language, the parser or any of the related tools and services, feel free to engage with us in any of the GitHub Repos.