The Unit of Measure (UoM) is a property that measures the magnitude of a physical quantity. Most numeric properties in engineering software involve measured values and require a UoM.
The Web API v3 supports standardized units of measure types, such as the metric International System of Units (SI), US customary units, and the imperial system. The OData contains resources to support each UoM type, including unit categories that list UoMs based on the object type in the schema.
For example, the unit category for Length returns units for meters, millimeters, feet, and inches. The unit category for Temperature returns units for Celsius, Fahrenheit, Kelvin, and so on. The OData API ensures consistent conversions between the SI unit and other different units.
All UoM values for OData APIs are represented by two properties:
-
[PropertyName]SiValue - The SI property is required by default, and displays a double SI value. For example, the SI unit is meters, so 8 meters is displayed as LengthSiValue=8.
-
[PropertyName] - The base property is optional, and holds a string containing both a numeric value and the UoM symbol. For example, Length=26 ft.
For example, the following unit of measure properties in metadata are from the SDx data model:
. . /api/v3/sdx/$metadata
<EntityType Name="FDWTag" BaseType="Intergraph.SPF.Server.API.Model.SPFObject" OpenType="true">
...
<Property Name="QALength" Type="Edm.String" MaxLength="max" />
<Property Name="QALengthSiValue" Type="Edm.Double" />
<Property Name="QAMandatory" Type="Edm.String" MaxLength="max" />
<Property Name="QAMass" Type="Edm.String" MaxLength="max" />
<Property Name="QAMassSiValue" Type="Edm.Double" />
<Property Name="QAPower" Type="Edm.String" MaxLength="max" />
<Property Name="QAPowerSiValue" Type="Edm.Double" />
...
</EntityType>
Vocabulary and Instance annotations can be used to determine the category and units of a UoM property, and which properties hold UoM values. For example:
. . /api/v3/sdx/annotations/$metadata
<Annotations Target="Intergraph.SPF.Server.API.Model.FDWTag/QALength">
<Annotation Term="Com.Ingr.Measures.V1.UnitCategory" String="Length" />
</Annotations>
<Annotations Target="Intergraph.SPF.Server.API.Model.FDWTag/QALengthSiValue">
<Annotation Term="Com.Ingr.Measures.V1.UnitCategory" String="Length" />
</Annotations>
The SI unit for specific UoM properties can be identified with instance annotations. For example:
{
"UID": "FTG_PlantA_PlantA_230-AC-4501-02",
"QALength@Org.OData.Measures.V1.Unit": "m",
"QALength": "22.5 m",
"QALengthSiValue": 22.5,
"QAMass@Org.OData.Measures.V1.Unit": "g",
"QAMass": "14.7 g",
"QAMassSiValue": 0.0147,
}
The Org.OData.Measures.V1.Unit term is used to identify UoM properties and the corresponding unit used to measure
them. The Com.Ingr.Measures.V1.UnitCategory term is used to identify the related unit category.