Merge pull request #232615 from dominicbetts/developer-dtdl-updates

IoT Developer: DTDL updates

Author: v-regandowner

articles/iot-develop/concepts-architecture.md

@@ -27,7 +27,7 @@ The following diagram shows the key elements of an IoT Plug and Play solution:
 
 ## Model repository
 
-The [model repository](./concepts-model-repository.md) is a store for model and interface definitions. You define models and interfaces using the [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md).
+The [model repository](./concepts-model-repository.md) is a store for model and interface definitions. You define models and interfaces using the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md).
 
 The web UI lets you manage the models and interfaces.
 

articles/iot-develop/concepts-convention.md

@@ -15,7 +15,7 @@ IoT Plug and Play devices should follow a set of conventions when they exchange
 
 A device can include [modules](../iot-hub/iot-hub-devguide-module-twins.md), or be implemented in an [IoT Edge module](../iot-edge/about-iot-edge.md) hosted by the IoT Edge runtime.
 
-You describe the telemetry, properties, and commands that an IoT Plug and Play device implements with a [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) _model_. There are two types of model referred to in this article:
+You describe the telemetry, properties, and commands that an IoT Plug and Play device implements with a [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) _model_. There are two types of model referred to in this article:
 
 - **No component** - A model with no components. The model declares telemetry, properties, and commands as top-level elements in the contents section of the main interface. In the Azure IoT explorer tool, this model appears as a single _default component_.
 - **Multiple components** - A model composed of two or more interfaces. A main interface, which appears as the _default component_, with telemetry, properties, and commands. One or more interfaces declared as components with more telemetry, properties, and commands.
@@ -48,7 +48,7 @@ A read-only property is set by the device and reported to the back-end applicati
 
 ### Sample no component read-only property
 
-A device or module can send any valid JSON that follows the DTDL V2 rules.
+A device or module can send any valid JSON that follows the DTDL rules.
 
 DTDL that defines a property on an interface:
 
@@ -282,7 +282,7 @@ The device responds with an acknowledgment that looks like the following example
 
 When a device receives multiple desired properties in a single payload, it can send the reported property responses across multiple payloads or combine the responses into a single payload.
 
-A device or module can send any valid JSON that follows the DTDL V2 rules.
+A device or module can send any valid JSON that follows the DTDL rules.
 
 DTDL:
 
@@ -452,7 +452,7 @@ On a device or module, multiple component interfaces use command names with the
 
 Now that you've learned about IoT Plug and Play conventions, here are some other resources:
 
-- [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md)
+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)
 - [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)
 - [IoT REST API](/rest/api/iothub/device)
 - [IoT Plug and Play modeling guide](concepts-modeling-guide.md)

articles/iot-develop/concepts-developer-guide-device.md

@@ -39,7 +39,7 @@ This guide describes the basic steps required to create a device, module, or IoT
 To build an IoT Plug and Play device, module, or IoT Edge module, follow these steps:
 
 1. Ensure your device is using either the MQTT or MQTT over WebSockets protocol to connect to Azure IoT Hub.
-1. Create a [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) model to describe your device. To learn more, see [Understand components in IoT Plug and Play models](concepts-modeling-guide.md).
+1. Create a [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) model to describe your device. To learn more, see [Understand components in IoT Plug and Play models](concepts-modeling-guide.md).
 1. Update your device or module to announce the `model-id` as part of the device connection.
 1. Implement telemetry, properties, and commands that follow the [IoT Plug and Play conventions](concepts-convention.md)
 
@@ -85,7 +85,7 @@ Once your device or module implementation is ready, use the [Azure IoT explorer]
 
 Now that you've learned about IoT Plug and Play device development, here are some other resources:
 
-- [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md)
+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)
 - [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)
 - [IoT REST API](/rest/api/iothub/device)
 - [Understand components in IoT Plug and Play models](concepts-modeling-guide.md)

articles/iot-develop/concepts-developer-guide-service.md

@@ -69,7 +69,7 @@ The service SDKs let you access device information from a solution component suc
 
 Now that you've learned about device modeling, here are some more resources:
 
-- [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md)
+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)
 - [C device SDK](https://github.com/Azure/azure-iot-sdk-c/)
 - [IoT REST API](/rest/api/iothub/device)
 - [IoT Plug and Play modeling guide](concepts-modeling-guide.md)

articles/iot-develop/concepts-digital-twin.md

@@ -3,17 +3,15 @@ title: Understand IoT Plug and Play digital twins
 description: Understand how IoT Plug and Play uses digital twins
 author: dominicbetts
 ms.author: dobett
-ms.date: 11/17/2022
+ms.date: 04/25/2023
 ms.topic: conceptual
 ms.service: iot-develop
 services: iot-develop
 ---
 
 # Understand IoT Plug and Play digital twins
 
-An IoT Plug and Play device implements a model described by the [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) schema. A model describes the set of components, properties, commands, and telemetry messages that a particular device can have.
-
-IoT Plug and Play uses DTDL version 2. For more information about this version, see the [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) specification on GitHub.
+An IoT Plug and Play device implements a model described by the [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) schema. A model describes the set of components, properties, commands, and telemetry messages that a particular device can have.
 
 > [!NOTE]
 > DTDL isn't exclusive to IoT Plug and Play. Other IoT services, such as [Azure Digital Twins](../digital-twins/overview.md), use it to represent entire environments such as buildings and energy networks.

articles/iot-develop/concepts-model-parser.md

@@ -3,7 +3,7 @@ title: Understand the Azure Digital Twins model parser | Microsoft Docs
 description: As a developer, learn how to use the DTDL parser to validate models.
 author: rido-min
 ms.author: rmpablos
-ms.date: 11/17/2022
+ms.date: 04/25/2023
 ms.topic: conceptual
 ms.custom: mvc
 ms.service: iot-develop
@@ -13,75 +13,35 @@ services: iot-develop
 
 # Understand the digital twins model parser
 
-The Digital Twins Definition Language (DTDL) is described in the [DTDL Specification V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md). Users can use the _Digital Twins Model Parser_ NuGet package to validate and query a DTDL model. The DTDL model may be defined in multiple files.
+The Digital Twins Definition Language (DTDL) is described in the [DTDL Specification](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md). Users can use the _Digital Twins Model Parser_ NuGet package to validate and query a DTDL model. The DTDL model may be defined in multiple files.
 
 ## Install the DTDL model parser
 
-The parser is available in NuGet.org with the ID: [Microsoft.Azure.DigitalTwins.Parser](https://www.nuget.org/packages/Microsoft.Azure.DigitalTwins.Parser). To install the parser, use any compatible NuGet package manager such as the one in Visual Studio or in the `dotnet` CLI.
+The parser is available in NuGet.org with the ID: [DTDLParser](https://www.nuget.org/packages/DTDLParser). To install the parser, use any compatible NuGet package manager such as the one in Visual Studio or in the `dotnet` CLI.
 
 ```bash
-dotnet add package Microsoft.Azure.DigitalTwins.Parser
+dotnet add package DTDLParser
 ```
 
 > [!NOTE]
-> At the time of writing, the parser version is `3.12.7`.
-
-## Use the parser to validate a model
-
-A model can be composed of one or more interfaces described in JSON files. You can use the parser to load all the files in a given folder and then validate all the files as a whole, including any references between the files:
-
-1. Create an `IEnumerable<string>` with a list of all model contents:
-
-    ```csharp
-    using System.IO;
-
-    string folder = @"c:\myModels\";
-    string filespec = "*.json";
-
-    List<string> modelJson = new List<string>();
-    foreach (string filename in Directory.GetFiles(folder, filespec))
-    {
-        using StreamReader modelReader = new StreamReader(filename);
-        modelJson.Add(modelReader.ReadToEnd());
-    }
-    ```
-
-1. Instantiate the `ModelParser` and call `ParseAsync`:
-
-    ```csharp
-    using Microsoft.Azure.DigitalTwins.Parser;
-
-    ModelParser modelParser = new ModelParser();
-    IReadOnlyDictionary<Dtmi, DTEntityInfo> parseResult = await modelParser.ParseAsync(modelJson);
-    ```
-
-1. Check for validation errors. If the parser finds any errors, it throws an `ParsingException` with a list of errors:
-
-    ```csharp
-    try
-    {
-        IReadOnlyDictionary<Dtmi, DTEntityInfo> parseResult = await modelParser.ParseAsync(modelJson);
-    }
-    catch (ParsingException pex)
-    {
-        Console.WriteLine(pex.Message);
-        foreach (var err in pex.Errors)
-        {
-            Console.WriteLine(err.PrimaryID);
-            Console.WriteLine(err.Message);
-        }
-    }
-    ```
-
-1. Inspect the `Model`. If the validation succeeds, you can use the model parser API to inspect the model. The following code snippet shows how to iterate over all the models parsed and display the existing properties:
-
-    ```csharp
-    foreach (var item in parseResult)
-    {
-        Console.WriteLine($"\t{item.Key}");
-        Console.WriteLine($"\t{item.Value.DisplayName?.Values.FirstOrDefault()}");
-    }
-    ```
+> At the time of writing, the parser version is `1.0.52`.
+
+## Use the parser to validate and inspect a model
+
+The DTDLParser is a library that you can use to:
+
+- Determine whether one or more models are valid according to the language v2 or v3 specifications.
+- Identify specific modeling errors.
+- Inspect model contents.
+
+A model can be composed of one or more interfaces described in JSON files. You can use the parser to load all the files that define a model and then validate all the files as a whole, including any references between the files.
+
+The [DTDLParser for .NET](https://github.com/digitaltwinconsortium/DTDLParser) repository includes the following samples that illustrate the use of the parser:
+
+- [DTDLParserResolveSample](https://github.com/digitaltwinconsortium/DTDLParser/blob/main/samples/DTDLParserResolveSample) shows how to parse an interface with external references, resolve the dependencies using the `Azure.IoT.ModelsRepository` client.
+- [DTDLParserJSInteropSample](https://github.com/digitaltwinconsortium/DTDLParser/blob/main/samples/DTDLParserJSInteropSample) shows how to use the DTDL Parser from JavaScript running in the browser, using .NET JSInterop.
+
+The DTDLParser for .NET repository also includes a [collection of tutorials](https://github.com/digitaltwinconsortium/DTDLParser/blob/main/tutorials/README.md) that show you how to use the parser to validate and inspect models.
 
 ## Next steps
 

articles/iot-develop/concepts-model-repository.md

@@ -11,7 +11,7 @@ services: iot-develop
 
 # Device models repository
 
-The device models repository (DMR) enables device builders to manage and share IoT Plug and Play device models. The device models are JSON LD documents defined using the [Digital Twins Modeling Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md).
+The device models repository (DMR) enables device builders to manage and share IoT Plug and Play device models. The device models are JSON LD documents defined using the [Digital Twins Modeling Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md).
 
 The DMR defines a pattern to store DTDL interfaces in a folder structure based on the device twin model identifier (DTMI). You can locate an interface in the DMR by converting the DTMI to a relative path. For example, the `dtmi:com:example:Thermostat;1` DTMI translates to `/dtmi/com/example/thermostat-1.json` and can be obtained from the public base URL `devicemodels.azure.com` at the URL [https://devicemodels.azure.com/dtmi/com/example/thermostat-1.json](https://devicemodels.azure.com/dtmi/com/example/thermostat-1.json).
 

articles/iot-develop/concepts-modeling-guide.md

@@ -22,7 +22,7 @@ At the core of IoT Plug and Play, is a device _model_ that describes a device's
 
 To learn more about how IoT Plug and Play uses device models, see [IoT Plug and Play device developer guide](concepts-developer-guide-device.md) and [IoT Plug and Play service developer guide](concepts-developer-guide-service.md).
 
-To define a model, you use the Digital Twins Definition Language (DTDL) V2. DTDL uses a JSON variant called [JSON-LD](https://json-ld.org/). The following snippet shows the model for a thermostat device that:
+To define a model, you use the Digital Twins Definition Language (DTDL). DTDL uses a JSON variant called [JSON-LD](https://json-ld.org/). The following snippet shows the model for a thermostat device that:
 
 - Has a unique model ID: `dtmi:com:example:Thermostat;1`.
 - Sends temperature telemetry.
@@ -126,7 +126,7 @@ The thermostat model has a single interface. Later examples in this article show
 
 This article describes how to design and author your own models and covers topics such as data types, model structure, and tools.
 
-To learn more, see the [Digital Twins Definition Language V2](https://github.com/Azure/opendigitaltwins-dtdl) specification.
+To learn more, see the [Digital Twins Definition Language](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) specification.
 
 ## Model structure
 
@@ -642,7 +642,7 @@ There's a DTDL authoring extension for VS Code.
 
 To install the DTDL extension for VS Code, go to [DTDL editor for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-dtdl). You can also search for **DTDL** in the **Extensions** view in VS Code.
 
-When you've installed the extension, use it to help you author DTDL model files in VS code:
+When you've installed the extension, use it to help you author DTDL model files in VS Code:
 
 - The extension provides syntax validation in DTDL model files, highlighting errors as shown on the following screenshot:
 
@@ -690,5 +690,5 @@ The following list summarizes some key constraints and limits on models:
 
 Now that you've learned about device modeling, here are some more resources:
 
-- [Digital Twins Definition Language V2 (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl)
+- [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md)
 - [Model repositories](./concepts-model-repository.md)

articles/iot-develop/howto-convert-to-pnp.md

@@ -170,7 +170,7 @@ In summary, the sample implements the following capabilities:
 
 ## Design a model
 
-Every IoT Plug and Play device has a model that describes the features and capabilities of the device. The model uses the [Digital Twin Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) to describe the device capabilities.
+Every IoT Plug and Play device has a model that describes the features and capabilities of the device. The model uses the [Digital Twin Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md) to describe the device capabilities.
 
 For a simple model that maps the existing capabilities of your device, use the *Telemetry*, *Property*, and *Command* DTDL elements.
 

articles/iot-develop/howto-manage-digital-twin.md

@@ -15,7 +15,7 @@ IoT Plug and Play supports **Get digital twin** and **Update digital twin** oper
 
 ## Update a digital twin
 
-An IoT Plug and Play device implements a model described by [Digital Twins Definition Language (DTDL) V2](https://github.com/Azure/opendigitaltwins-dtdl). Solution developers can use the **Update Digital Twin API** to update the state of component and the properties of the digital twin.
+An IoT Plug and Play device implements a model described by [Digital Twins Definition Language (DTDL)](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/README.md). Solution developers can use the **Update Digital Twin API** to update the state of component and the properties of the digital twin.
 
 The IoT Plug and Play device used as an example in this article implements the [Temperature Controller model](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json) with [Thermostat](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json) components.
 
@@ -150,25 +150,25 @@ The following JSON Patch sample shows how to add, replace, or remove a property
 
 **Name**
 
-The name of a component or property must be valid DTDL V2 name.
+The name of a component or property must be valid DTDL name.
 
 Allowed characters are a-z, A-Z, 0-9 (not as the first character), and underscore (not as the first or last character).
 
 A name can be 1-64 characters long.
 
 **Property value**
 
-The value must be a valid [DTDL V2 Property](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md#property).
+The value must be a valid [DTDL Property](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v3/DTDL.v3.md#property).
 
-All primitive types are supported. Within complex types, enums, maps, and objects are supported. To learn more, see [DTDL V2 Schemas](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md#schema).
+All primitive types are supported. Within complex types, enums, maps, and objects are supported. To learn more, see [DTDL Schemas](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v3/DTDL.v3.md#schema).
 
 Properties don't support array or any complex schema with an array.
 
 A maximum depth of a five levels is supported for a complex object.
 
-All field names within complex object should be valid DTDL V2 names.
+All field names within complex object should be valid DTDL names.
 
-All map keys should be valid DTDL V2 names.
+All map keys should be valid DTDL names.
 
 ## Troubleshoot update digital twin API errors