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
The required digital twin model context indicates the digital twin model uses DTDL v3: dtmi:dtdl:context;3
In digital twin models, use JSON Schema Validation Specifications to add validation properties to the validate ingested data. To learn how to use the DTMI extension in your digital twin model, see Scenario: Add JSON Schema Validation to a Digital Twin Model.

A digital twin instance requires a digital twin model and a digital twin adapter to receive data from a device that sends structured 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:

MQTT extensions and writable properties are not supported. If a writable property is included, it must be set to false.
Only the content within the component can be annotated as historized, indicating the IoT platform must retain that sensor’s time-series telemetry, see the digital twin model example dtdl-model-specifications.json below.

If you want to create a digital twin instance without ingestible data from a device, then you can create a digital twin instance without a digital twin adapter and without the authentication ID parameter, --auth-id. The associated digital twin model must not contain telemetry or properties. After, you create a digital twin instance, then you can create a digital twin relationship to simulate your IoT environment without the complexity of data or authentication.

1. On the IoT domains list page, select the IoT domain you want to work with. If you need help finding the IoT domains list page, see Listing IoT Domains.
2. Select the Digital twin models tab, select Create.
3. Enter a Name and optionally a user friendly Description. Avoid entering confidential information.
4. Select an option to add the model's DTDL specification:
  To upload your dtdl-specification.json file, select upload the specification. Drag and drop or select a .json file with the DTDL specification for this digital twin model.
  To add the JSON for the digital twin model, select paste specification.
5. Tags: (Optional) Add one or more tags to the digital twin model. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
6. Select Create.
View the digital twin model's details. Copy the associated IoT domain OCID, digital twin model DTMI, or the digital twin model OCID.
Select the related tab to view the DTDL specification, the Associated digital twin instances, Associated digital twin adapters, or Tags for this digital twin model.

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:

Inline example: 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}$"}]}'

File reference example: This example shows how to create a dtdl-model-specifications.json file that contains your specifications, how to reference the .json file in the command. The format may vary based on your operating system 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-model-specifications.json

In this snippet from the example digital twin model below:

Notice the humidity value is annotated as historized telemetry, so each humidity reading is stored as a time-series measurement with a timeObserved timestamp, instead of only recording the latest value.
It’s also validated to be an integer in the range 0–100. Only the content within a component can be annotated as historized notice this @type declaration in the example below.

{
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}

In this HVAC model, dtdl-model-specifications.json

This model is based on the DTDL v3 specification and contains a Digital Twin Model Identifier (DTMI) as a unique identifier: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
This example digital twin model enables the historization, qualitative types, and the validation extension contexts. See DTMI Validation Extension Reference.
As described in the snippet above the humidity telemetry is annotated as Historized, so the humidity readings are retained as time series data, readings over time.
location telemetry is annotated as Historized, so changes to the location are also retained over time, recording property's location history with an audit trail.
temperature telemetry is not annotated with Historized, recording only the last known value another downstream persistence configured somewhere else.
serialNumber property is marked Validated using a regex pattern and is not annotated as Historized, so only the current or latest value is maintained not a historical tracking of changes.

{
  "@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 CLI 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": false},
        {"@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