This page discusses datapoints whose value includes unions.  See also Working with Datapoint Values.

Background

A union is an aggregate with multiple fields of different types that overlap each other, providing different interpretations of the same shared implementation value.

IAP datapoint types support unions with the baseAggregate schema and cat: “one of”.

Working with unions faces three fundamental challenges:

• Unions do not indicate the field that is "active".
  Consider the example of a union with three fields, a single precision floating point type, an unsigned 8-bit integer, and an unsigned 32-bit integer type. In a big-endian implementation with big-endian alignment, the floating-point field might read 1.234, while the long integer field shows 1067316150, and the short integer field shows 63. Selecting the correct interpretation depends on  the context. Consumers of this data may not care about selecting the correct interpretation, as might be the case for a generic data logger. Custom applications typically have the contextual knowledge build in to be able to make the correct interpretation.
  
  
• Unions are always implementation-dependent. The example above is correct for big-endian data in a big-endian aligned union.
  For example, if the example union was implemented with big-endian data but little endian alignment, the short integer field would become 182 while the other fields would remain unchanged.
  
  
• Many modern languages and formats, including JSON and JavaScript, have no native support for unions.

Presenting Unions

IAP presents unions like structures (or JSON "objects"), showing all the fields in their native value.  The example union from above would be presented as follows:

Writing Unions

When writing a value to a union, you must only include one field within the union. Writing a union with more than one field at once yields an invalid value error.  For example, you could write the example union with this value:

For a union implemented with big-endian data and big-endian alignment, the resulting value feedback would be:

This feedback requires that the engine modifies the shortInt field but preserves any other bytes. Other engines may implement an alternative strategy that clears the implementation data in its entirety, then assigns the desired field. Therefore, this alternative feedback is also acceptable:

Unions in Datapoint Connections

Peer-to-peer datapoint connections can connect datapoint types that include unions, because a peer-to-peer datapoint connection is within one edge protocol, carrying the implementation value.

In the example above, the union value might be carried as four bytes of hexadecimal values 0x3F.9D.F3.B6. Sources and destinations have the contextual knowledge necessary to interpret this data correctly (or do not require such knowledge).

For point-to-point datapoint connections, an explicit type transcoding map is required to select one field of the source union and write it to the destination. Transcoding maps are detailed in /wiki/spaces/DrftSSIoT/pages/1480114.