DTMI Validation Extension Reference
Add a DTMI validation extension to your digital twin model so you can define data validation rules using JSON Schema validation properties.
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.
- 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 apply to the array itself such as
minItemsoruniqueItemsare defined as siblings of the array schema, while constraints that apply to each element such as value ranges or string patterns that are placed inside the array schema, as sibling properties toelementSchema.
The IoT platform supports the following JSON schema validation keywords:
- Numeric Instances including:
numberandinteger - Strings:
"schema": "string" - Arrays
minItems,maxItems, anduniqueItems - Objects:
required. See Required and Optional Object Fields.
For
exclusiveMinimum and exclusiveMaximum validation, when you use the unsignedLong schema type, values may be converted to doubles if they exceed the range of a standard long. This conversion can result in a loss of precision, so values near the exclusiveMinimum or exclusiveMaximum may not pass validation even if they appear to be valid.| Validation | Data Type | Valid on these @types | Applies to schema types | Examples |
|---|---|---|---|---|
| Number | Array CommandRequest CommandResponse Enum Field MapValue Property Telemetry |
| |
| Number | Array CommandRequest CommandResponse Enum Field MapValue Property Telemetry |
| |
| Integer | Array CommandRequest CommandResponse Enum Field MapKey MapValue Property Telemetry |
| |
multipleOf | Number | Array CommandRequest CommandResponse Enum Field MapValue Property Telemetry |
| |
pattern | String | Array CommandRequest CommandResponse Enum Field MapKey MapValue Property Telemetry |
| |
| Integer | Array CommandRequest CommandResponse Field MapValue Property Telemetry | Array Schema (all primitive types) | |
uniqueItems | Boolean | Array CommandRequest CommandResponse Field MapValue Property Telemetry | Array Schema (all primitive types) | |
required | Array of field names | Object | Object schema; add beside fields | An empty list makes all declared fields optional. Use the validation extension and containing |
Required and Optional Object Fields
Use the existing dtmi:com:oracle:dtdl:extension:validation;1 context and the Validated co-type on the containing content to use required in an Object schema. No new validation extension version is needed.
Add required beside fields in the Object schema. Its value is an array of field names that must be supplied. Declared fields not listed in the array are optional and can be omitted.
- If an Object has no
requiredproperty, all declared fields remain required. - With
"required": [], all declared fields are optional. Any supplied field value must still satisfy its schema and constraints. - Omit an optional field when no value is available. Do not send JSON null in place of an omitted field. Supplied values must satisfy their declared schemas and constraints.
- Each Object's list applies only to its immediate fields. A nested Object has its own list. To make the nested Object itself optional, omit its field name from the parent's list; if supplied, it must satisfy its own rules.
- The same rule applies to Objects used as Array elements or Map values: each Object uses the list on its own schema.
For example, "required": ["errorCount", "stale", "state"] permits a sensor to omit lastSuccessTime until it has a successful reading, while retaining the required health fields. See the sensor model example and the nested Object example.