# azure/opendigitaltwins-dtdl architecture

> Architecture diagram of the GitHub repository azure/opendigitaltwins-dtdl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure/opendigitaltwins-dtdl
- Repository: https://github.com/azure/opendigitaltwins-dtdl

## Overview

This repository publishes the Digital Twins Definition Language (DTDL), a versioned language for describing IoT digital-twin models and interfaces—not a model-processing runtime. The principal workflow is for a model author to describe a twin’s capabilities in DTDL so IoT services and tools can use its semantics. The README identifies JSON-LD and RDF as foundations and names supported versions and services. No source excerpts were available, so relationships beyond those documented in the README are omitted; v3 and v4 are represented only by their listed directories.

Main entry points: [`DTDL/v2/DTDL.v2.md`](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md) (V2 language)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_versions["Language versions"]
  node_v1["V1 preview<br/>[dtdlv1.md]"]
  node_v2["V2 language<br/>[DTDL.v2.md]"]
  node_v3["V3 language"]
  node_v4["V4 language"]
end

subgraph group_v2semantics["V2 semantics"]
  node_v2context["V2 contexts"]
  node_v2metamodel["V2 elements"]
  node_v2shacl["V2 RDF constraints"]
  node_v2spec["V2 conformance cases"]
end

subgraph group_extensions["Extensions"]
  node_iotcentraldoc["IoT Central extension spec"]
  node_iotcentralcontext["IoT Central context"]
  node_iotcentralelements["IoT Central elements"]
  node_iotcentralshacl["IoT Central constraints"]
end

subgraph group_examples["Model examples"]
  node_thermostat["Thermostat model<br/>[Thermostat.json]"]
  node_temperature["Temperature controller"]
end

node_author(("Model author"))
node_iotservices(("IoT services"))
node_jsonldrdf(("JSON-LD and RDF"))

node_author -->|"describes models"| node_v2
node_v2 -->|"enables semantics"| node_iotservices
node_v2 -->|"is based on"| node_jsonldrdf

click node_v1 "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v1-preview/dtdlv1.md"
click node_v2 "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md"
click node_v3 "https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v3"
click node_v4 "https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v4"
click node_v2context "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/context/DTDL.v2.context.json"
click node_v2metamodel "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.ModelElements.json"
click node_v2shacl "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.ModelRDF-SHACL.json"
click node_v2spec "https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v2/spec"
click node_iotcentraldoc "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md"
click node_iotcentralcontext "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/context/DTDL.v2.iotcentral.context.json"
click node_iotcentralelements "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.Elements.json"
click node_iotcentralshacl "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.RDF-SHACL.json"
click node_thermostat "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json"
click node_temperature "https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v1,node_v2,node_v3,node_v4 toneBlue
class node_v2context,node_v2metamodel,node_v2shacl,node_v2spec toneAmber
class node_iotcentraldoc,node_iotcentralcontext,node_iotcentralelements,node_iotcentralshacl toneMint
class node_thermostat,node_temperature toneRose
class node_author,node_iotservices,node_jsonldrdf toneIndigo
```

## Components

### Language versions

- [V1 preview](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v1-preview/dtdlv1.md): `DTDL/v1-preview/dtdlv1.md`
- [V2 language](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.v2.md): `DTDL/v2/DTDL.v2.md`
- [V3 language](https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v3): `DTDL/v3`
- [V4 language](https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v4): `DTDL/v4`

### V2 semantics

- [V2 contexts](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/context/DTDL.v2.context.json): `DTDL/v2/context/DTDL.v2.context.json`
- [V2 elements](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.ModelElements.json): `DTDL/v2/metamodel/DTDL.v2.ModelElements.json`
- [V2 RDF constraints](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.ModelRDF-SHACL.json): `DTDL/v2/metamodel/DTDL.v2.ModelRDF-SHACL.json`
- [V2 conformance cases](https://github.com/azure/opendigitaltwins-dtdl/tree/master/DTDL/v2/spec): `DTDL/v2/spec`

### Extensions

- [IoT Central extension spec](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/DTDL.iotcentral.v2.md): `DTDL/v2/DTDL.iotcentral.v2.md`
- [IoT Central context](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/context/DTDL.v2.iotcentral.context.json): `DTDL/v2/context/DTDL.v2.iotcentral.context.json`
- [IoT Central elements](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.Elements.json): `DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.Elements.json`
- [IoT Central constraints](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.RDF-SHACL.json): `DTDL/v2/metamodel/DTDL.v2.PartnerExtension.iotcentral.RDF-SHACL.json`

### Model examples

- [Thermostat model](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json): `DTDL/v2/samples/Thermostat.json`
- [Temperature controller](https://github.com/azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/TemperatureController.json): `DTDL/v2/samples/TemperatureController.json`

### Other components

- **Model author**
- **IoT services**
- **JSON-LD and RDF**

## Connections

- Model author → V2 language: describes models
- V2 language → IoT services: enables semantics
- V2 language → JSON-LD and RDF: is based on
