A model is composed by a set of interfaces identified by a unique id in the form of a DTMI.

The model repo stores one interface version per file following the structure defined below.

A DTMI can be translated to a relative path with the following rules:

• Folder name is based on the DTMI
  • Convert to lower case invariant
  • Create a folder structure with a subfolder for each DTMI segment (separated by :)
• File name is the last DTMI segment plus the version number with the .json extension

dtmi:com:example:Thermostat;1 -> dtmi/com/example/thermostat-1.json

Folders or files are associated to CODEOWNERS (see Model-Ownership) to ensure that any future updates are reviewed by the user who initially created the folder.

Note: Once a DTMI is registered with a specific casing all other case variants will be stored under the same folder owned by the same user.

Based on the file/folder rules, only one DTMI can be stored regardless of id casing.

✔️ Valid

dtmi:com:example:Thermostat;1 -> dtmi/com/example/thermostat-1.json
dtmi:com:example:thermostat;2 -> dtmi/com/example/thermostat-2.json

❌ Invalid

dtmi:com:example:Thermostat;1 -> dtmi/com/example/thermostat-1.json
dtmi:com:example:thermostat;1 -> dtmi/com/example/thermostat-1.json

Each IoT Model Repo will be accessible at a URL, where all paths are relative to the location of base repo URL.

For a model repo at https://devicemodels.azure.com the referenced interfaces will be available from:

GET https://devicemodels.azure.com/dtmi/com/example/thermostat-1.json

The same folder structure can be used locally with local file paths

C:\localModelRepo\dtmi\com\example\thermostat-1.json

The model repo must guarantee that all @id included in the interfaces are unique across the repo to avoid collisions when loading different models.

• @id elements from interfaces are guaranteed to be unique by the folder/file convention.
• All other @id elements from schemas, fields, and properties must be under the root DTMI established by the interface.

✔️ Valid

{
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:demo;1",
    "@type": "Interface",
    "contents": [
        {
            "@id": "dtmi:com:demo:name;1",
            "@type" : "Property",
            "name" : "name",
            "schema" : "string"
        }
    ]
  }

❌ Invalid

{
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:demo;1",
    "@type": "Interface",
    "contents": [
        {
            "@id": "dtmi:com:notindemo:name;1",
            "@type" : "Property",
            "name" : "name",
            "schema" : "string"
        }
    ]
  }

Note: During the validation process we will validate all the interfaces under the same folder do not contain duplicated @id elements.

DTDL interfaces can have dependencies to external (in a different file) interfaces for extends and @component schemas only. Any other dependencies are only supported with inline documents.

• The DMR will not accept interfaces with external dependencies that cannot be resolved in the Public DMR.
• There are no hard code limits for dependency depth.

Once the model -with all the interfaces- has been validated and accepted, the DMR will produce an expanded version of each interface with all their dependencies.

The expanded file follows the next rules:

1. Use a JSON array of DTDL documents
2. The root interface MUST be the first element in the Array
3. Each interface MUST appear only once in the array
4. When there are no dependencies, the expanded version will be an Array of one element

Given a dependency graph such as:

A->B->C

Will produce the next 6 files.

A.json
A.expanded.json
B.json
B.expanded.json
C.json
C.expanded.json

Where A.expanded.json will include A, B and C, B.expanded.json includes B and C, and C.expanded.json includes an array of one element with C.