A Unit of Measure (UoM) is a property that measures the magnitude of a physical quantity. Most numeric properties in engineering software, including Smart APIs, involve measured values and thus require UoM.
All UoM values for Smart APIs can be represented by two properties:
-
{PropertyName}SiValue (required) - The SI property holds a double value in International System of Units (SI). For example, LengthSiValue is 8, and the SI unit is meters.
-
{PropertyName} (optional) - The base property holds a string containing both a numeric value and unit symbol. For example, Length is "26.25 ft".
For example, if you examine the metadata for the SampleService, you will find that Equipment length is a Unit of Measure:
https://sam.spclouddave.com/SampleService/Sppid/v2/$metadata
<EntityType Name="Equipment" BaseType="Com.Ingr.Sppid.V1.PlantItem"
Abstract="true" OpenType="true">
.
<Property Name="LengthSiValue" Type="Edm.Double"/>
<Property Name="Length" Type="Edm.String"/>
</EntityType>
You can also discover which properties hold UoM values by examining the annotations metadata document. For example, you will discover annotations like the following:
https://sam.spclouddave.com/SampleService/Sppid/V2/Annotations/$metadata
<Annotations Target="Com.Ingr.Sppid.V1.Equipment/LengthSiValue">
<Annotation Term="Org.OData.Measures.V1.Unit" String="m"/>
<Annotation Term="Com.Ingr.Vocabularies.Measures.V1.UnitCategory" String="Length"/>
.
<Annotations Target="Com.Ingr.Sppid.V1.Equipment/Length">
<Annotation Term="Org.OData.Measures.V1.Unit" String="ft"/>
<Annotation Term="Com.Ingr.Vocabularies.Measures.V1.UnitCategory" String="Length"/>
.
</Annotations>
The Org.OData.Measures.V1.Unit term is used to identify UoM properties and the corresponding SI unit used to measure them.
The Com.Ingr.Vocabularies.Measures.V1.UnitCategory term is used to identify the kind of related unit types supported.
Be aware that when you read or write UoM values, you are responsible for validating
both properties.
There is a public-facing, shared, and common Units of Measure API to support all
Smart APIs. This UoM Smart API contains resources for the supported, standard UoM,
or units, as well as unit_categories, which are lists of UoMs, or units per quantity
type, based on the Engineering Framework Schema.
For example, the unit category Length will return units like mm, m, ft, and in; the unit category Temperature will return units like C, F, and K; and so forth. The API ensures consistent conversions between different units and the SI unit. See the following topic for details.