Creating a Digital Twin Model

Create a digital twin model for your Internet of Things (IoT).

A digital twin model defines the semantics of a digital twin and is based on the DTDL v3 specifications. A digital twin model uses a Digital Twin Model Identifier (DTMI) as a unique identifier.

For example: dtmi:com:oracle:iot:connectable;1

A digital twin instance requires a digital twin model and a digital twin adapter to receive structured device data. For specific examples, see Scenarios.

Note

Digital Twins Definition Language (DTDL) v3 is supported on GitHub by the Digital Twin Consortium. It is important to note that MQTT extensions and writable properties are not supported.

If a writable property is included, it must be set to false.

Use the oci iot digital-twin-model create command and required parameters to create a digital twin model in a specific IoT domain. Provide the specifications as JSON content directly in the command line or as a file referenced in the command line:

This example shows providing the JSON specifications directly in the command line:

oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec '{"@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:historization;1", "dtmi:dtdl:extension:quantitativeTypes;1", "dtmi:com:oracle:dtdl:extension:validation;1"], "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1", "@type": "Interface", "contents": [{"@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "integer", "unit": "degreeFahrenheit"}, {"@type": ["Telemetry", "Historized", "Validated"], "name": "humidity", "schema": "integer", "minimum": 0, "maximum": 100}, {"@type": ["Property", "Historized"], "name": "location", "schema": "point", "writable": true}, {"@type": ["Property", "Validated"], "name": "serialNumber", "schema": "string", "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"}]}'

This example shows how to create a dtdl-specifications.json file that contains the your specifications and reference the file in the command. For more information about referencing files, see Using a JSON File for Complex Input:

oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-specifications.json

Example dtdl-specifications.json file based on the DTDL v3 specification that contains a Digital Twin Model Identifier (DTMI) as a unique identifier.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "schema": "integer",
      "unit": "degreeFahrenheit"
    },
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Validated"
      ],
      "name": "humidity",
      "schema": "integer",
      "minimum": 0,
      "maximum": 100
    },
    {
      "@type": [
        "Property",
        "Historized"
      ],
      "name": "location",
      "schema": "point",
      "writable": false
    },
    {
      "@type": [
        "Property",
        "Validated"
      ],
      "name": "serialNumber",
      "schema": "string",
      "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"
    }
  ]
}

This example response shows the digital twin model was created for the IoT domain, with a DTMI URI: dtmi:com:oracle:iot:sample:hvac:unique-id;1:

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user",
        "CreatedOn": "2025-08-05T17:43:00.438Z"
      }
    },
    "description": null,
    "display-name": "HVAC",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:iot:sample:hvac:unique-id;1",
    "system-tags": {},
    "time-created": "2025-08-05T17:43:00.508000+00:00",
    "time-updated": "2025-08-05T17:43:00.508000+00:00"
  },
  "etag": "<unique-id>"
}

For a complete list of parameters and values for CLI commands, see CLI Command Reference

Run the CreateDigitalTwinModel operation to create a digital twin model in the specific IoT domain.

Example request:

POST /20250531/digitalTwinModels
content-type: application/json+ld
{
    "@context": ["dtmi:dtdl:context;3"],
    "@id": "dtmi:com:oracle:labauto:SmartSpecimenVault;1",
    "@type": "Interface",
    "extends": "dtmi:com:oracle:iot:connectable;1",
    "displayName": "HVAC",
    "contents": [
        {"@type": "Telemetry", "name": "temperature", "schema": "integer"},
        {"@type": "Telemetry", "name": "humidity", "schema": "integer", "minimum":0, "maximum": 100},
        {"@type": "Property", "name": "desiredTemperature", "schema": "integer", "writable": true},
        {"@type": "Property", "name": "serialNumber", "schema": "string"} 
    ]
}

Example response:

header:
content-type: application/json
Body:
{
    "id": "<digital-twin-model-OCID>"
    "displayName": "<your-HVAC-display-name>",
    "description": "<digital-twin-model-for-HVAC>"
    "lifecycleState": "ACTIVE",
    "freeformTags": {},
    "definedTags": {
       "Oracle-Tags": {
         "CreatedBy": "default/user@oracle.com",
         "CreatedOn": "2024-07-22T10:24:53.446Z"
       }
    },
    "specUri": "dtmi:com:oracle:labauto:SmartSpecimenVault;1"
    "timeCreated": "2025-01-13T10:24:53Z",
    "timeUpdated": "2025-01-14T17:15:21Z"
}

Oracle Cloud Infrastructure Documentation

Creating a Digital Twin Model