Model Index

The IoT models repository index

The global models repository endpoint https://devicemodels.azure.com will publish a model index json file index.json, at the root of the repository https://devicemodels.azure.com/index.json.

The models repository model index implements a similar paging pattern one would consume from a paged REST api. Consuming all pages will provide the client with all the available interfaces in the main branch at the time of publishing.

The object model contained within index.json will have at least three top level properties. models, links, and version.

The models property consists of an object indexed by Digital Twins Model Identifiers (@id) and the value being an object with a number of the respective models key attributes. The attributes will include at least the displayName and description if they exist on the respective model.

The links property is an object which contains at least the self property which is the string value of the current index file name. If index.json contains only self there are no pages to process. Other properties include next and prev. If next is available, there exists another index page for the client to consume in order to accumulate the full set of models available on the repository. If prev is available, the client is able to traverse to the prior index page.

Index pages are always relative to the root index file (index.json). The version property indicates the version of the model index, which will be consistent across index pages.

Index file format example

This is an example of the root index file index.json with no pages.

{
  "links": {
    "self": "index.json"
  },
  "models": {
    "dtmi:com:example:TemperatureController;1": {
      "displayName": "Temperature Controller",
      "description": "Device with two thermostats and remote reboot."
    },
    "dtmi:com:example:Thermostat;1": {
      "displayName": "Thermostat"
    },
    ...
  },
  "version": "1.0"
}

In this example index.json shows there is another page to consume.

{
  "links": {
    "next": "index.page.1.json",
    "self": "index.json"
  },
  "models": {
    "dtmi:com:example:TemperatureController;1": {
      "displayName": "Temperature Controller",
      "description": "Device with two thermostats and remote reboot."
    },
    "dtmi:com:example:Thermostat;1": {
      "displayName": "Thermostat"
    },
    ...
  },
  "version": "1.0"
}

The following is an example of a terminal index page

{
  "links": {
    "prev": "index.json",
    "self": "index.page.1.json"
  },
  "models": {
    "dtmi:com:example:azurertos:gsg;1": {
      "displayName": "Getting Started Guide",
      "description": "Example model for the Azure RTOS Getting Started Guides"
    }
  },
  "version": "1.0"
}

Note: displayName and description are optional. If these attributes are not available in the source model the properties will not exist for that particular model index entry (as opposed to being set to null).

Index expectations

The IoT models repository index pattern is preview and can evolve over time. The intent is to power UX against the models repository.