Edit

Device models repository

  • Article

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).

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.

Index, expanded and metadata

The DMR conventions include other artifacts for simplifying consumption of hosted models. These features are optional for custom or private repositories.

Public device models repository

Microsoft hosts a public DMR with these characteristics:

  • Curated models. Microsoft reviews and approves all available interfaces using a GitHub pull request (PR) validation workflow.
  • Immutability. After it's published, an interface can't be updated.
  • Hyper-scale. Microsoft provides the required infrastructure to create a secure, scalable endpoint where you can publish and consume device models.

Custom device models repository

Use the same DMR pattern to create a custom DMR in any storage medium, such as local file system or custom HTTP web server. You can retrieve device models from the custom DMR in the same way as from the public DMR by changing the base URL used to access the DMR.

Note

Microsoft provides tools to validate device models in the public DMR. You can reuse these tools in custom repositories.

Public models

The public device models stored in the DMR are available for everyone to consume and integrate in their applications. Public device models enable an open eco-system for device builders and solution developers to share and reuse their IoT Plug and Play device models.

See the Publish a model section to learn how to publish a model in the DMR and make it public.

Users can browse, search, and view public interfaces from the official GitHub repository.

All interfaces in the dtmi folders are also available from the public endpoint https://devicemodels.azure.com

Resolve models

To programmatically access these interfaces, you can use the ModelsRepositoryClient available in the NuGet package Azure.IoT.ModelsRepository. This client is configured by default to query the public DMR available at devicemodels.azure.com and can be configured to any custom repository.

The client accepts a DTMI as input and returns a dictionary with all required interfaces:

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

The expected output displays the DTMI of the three interfaces found in the dependency chain:

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

The ModelsRepositoryClient can be configured to query a custom DMR -available through http(s)- and to specify the dependency resolution by using the ModelDependencyResolution flag:

  • Disabled. Returns the specified interface only, without any dependency.
  • Enabled. Returns all the interfaces in the dependency chain

Tip

Custom repositories might not expose the .expanded.json file. When this file isn't available, the client will fallback to process each dependency locally.

The following sample code shows how to initialize the ModelsRepositoryClient by using a custom repository base URL, in this case using the raw URLs from the GitHub API without using the expanded form since it's not available in the raw endpoint. The AzureEventSourceListener is initialized to inspect the HTTP request performed by the client:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

There are more samples available in the Azure SDK GitHub repository: Azure.Iot.ModelsRepository/samples.

Publish a model

Important

You must have a GitHub account to be able to submit models to the public DMR.

  1. Fork the public GitHub repository: https://github.com/Azure/iot-plugandplay-models.
  2. Clone the forked repository. Optionally create a new branch to keep your changes isolated from the main branch.
  3. Add the new interfaces to the dtmi folder using the folder/filename convention. To learn more, see Import a Model to the dtmi/ folder.
  4. Validate the models locally using the dmr-client tool. To learn more, see validate models.
  5. Commit the changes locally and push to your fork.
  6. From your fork, create a pull request that targets the main branch. See Creating an issue or pull request docs.
  7. Review the pull request requirements.

The pull request triggers a set of GitHub Actions that validate the submitted interfaces, and makes sure your pull request satisfies all the requirements.

Microsoft will respond to a pull request with all checks in three business days.

dmr-client tools

The tools used to validate the models during the PR checks can also be used to add and validate the DTDL interfaces locally.

Note

This tool requires the .NET SDK version 3.1 or greater.

Install dmr-client

dotnet tool install --global Microsoft.IoT.ModelsRepository.CommandLine --version 1.0.0-beta.6

Import a model to the dtmi/ folder

If you have your model already stored in json files, you can use the dmr-client import command to add them to the dtmi/ folder with the correct file names:

# from the local repo root folder
dmr-client import --model-file "MyThermostat.json"

Tip

You can use the --local-repo argument to specify the local repository root folder.

Validate models

You can validate your models with the dmr-client validate command:

dmr-client validate --model-file ./my/model/file.json

Note

The validation uses the latest DTDL parser version to ensure all the interfaces are compatible with the DTDL language specification.

To validate external dependencies, they must exist in the local repository. To validate models, use the --repo option to specify a local or remote folder to resolve dependencies:

# from the repo root folder
dmr-client validate --model-file ./my/model/file.json --repo .

Strict validation

The DMR includes extra requirements, use the strict flag to validate your model against them:

dmr-client validate --model-file ./my/model/file.json --repo . --strict true

Check the console output for any error messages.

Export models

Models can be exported from a given repository (local or remote) to a single file using a JSON Array:

dmr-client export --dtmi "dtmi:com:example:TemperatureController;1" -o TemperatureController.expanded.json

Create the repository index

The DMR can include an index with a list of all the DTMIs available at the time of publishing. This file can be split in to multiple files as described in the DMR Tools Wiki.

To generate the index in a custom or private DMR, use the index command:

dmr-client index -r . -o index.json

Note

The public DMR is configured to provide an updated index available at: https://devicemodels.azure.com/index.json

Create expanded files

Expanded files can be generated using the command:

dmr-client expand -r .

Next steps

The suggested next step is to review the IoT Plug and Play architecture.