6 Model

6.1 Overview

Object Serialization provides a consistent, compact representation of the Variable Values in the SerializationScope. Objects or Variables that are the root of such a serialization are called SerializationStartNodes and have HasSerializationEntity References to one or more SerializationEntities. The SerializationEntities are of ObjectType SerializationEntityType, see 6.2. The SerializationProcess is controlled by Properties of this ObjectType.

The DataType of the SerializedData Variable is the SerializationValue DataType mapping all Values in the SerializationScope. It is the serialization DataType of the SerializationStartNode. The Values themselves each have their own SerializationFieldDataType. In the example shown in Figure 6, the SerializationFieldDataTypes of the Variables in the SerializationScope equal the DataTypes of the original Values.

In the example above, the “MyObjectSerialization” instance of SerializationEntityType has the IncludeReferenceTypes Property set to “HasChild”. This selects all Variables and Properties.

Because it is instance-specific, the SerializationValue DataType Node is dynamically created. Its BrowseName and NodeId are Server-specific and could be GUID-based.

In the Type-based serialization the SerializationValue DataType Node is defined in the subtype of the SerializationEntityType.

6.2 Limitations

Since the BrowseNames of the Variables in the SerializationScope are used as field names for the SerializationFieldDataType fields in the SerializationValue DataType, limitations for BrowseNames arise: The characters used for the BrowseNames must be permissible in field names of Structure DataTypes. To achieve this, it is recommended to limit the characters used in BrowseNames to letters (lower- and uppercase), digits and the underscore ('_'). The BrowseName must not start with a digit. Special characters (e.g. '@', '*', etc.) shall not be used.

If a non-allowed character is encountered, this character will be replaced according to the name encoding rules defined in the OPC 10000-6.

If conflicting BrowseNames (e.g. duplicate BrowseNames on the same hierarchy level) are encountered, the SerializationProcess fails and the StatusCode for access yields Bad_BrowseNameDuplicated.

6.3 SerializationEntityType ObjectType

6.3.1 Definition

The SerializationEntityType ObjectType defines the SerializationProcess. It has SerializationProperties which allow the configuration of the SerializationProcess and the SerializationScope.

The SerializationEntityType is formally defined in Table 1 and illustrated in Figure 7.

The SerializationProperties are described starting with clause 6.3.4. The default settings in Table 2 apply for Properties that are not provided on a SerializationEntityType instance.

6.3.2 SerializedData Variable

The SerializedData Variable holds the SerializationValue, customized by the SerializationProperties.

The DataType of the SerializationValue is the SerializationValue DataType and is a subtype of Structure where the DataTypeDefinition Attribute of this DataType provides the metadata and encoding information.

The DataType Node including the DataTypeDefinition Attribute is dynamically created. It only has an inverse Reference to its supertype Structure. Clients must obtain the NodeId by reading the DataType Attribute of the SerializedData Variable. Then they must read the DataTypeDefinition Attribute of the DataType to be able to decode the SerializationValue.

The Value of the SerializedData Variable is only generated (serialized) when requested by the Read Service, by a Subscription or in PubSub publishing.

The SerializationValue is typically read-only. If the Server supports write access, the Client’s Session shall be able to successfully write all original Variables in the SerializationScope. If the write for any Variable fails, the write call shall fail and return a proper result code (e.g., Bad_NotWritable, Bad_InvalidArgument, and Bad_ConfigurationError).

If the SerializationScope contains nested subtrees, each element that has children itself has its own DataType Node describing these direct children of this element.

The SerializationValue can change in the following ways:

By changing the SerializationProperties with the ConfigureSerialization Method.

By other changes of the AddressSpace, for instance insertion or deletion of child nodes on any level of the subtree in the SerializationScope.

In case of such changes, a new DataType shall be created with a new DataType NodeId and encoding NodeId. This DataType Attribute of the SerializedData Variable shall refer to this new DataType.

In case of PubSub, a change of the DataType NodeId causes a change of the metadata.

Servers may not be able to save dynamically created Nodes. In addition, the AddressSpace may have changed (reconfigured) during shutdown.

If the SerializationEntity is an InstanceDeclaration, accessing the SerializedData Variable is not possible. Reading attempts are answered with the StatusCode Bad_NoValue.

6.3.3 ConfigureSerialization Method

ConfigureSerialization is an optional Method to set the SerializationProperties of the parent SerializationEntity.

The DI:LockingServicesType is an AddIn defined in OPC 10000-100. This AddIn shall be added as instance with the instance name “Lock” if the Server implements the ConfigureSerialization Method.

Before invoking this Method, Clients shall lock the SerializationEntity using the Lock Object instance.

When successful, the Server will create a new DataType for the SerializedData Variable with the DataTypeDefinition Attribute for the metadata and encoding information.

The signature of this Method is specified below. Table 3 and Table 4 specify the arguments and AddressSpace representation, respectively.

Signature

	ConfigureSerialization (
		[in]	KeyValuePair[]	SerializationFilterProperties,
		[out]	Int32[]		Results
	);
	

The Method result codes (defined in Call Service) are defined in Table 5. The configuration is applied if a result code with severity Good is returned. Otherwise, no Property is changed.

If the desired settings do not deviate from the actual settings, the Method shall do nothing and return Good as result code.

6.3.4 Include- and ExcludeReferenceTypes Properties

These Properties allow to select which ReferenceTypes are followed to create the SerializationScope: The IncludeReferenceTypes Property contains an array of ReferenceType NodeIds. Any Reference of each ReferenceType NodeId of the array including their subtypes is considered. The ExcludeReferenceTypes Property contains an array of ReferenceType NodeIds. Any Reference of each ReferenceType NodeId of the array including their subtypes is removed from the results out of the IncludeReferenceType Property.

The exclude rules determined by the ExcludeReferenceTypes Property have priority against the include rules determined by the IncludeReferenceTypes Property. The HasSerializationEntity ReferenceType is always excluded.

Figure 8 shows a usage example for the ReferenceType Properties. IncludeReferenceTypes contains HierarchicalReferences. This selects Variable1, Object1 and Property3. ExcludeReferenceTypes contains HasComponent. This removes Variable1 and Object1 from the selection. Therefore, only Property3 referenced by HasProperty is mapped to a field of the SerializationValue DataType.

6.3.5 SerializationDepth Property

The SerializationDepth Property allows to limit the serialization levels of the SerializationScope.

A SerializationDepth Value of 0 implies no limit. A Value of 1 implies direct children of the Object, and so on.

If SerializationDepth is equal to zero and the SerializationScope contains circular References, the process of serialization into a Structure does not stop. The modelling or the implementation shall contain countermeasures to prevent this.

6.3.6 ConsiderSubElementSerializationProperties Property

The ConsiderSubElementSerializationProperties Property contains a Boolean Value. If set to True, SerializationEntities referenced by elements of the SerializationScope which have the same BrowseName as the SerializationEntity referenced by the SerializationStartNode are considered for the SerializationProcess. If false, only the SerializationEntity referenced by the SerializationStartNode is used.

Figure 9 demonstrates the usage of the ConsiderSubElementSerializationProperties Property. The IncludeReferenceTypes and ExcludeReferenceTypes Properties of the “ObjectSerialization” SerializationEntity are set according to Figure 8. The ConsiderSubElementSerializationProperties Property contains the Value “True”. So, any SerializationEntity of a child node in the subtree originating from the SerializationStartNode with the BrowseName “ObjectSerialization” will be considered. “Variable2” has such a SerializationEntity. This SerializationEntity sets the ReferenceTypes to select all hierarchical References but no HasComponent References. As result, “Property1” and “Property1.1” are excluded by the “ObjectSerialization” Properties referenced by “MyObject”. “Variable2.1” is excluded and “Property2.1” is included by the “ObjectSerialization” Properties referenced by “Variable2”.

6.3.7 CustomMetaDataProperties Property

DataSetMetaData describe the content and the semantics of a DataSet. Subscribers use this metadata to interpret the DataSet from the DataSetMessage and can evaluate the Properties field of the FieldMetaData Structure (see OPC 10000-14).

The CustomMetaDataProperties Property contains an array of KeyValuePairs. The purpose of this Property is the enhancement of the DataSetMetaData if the SerializedData Variable is serialized in a PubSub scenario. If the SerializedData Variable is used in a published DataSet, the KeyValuePairs of the CustomMetaDataProperties Property shall be added to the Properties field in the FieldMetaData Structure representing the SerializedData Variable in the containing DataSetMetaDataType Structure comprising the DataSetMetaData (see OPC 10000-14).

The field names from the structures containing the Values the semantic Properties belong to are qualified with the OPC UA Namespace. This allows the encoder to omit the NamespaceIndex when serializing the QualifiedName inside the KeyValuePair.

Figure 10 shows the structure of the CustomMetaDataProperties for a SerializationScope excluding the metadata comprising the EUInformation and EngineeringUnits Properties of the AnalogUnitType and AnalogUnitRangeType Variables in the SerializationScope.

The content of the CustomMetaDataProperties Property of the SerializedData Variable describes the semantic Properties for all Values mapped into the SerializationValue DataType of the SerializedData. It is used as Properties field of the FieldMetaData Structure representing the SerializedData Variable in the DataSet.

The KeyValuePair elements at the lowest indices contain the semantic Properties (e.g. key=“EngineeringUnits”, value=EUInformation) for the Value of the represented Variable. Sub-Variables are represented with elements containing KeyValuePairs with keys equal to the BrowseNames of the Variables (see “Variable1”, “Variable2” and “Variable3” elements) and arrays of KeyValuePairs for the semantic Properties of those Variables as values.

6.3.8 CustomMetaDataRef Property

The CustomMetaDataRef Property references another SerializedData Variable. The Value of this Property is the NodeId of this other Variable. A KeyValuePair with the BrowseName of this Variable as key and the NodeId of this Variable as value is added to the content of the Properties KeyValuePair array in the FieldMetaData.

If the CustomMetaDataProperties and the CustomMetaDataRef Properties are both provided, the contents of both are combined in the Properties KeyValuePair array in the FieldMetaData Structure.

6.3.9 IncludeStatus, IncludeSourceTimestamp, and IncludeDictionaryReference Properties

The IncludeStatus Property is a Boolean indicating how the StatusCodes of the serialized Variables are serialized themselves.

If True, the SerializationFieldDataType of the Variable shall always be a Structure DataType which shall contain a “Value” field for the Value of the Variable and a “Status” field for the statusCode. The DataType of the field shall be StatusCode. If False, the DataType representing the Variable shall contain no “Status” field.

The IncludeSourceTimestamp Property is a Boolean indicating how the sourceTimestamps of the serialized Variables are serialized themselves.

If True, the SerializationFieldDataType of the Variable shall always be a Structure DataType which shall contain a “Value” field for the Value of the Variable and a “SourceTimestamp” field for the sourceTimestamp. The DataType of the field shall be UtcTime. If False, the DataType representing the Variable shall contain no “SourceTimestamp” field.

The IncludeDictionaryReference Property is a Boolean indicating whether the HasDictionaryEntry References of the serialized Variables are included into the SerializationValue.

If True, the SerializationFieldDataType of the Variable shall be structure DataType which shall contain a “Value” field for the Value of the Variable and a “DictionaryReferences” field. The DataType of the field shall be an array of QualifiedName. The array shall have as many elements as there are HasDictionaryEntry References (see OPC 10000-19) with the Variable as SourceNode. The QualifiedName element shall contain the NodeId of the referenced DictionaryEntryType Object.

If False, the structure DataType representing the Variable shall contain no “DictionaryReferences” field.

Figure 11 demonstrates the effect of the IncludeStatus, IncludeSourceTimestamp and IncludeDictionaryReference Properties on the SerializationFieldDataTypes used for the serialization of a Variable without child nodes.

Figure 12 shows the effect of the IncludeStatus, IncludeSourceTimestamp and IncludeDictionaryReference Properties on the SerializationFieldDataTypes used for the serialization of a Variable with one Variable as child node.

6.4 SerializationValue Structure rules

The following rules describe how the SerializationScope and the SerializationProperties impact the layout of the SerializationFieldDataType.

6.4.1 SerializationFieldDataType of Variables

If Variables are serialized, the Value of the Variable is mapped also into the SerializationValue DataType of the SerializedData Variable. The Value is inserted as field into the Structure DataType of the SerializedData Variable which has the SerializationFieldDataType of the Variable.

6.4.2 SerializationFieldDataType of Variables without Children

If the Variable has no children, the Variable is represented by a single Structure field with the BrowseName of the Variable as field name. The SerializationFieldDataType of the Variable equals the DataType of the Variable. As shown in Figure 11, the Variable V1 is mapped into the Structure field V1 with the SerializationFieldDataType V1DataType (left column with IncludeStatus, IncludeSourceTimestamp and IncludeDictionaryReference Properties equal to False).

If some of the IncludeStatus, IncludeSourceTimestamp and IncludeDictionaryReference Properties (“Include-Properties”) are True, the Variable is also represented by a single Structure field, but the SerializationFieldDataType is a Structure DataType.

This Structure contains a “Value” field which has the same DataType as the Value of the Variable. Dependent on the Value of the “Include-Properties”, the Structure can contain a “Status” field with the DataType StatusCode, a “SourceTimestamp” field with the DataType UtcTime and an entry in the DictionaryReferences array field as shown in Figure 11 (middle and right column, V1Type, examples for the IncludeStatus, IncludeSourceTimestamp and IncludeDictionaryReference Properties).

6.4.3 SerializationFieldDataType of Variables with Children

If the Variable has child nodes, the fields of the SerializationFieldDataType representing the Variable are generated as shown in Figure 12 for the V1 Variable (V1Type):

The Value of the Variable is mapped into a field with the name “Value” with the DataType of the Value of the V1 Variable.

A field with name “Children” is inserted after the “Value” field. Its DataType is a new Structure DataType containing as many fields as there are children of the serialized Variable. The name of each of those fields equals the BrowseName of the mapped child. Servers shall make sure that field names are unique (e.g., two BrowseNames can have the same text field but different namespaces). The SerializationFieldDataType of each of those fields equals the DataType of the mapped child Variable if the respective child is a “leaf” of the Object tree. This is the case for Properties and “childless” Variables (see Figure 12, left column, V1Type and V1ChildrenType with “Include-Properties” set to False). If the child Variable itself has child nodes, the SerializationFieldDataType of the field representing the Variable is a Structure DataType generated according to the same rules which were applied to the parent Variable (recursiveness).

If “Include-Properties” are True, the SerializationFieldDataType is always a Structure DataType and contains additional fields mapping the corresponding Properties as shown in Figure 12 (middle and right column, V1Type and V2Type, examples for IncludeStatus and IncludeSourceTimestamp Properties).

Figure 13, Figure 14 and Figure 15 demonstrate the SerializationFieldDataType generated if the “Include-Properties” (see 6.3.9) are set to False, which allows representing “leaves” of the Object tree as “simple” fields.

Figure 13 shows the SerializationFieldDataType for Variables with Properties and Variables.

6.4.4 SerializationFieldDataType of Objects with children

The rules described above apply in the same way to Objects, with the exception that the Object level itself has no Value and therefore the SerializationFieldDataTypes do not contain a “Value”-field. Figure 14 shows the SerializationFieldDataType needed to serialize an Object and its children. The fields representing the children are inserted directly into the SerializationFieldDataType of the Object, without an intermediate “Children” structure used in case of Variables with children.

The SerializationFieldDataType for Variables with children are created according to chapter 6.4.3

6.4.5 SerializationFieldDataType of nested Object subtrees

Figure 15 shows a nested subtree where members of the subtree are again subtrees. Each subtree has its own DataTypeDefinition Node. Since “Variable1” has no children, it is mapped to the field “Variable1” with the same DataType. Since “Object1” has children, it is mapped to the “Object1DataType” Structure DataType with the field “Property1”.

6.5 HasSerializationEntity ReferenceType

The HasSerializationEntity ReferenceType is a concrete ReferenceType that can be used directly. It is a subtype of the HierarchicalReferences ReferenceType.

The semantic of this ReferenceType is to reference the serialized data of the SourceNode of the Reference.

The SourceNode of this ReferenceType shall be an Object, ObjectType, Variable or VariableType. The TargetNode of this ReferenceType shall be an Object of SerializationEntityType or a subtype.

The HasSerializationEntity is formally defined in Table 6.