The TypeDictionary element is the root element of an OPC Binary Dictionary. The components of this element are described in Table E.1.

Table E.1 TypeDictionary Components

Name

Type

Description

Documentation

Documentation

An element that contains human-readable text and XML that provides an overview of what is contained in the dictionary.

Import

ImportDirective[]

Zero or more elements that specify other TypeDictionaries that are referenced by StructuredTypes defined in the dictionary. Each import element specifies the NamespaceUri of the TypeDictionary being imported. The TypeDictionary element shall declare an XML namespace prefix for each imported namespace.

TargetNamespace

xs:string

Specifies the URI that qualifies all TypeDescriptions defined in the dictionary.

DefaultByteOrder

ByteOrder

Specifies the default ByteOrder for all TypeDescriptions that have the ByteOrderSignificant attribute set to “true”.

This value overrides the setting in any imported TypeDictionary.

This value is overridden by the DefaultByteOrder specified on a TypeDescription.

TypeDescription

TypeDescription[]

One or more elements that describe the structure of a binary encoded value.

A TypeDescription is an abstract type. A dictionary may only contain the OpaqueType, EnumeratedType and StructuredType elements.

A TypeDescription describes the structure of a binary encoded value. A TypeDescription is an abstract base type and only instances of subtypes may appear in a TypeDictionary. The components of a TypeDescription are described in Table E.2.

Table E.2 – TypeDescription Components

Name

Type

Description

Documentation

Documentation

An element that contains human readable text and XML that describes the type. This element should capture any semantic information that would help a human to understand what is contained in the value.

Name

xs: NCName

An attribute that specifies a name for the TypeDescription that is unique within the dictionary. The fields of structured types reference TypeDescriptions by using this name qualified with the dictionary namespace URI.

DefaultByteOrder

ByteOrder

An attribute that specifies the default ByteOrder for the type description.

This value overrides the setting in any TypeDictionary or in any StructuredType that references the type description.

anyAttribute

*

Authors of a TypeDictionary may add their own attributes to any TypeDescription that shall be qualified with a namespace defined by the author. Applications should not be required to understand these attributes in order to interpret a binary encoded instance of the type.

An OpaqueType describes a binary encoded value that is either a primitive fixed length type or that has a structure too complex to capture in an OPC Binary type dictionary. Authors of type dictionaries should avoid defining OpaqueTypes that do not have a fixed length because it would prevent applications from interpreting values that use these types without having built-in knowledge of the OpaqueType. The OPC Binary Type Description System defines many standard OpaqueTypes that should allow authors to describe most binary encoded values as StructuredTypes.

The components of an OpaqueType are described in Table E.3.

Table E.3 – OpaqueType Components

Name

Type

Description

TypeDescription

TypeDescription

An OpaqueType inherits all elements and attributes defined for a TypeDescription in Table E.2.

LengthInBits

xs:string

An attribute which specifies the length of the OpaqueType in bits. This value should always be specified. If this value is not specified the Documentation element should describe the encoding in a way that a human understands.

ByteOrderSignificant

xs:boolean

An attribute that indicates whether byte order is significant for the type.

If byte order is significant then the application shall determine the byte order to use for the current context before interpreting the encoded value. The application determines the byte order by looking for the DefaultByteOrder attribute specified for containing StructuredTypes or the TypeDictionary. If StructuredTypes are nested the inner StructuredTypes override the byte order of the outer descriptions.

If the DefaultByteOrder attribute is specified for the OpaqueType, then the ByteOrder is fixed and does not change according to context.

If this attribute is “true”, then the LengthInBits attribute shall be specified and it shall be an integer multiple of 8 bits.

An EnumeratedType describes a binary-encoded numeric value that has a fixed set of valid values. The encoded binary value described by an EnumeratedType is always an unsigned integer with a length specified by the LengthInBits attribute.

The names for each of the enumerated values are not required to interpret the binary encoding, however, they form part of the documentation for the type.

The components of an EnumeratedType are described in Table E.4.

Table E.4 – EnumeratedType Components

Name

Type

Description

OpaqueType

OpaqueTypeDescription

An EnumeratedType inherits all elements and attributes defined for a TypeDescription in Table E.2 and for an OpaqueType defined in Table E.3.

The LengthInBits attribute shall always be specified.

EnumeratedValue

EnumeratedValue

One or more elements that describe the possible values for the instances of the type.

A StructuredType describes a type as a sequence of binary-encoded values. Each value in the sequence is called a Field. Each Field references a TypeDescription that describes the binary-encoded value that appears in the field. A Field may specify that zero, one or multiple instances of the type appear within the sequence described by the StructuredType.

Authors of type dictionaries should use StructuredTypes to describe a variety of common data constructs including arrays, unions and structures.

Some fields have lengths that are not multiples of 8 bits. Several of these fields may appear in a sequence in a structure, however, the total number of bits used in the sequence shall be fixed and it shall be a multiple of 8 bits. Any field which does not have a fixed length shall be aligned on a byte boundary.

A sequence of fields which do not line up on byte boundaries are specified from the least significant bit to the most significant bit. Sequences which are longer than one byte overflow from the most significant bit of the first byte into the least significant bit of the next byte.

The components of a StructuredType are described in Table E.5.

Table E.5 – StructuredType Components

Name

Type

Description

TypeDescription

TypeDescription

A StructuredType inherits all elements and attributes defined for a TypeDescription in Table E.2.

Field

FieldType

One or more elements that describe the fields of the structure. Each field shall have a name that is unique within the StructuredType. Some fields may reference other fields in the StructuredType by using this name.

A FieldType describes a binary encoded value that appears in sequence within a StructuredType. Every FieldType shall reference a TypeDescription that describes the encoded value for the field.

A FieldType may specify an array of encoded values.

Fields may be optional and they reference other FieldTypes, which indicate if they are present in any specific instance of the type.

The components of a FieldType are described in Table E.6.

Table E.6 – FieldType Components

Name

Type

Description

Documentation

Documentation

An element that contains human readable text and XML that describes the field. This element should capture any semantic information that would help a human to understand what is contained in the field.

Name

xs:string

An attribute that specifies a name for the Field that is unique within the StructuredType.

Other fields in the structured type reference a Field by using this name.

TypeName

xs:QName

An attribute that specifies the TypeDescription that describes the contents of the field. A field may contain zero or more instances of this type depending on the settings for the other attributes and the values in other fields.

Length

xs:unsignedInt

An attribute that indicates the length of the field. This value may be the total number of encoded bytes or it may be the number of instances of the type referenced by the field. The IsLengthInBytes attributes specifies which of these definitions applies.

LengthField

xs:string

An attribute that indicates which other field in the StructuredType specifies the length of the field. The length of the field may be in bytes or it may be the number of instances of the type referenced by the field. The IsLengthInBytes attributes specify which of these definitions applies.

If this attribute refers to a field that is not present in an encoded value, then the default value for the length is 1. This situation could occur if the field referenced is an optional field (see the SwitchField attribute).

The length field shall be a fixed length Base-2 representation of an integer. If the length field is one of the standard signed integer types and the value is a negative integer, then the field is not present in the encoded stream.

The FieldType referenced by this attribute shall precede the field with the StructuredType.

IsLengthInBytes

xs:boolean

An attribute that indicates whether the Length or LengthField attributes specify the length of the field in bytes or in the number of instances of the type referenced by the field.

SwitchField

xs:string

If this attribute is specified, then the field is optional and may not appear in every instance of the encoded value.

This attribute specifies the name of another Field that controls whether this field is present in the encoded value. The field referenced by this attribute shall be an integer value (see the LengthField attribute).

The current value of the switch field is compared to the SwitchValue attribute using the SwitchOperand. If the condition evaluates to true then the field appears in the stream.

If the SwitchValue attribute is not specified, then this field is present if the value of the switch field is non-zero. The SwitchOperand field is ignored if it is present.

If the SwitchOperand attribute is missing, then the field is present if the value of the switch field is equal to the value of the SwitchValue attribute.

The Field referenced by this attribute shall precede the field with the StructuredType.

SwitchValue

xs:unsignedInt

This attribute specifies when the field appears in the encoded value. The value of the field referenced by the SwitchField attribute is compared using the SwitchOperand attribute to this value. The field is present if the expression evaluates to true. The field is not present otherwise.

SwitchOperand

xs:string

This attribute specifies how the value of the switch field should be compared to the switch value attribute. This field is an enumeration with the following values:

Equal

SwitchField is equal to the SwitchValue.

GreaterThan

SwitchField is greater than the SwitchValue.

LessThan

SwitchField is less than the SwitchValue.

GreaterThanOrEqual

SwitchField is greater than or equal to the SwitchValue.

LessThanOrEqual

SwitchField is less than or equal to the SwitchValue.

NotEqual

SwitchField is not equal to the SwitchValue.

In each case the field is present if the expression is true.

Terminator

xs:hexBinary

This attribute indicates that the field contains one or more instances of TypeDescription referenced by this field and that the last value has the binary encoding specified by the value of this attribute.

If this attribute is specified then the TypeDescription referenced by this field shall either have a fixed byte order (i.e. byte order is not significant or explicitly specified) or the containing StructuredType shall explicitly specify the byte order.

Examples:

Field Data TypeTerminatorByte OrderHexadecimal String

Char tab characternot applicable09

WideChartab characterBigEndian0009

WideChartab characterLittleEndian0900

Int16 1 BigEndian0001

Int16 1 LittleEndian0100

anyAttribute

*

Authors of a TypeDictionary may add their own attributes to any FieldType which shall be qualified with a namespace defined by the authors. Applications should not be required to understand these attributes in order to interpret a binary encoded field value.

An EnumeratedValue describes a possible value for an EnumeratedType.

The components of an EnumeratedValue are described in Table E.7.

Table E.7 – EnumeratedValue Components

Name

Type

Description

Name

xs:string

This attribute specifies a descriptive name for the enumerated value.

Value

xs:int

This attribute specifies the numeric value that could appear in the binary encoding.

A ByteOrder is an enumeration that describes a possible value byte orders for TypeDescriptions that allow different byte orders to be used. There are two possible values: BigEndian and LittleEndian. BigEndian indicates the most significant byte appears first in the binary encoding. LittleEndian indicates that the least significant byte appears first.

An ImportDirective specifies a TypeDictionary that is referenced by types defined in the current dictionary.

The components of an ImportDirective are described in Table E.8.

Table E.8 – ImportDirective Components

Name

Type

Description

Namespace

xs:string

This attribute specifies the TargetNamespace for the TypeDictionary being imported. This may be a well-known URI which means applications need not have access to the physical file to recognise types that are referenced.

Location

xs:string

This attribute specifies the physical location of the XML file containing the TypeDictionary to import. This value could be a URL for a network resource, a NodeId in an OPC UA Server address space or a local file path.