QuantitativeTypes extension

PREVIEW DOCUMENTATION

This document provides a preliminary description of a future version of DTDL.
Preview functionality is provided without a service level agreement, and is not recommended for production uses.
Any and all aspects of the language described herein are subject to change without notice until this version of DTDL becomes generally available.
There is no obligation of continued support for any feature, aspect, or syntactical construct that does not make the transition to general availability.
For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Version 1

Usable in DTDL version 3

The QuantitativeTypes extension provides a set of standard semantic types that can be applied to CommandRequests, CommandResponses, Fields, MapValues, Properties, and Telemetries.
If a service supports the QuantitativeTypes extension, and if the QuantitativeTypes context is specified, the service recognizes and understands the semantic types, unit types, and units itemized below, as well as the unit property on each of the semantic types.

QuantitativeTypes context

The context specifier for version 1 of the QuantitativeTypes extension is “dtmi:dtdl:extension:quantitativeTypes;1”.

Semantic types and units

The semantic types itemized below can co-type a CommandRequest, a CommandResponse, a Field, a MapValue, a Property, or a Telemetry in DTDL version 3.
When a CommandRequest, CommandResponse, Field, MapValue, Property, or Telemetry is co-typed with one of these semantic types, the value of the unit property must be an instance of the corresponding unit type, and the value of the schema property must be a numeric type.

Note that although most semantic types have matching unit types, there is not a strict one-to-one correspondence between semantic types and unit types.
For example, Humidity is expressed using DensityUnit, and Luminosity is expressed using PowerUnit.

The chart below itemizes semantic types, corresponding unit types, and available units for each unit type.

Note:
The TimeSpan semantic type should not be confused with the duration schema type.
The duration schema is in ISO 8601 format; it is intended for calendar durations; and it does not play well with SI units.
The semantic unit for TimeSpan is TimeUnit, which gives temporal semantics to a numeric schema type.

Semantic type and unit examples

The following example shows an Interface with four contents elements that are all of type Telemetry.

• The element named “thermometer” has co-type Temperature and unit degreeCelsius.
• The element named “barometer” has co-type Pressure and unit millibar.
• The element named “humidityMeter” has co-type RelativeHumidity and unit percent.
• The element named “anemometer” has co-type Velocity and unit metrePerSecond.

One Telemetry has a schema value of integer, and the other three have schema values of double, all of which are valid since both integer and double are numeric schemas.

{
    "@id": "dtmi:com:example:Sensor;1",
    "@type": "Interface",
    "contents": [
        {
            "@type": [ "Telemetry", "Temperature" ],
            "name": "thermometer",
            "schema": "double",
            "unit": "degreeCelsius"
        },
        {
            "@type": [ "Telemetry", "Pressure" ],
            "name": "barometer",
            "schema": "double",
            "unit": "millibar"
        },
        {
            "@type": [ "Telemetry", "RelativeHumidity" ],
            "name": "humidityMeter",
            "schema": "integer",
            "unit": "percent"
        },
        {
            "@type": [ "Telemetry", "Velocity" ],
            "name": "anemometer",
            "schema": "double",
            "unit": "metrePerSecond"
        }
    ],
    "@context": [
        "dtmi:dtdl:context;3",
        "",
        "dtmi:dtdl:extension:quantitativeTypes;1"
    ]
}

Feature versions

The chart below lists the versions of the QuantitativeTypes extension that are currently available.