KindOfQuantity

Commonly referred to as a KOQ.

Describes a strongly typed kind for a property. This kind identifies what is being measured and stored in an ECProperty. It is used for grouping like properties, setting units and display formatting, and creating quantity objects.

Attributes

typeName Defines the name of this KindOfQuantity. Must be a valid ECName and be unique among all other items in a schema.

description A user-facing description of the KindOfQuantity. Localized and may be shown in a UI.

displayLabel A localized display label that will be used instead of the name in a UI. If not set the Type Name of the KindOfQuantity will be used.

persistenceUnit The unit values of this kind will be stored in.

relativeError The ratio of the absolute error and the actual value persisted as a fractional value (not a percentage). For example if a pipes diameter is measured +/- 1 mm at a diameter of 2 meters the relative error would be 1/2000 => 5e-4.

presentationUnits A list of Formats or format overrides that can be used to display the value in the UI. The first format in the list is used as the default presentation of the value.

The first format in the list is considered the default presentation format. The format used when displaying this kind of value in the UI.

Format Overrides

A format defines the way a value of a property can be displayed in the UI. Formats support several numerical and unit based styles and sometimes that is desired is to change a single part of an existing format, defined within the same schema or reference schema. Instead of copying that format to make the small change, KOQ supports overriding specific portions of the format by using Format Strings.

Format overrides are currently supported the following modifications to an existing Format,

  • Change the precision of the Format
  • Add units to a Format that does not already define any
  • Change the label of units that already exist in the format

Format String

The Format String is a short string-based representation of a Format, which allows overriding of certain key properties of a Format. Its main purpose is to reduce the need for new formats to be created for minor things such as precision and label changes.

The below represents the string literal syntax. All italicized values are to be replaced with appropriate values.

formatName(precision) [unitName|unitLabel] [unitName|unitLabel] [unitName|unitLabel] [unitName|unitLabel]

formatName

  • Required
  • A valid, fully-qualified, ECName referring to a Format

precision

  • Optional
  • Integer
    • See Format for valid options
  • Overrides the number of decimal digits specified in the Format.

Unit Override = [unitName|unitLabel]

  • Optional
  • Adds units to a Format that specifies none or overrides unit labels in a Format definition that specifies units.
  • Position in format string determines which unit it affects in the Format's composite
    • formatName(precision)[First Unit][Second Unit][Third Unit][Fourth Unit]
  • Overrides may not change units if any are originally defined in the base format, they may only change the display label.
  • Up to 4 per format string
  • Example
    • [u:M|meters]

Parts of a Unit Override

unitName

  • Required
  • Name of a unit.
    • The name must be a fully qualified ECName.

unitLabel

  • Optional
  • A string that overrides the label of the Unit, in the position specified in this Unit Override
    • For example, the second override listed would affect the label of the second unit
  • The character ] is not allowed, if this character is desired, a new Format is required.

Examples

  • The format string f:DefaultRealU[u:M][u:CM][u:MM] will override the first unit to be u:M, the second unit to be u:CM and the third unit to be u:MM

  • For the format f:AmerFI (which has FT as a first unit and IN as a second unit), valid overrides must specify both units in the correct order:

Intention Invalid way Valid way
Override second Label f:AmerFI[u:IN|inches] f:AmerFI[u:FT][u:IN|inches]
Override first Label f:AmerFI[u:FT|feet] f:AmerFI[u:FT|feet][u:IN]
Change units f:AmerFI[u:M|m][u:CM|cm] Never Valid

Last Updated: 23 April, 2020