Oracle Cloud Infrastructure Documentation

Scenario: Add JSON Schema Validation to a Digital Twin Model

Use a custom Oracle DTDL validation extension to apply JSON schema data validation rules to device payloads in your digital twin model.

If you reference the validation extension in your digital twin model using by appending the Digital Twin Model Identifier (DTMI): dtmi:com:oracle:dtdl:extension:validation;1 and adding validation metadata @type to the properties, telemetry, or command elements in your digital twin model then you can apply validation rules and constraints to value ranges, regex patterns, enumerations, required fields, or conditional logic. These validation rules are enforced at runtime, to valid data that's ingested and passed through to applications is normalized.

For a complete list of supported validation properties rules, see DTMI Validation Extension Reference.

Before you begin

Make sure you have the required permissions and your OCI CLI is configured. For more information, see Prerequisites, Policy Details for the Internet of Things (IoT) Platform, and Using a JSON File for Complex Input.

Understand the code snippets in this scenario

The code snippets below are examples from a digital twin model that's based on DTDL v3 and demonstrates how to use the custom Oracle validation extension.

Step 1: Define the Validation Extension in the @context of the Digital Twin Model

The required digital twin model context indicating the digital twin model uses DTDL specifications v3: dtmi:dtdl:context;3

To define the validation extension, when you create digital twin model or update a digital twin model append the validation extension to the DTMI URI value in the @context. The digital twin model reads these validation blocks to enforce validation rules to incoming device data. Any data that fails a validation rule is rejected. The normalized and rejected data is in the IoT database schema. 

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  ...
  }

Step 2: Add a validation Property to Elements in a Digital Twin Model

In digital twin models, use JSON Schema Validation Specifications to add validation properties to the validate ingested data.
  • For primitive properties such as strings or integers, validation constraints are added as sibling properties next to the schema field within the property or telemetry definition.
  • For arrays, validations applies to the array itself such as minItems or uniqueItems and defined as siblings of the array schema, while constraints that apply to each element such as value ranges or string patterns are placed inside the array schema, as sibling properties to elementSchema.

Use the following code snippets as examples for your digital twin models. For a complete list of supported validation properties and rules, see DTMI Validation Extension Reference.

Digital Twin Model Snippet: Telemetry with Number Validation

This code snippet from a digital twin model shows how to valid pressures from a sensor between 950.0 and 1050.0 inclusive, and must be a multiple of 0.1.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:example:Sensor;1",
  "@type": "Interface",
  "displayName": "Example Sensor",
  "contents": [
    {
      "@type": ["Telemetry", "Validated"],
      "name": "pressure",
      "schema": "double",
      "displayName": "Pressure",
      "minimum": 950.0,
      "maximum": 1050.0,
      "multipleOf": 0.1
  ]
  }

Digital Twin Model Snippet: String Pattern Validation

This example validates the serial number follows a specific string pattern. In this example, the string pattern is a regular expression that incoming serial number values must match. The serial number value must start with "SN-", followed by 4 to 8 uppercase letters (A-Z) or digits (0-9) and nothing else is allowed before or after:

"pattern": "^SN-[A-Z0-9]{4,8}$"
{
  "@type": ["Property", "Validated"]
  "name": "serialNumber",
  "schema": "string",
  "pattern": "^SN-[A-Z0-9]{4,8}$"
  }

Digital Twin Model Snippet: Array Validation with Element Constraints

Validates the alarm codes must be an array of integers is between 100 and 900. The array must have at least 1, no more than 5 items, and all items must be unique.
{
  "@type": ["Property", "Validated"]
  "name": "alarmCodes",
  "schema": {
    "@type": "Array",
    "elementSchema": "integer",
      "minimum": 100,
      "maximum": 900
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

Digital Twin Model Snippet: Double-Precision Telemetry with Explicit Validation

This example validates the value must be a double whole number and must be inclusive between -50.0 and 150.0.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_double",
  "schema": "double",
  "minimum": -50.0,
  "maximum": 150.0
}

Digital Twin Model Snippet: Single-Precision Telemetry with Explicit Validation

This example validates the value must be a float, and the value must be in the specified range between -50.0 and 150.0.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_float",
  "schema": "float",
  "minimum": -50.0,
  "maximum": 150.0
}

Digital Twin Model Snippet: Telemetry with Type, Range, and Step Validation

This example validates the value is a double, a whole number and between 0 and 360 degrees and in increments of 0.1.

{
  "@type": ["Telemetry", "Validated"]
  "name": "angle",
  "schema": "double",
  "minimum": 0.0,
  "maximum": 360.0,
  "multipleOf": 0.1
}