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).
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.
- Index. All available DTMIs are exposed through an index composed by a sequence of json files, for example: https://devicemodels.azure.com/index.page.2.json
- Expanded. A file with all the dependencies is available for each interface, for example: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
- Metadata. This file exposes key attributes of a repository and is refreshed periodically with the latest published models snapshot. It includes features that a repository implements such as whether the model index or expanded model files are available. You can access the DMR metadata at https://devicemodels.azure.com/metadata.json
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.
Microsoft provides tools to validate device models in the public DMR. You can reuse these tools in custom repositories.
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
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
ModelsRepositoryClient can be configured to query a custom DMR -available through http(s)- and to specify the dependency resolution by using the
- Disabled. Returns the specified interface only, without any dependency.
- Enabled. Returns all the interfaces in the dependency chain
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
You must have a GitHub account to be able to submit models to the public DMR.
- Fork the public GitHub repository: https://github.com/Azure/iot-plugandplay-models.
- Clone the forked repository. Optionally create a new branch to keep your changes isolated from the
- Add the new interfaces to the
dtmifolder using the folder/filename convention. To learn more, see Import a Model to the
- Validate the models locally using the
dmr-clienttool. To learn more, see validate models.
- Commit the changes locally and push to your fork.
- From your fork, create a pull request that targets the
mainbranch. See Creating an issue or pull request docs.
- 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.
The tools used to validate the models during the PR checks can also be used to add and validate the DTDL interfaces locally.
This tool requires the .NET SDK version 3.1 or greater.
dotnet tool install --global Microsoft.IoT.ModelsRepository.CommandLine --version 1.0.0-beta.6
Import a model to the
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"
You can use the
--local-repo argument to specify the local repository root folder.
You can validate your models with the
dmr-client validate command:
dmr-client validate --model-file ./my/model/file.json
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
remote folder to resolve dependencies:
# from the repo root folder dmr-client validate --model-file ./my/model/file.json --repo .
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.
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
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
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 .
The suggested next step is to review the IoT Plug and Play architecture.