Union
In OPC UA, a Union is a Structure subtype that carries exactly one of its declared fields at a time. On the wire it is a UInt32 switch value naming the active field, followed by that field's value; switch value 0 means no field is set. Unions require DataTypeDefinition to decode.
Declaring a union
A union is a DataType whose StructureDefinition has StructureType Union, or in nodeset XML a Definition element with IsUnion set to true. Its fields are alternatives, not members: the definition lists them in order, and the switch value on the wire is the one-based index of the field actually present. Unions arrived with the 1.04 structure extensions alongside optional fields and subtyped values, so they are a comparatively recent construct in deployed servers.
The encoding
In UA Binary a union is a UInt32 SwitchField followed by the encoded value of the selected field and nothing else. Switch value 0 is the null union - no field selected, no value follows - and it is legal. Field 1 is the first field in declaration order. Because the body length depends entirely on the switch, a decoder that guesses wrong does not fail cleanly; it reads the next field's bytes as this one's and corrupts everything after it in the same message.
Where you actually meet them
Unions are used where a value is genuinely one-of: a measurement that may be a scalar or a range, a result that is either a value or an error, an identifier that may be a string or a number. Several of the newer companion specifications use them in result and job models. They are also the construct most likely to be missing from an older client's decoder, which makes them a good compatibility test when you are qualifying a stack.
Decoding them safely
Read the DataTypeDefinition, confirm StructureType is Union, and drive the decode from the switch value rather than from the field list. Validate that the switch is within range: a value larger than the field count means the server is using a newer version of the type than your definition, and the correct response is to stop decoding that value rather than to fall through to field 1. Treat the null union as a distinct state, not as a zero.
Example
A two-field union, its definition and three encoded values
Definition (StructureType = Union)
ns=1;i=3010 MeasurementResult
[1] SingleValue Double
[2] ValueRange Range (Low, High : Double)
UA Binary encodings
switch = 0 null union, no value follows
00 00 00 00
switch = 1, SingleValue = 42.5
01 00 00 00 00 00 00 00 00 40 45 40
switch = 2, ValueRange = { Low 0.0, High 100.0 }
02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 59 40
In nodeset XML
<Definition Name="1:MeasurementResult" IsUnion="true">
<Field Name="SingleValue" DataType="i=11"/>
<Field Name="ValueRange" DataType="i=884"/>
</Definition>Defined in: Part 3 - Address Space Model, Union DataTypes and the StructureType enumeration; Part 6 - Mappings for the union encoding.
Last verified 7 September 2026 against OPC UA 1.05.07. OPC UA Connect is an educational resource and is not affiliated with the OPC Foundation.