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.

Figure 6 – Example: Instance-specific serialization for the Object “MyObject”

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.

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.

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.

Figure 7 – SerializationEntityType components

Table 1 – SerializationEntityType definition

Attribute		Value
BrowseName		SerializationEntityType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the BaseObjectType defined in OPC 10000-5
HasComponent	Variable		SerializedData	Structure	BaseDataVariableType	M
Serialization filter Properties
HasProperty	Variable		IncludeReferenceTypes	NodeId[]	PropertyType	O,R
HasProperty	Variable		ExcludeReferenceTypes	NodeId[]	PropertyType	O,R
HasProperty	Variable		SerializationDepth	UInt16	PropertyType	O,R
HasProperty	Variable		ConsiderSubElementSerializationProperties	Boolean	PropertyType	O,R
HasProperty	Variable		CustomMetaDataProperties	KeyValuePair[]	PropertyType	O,R
HasProperty	Variable		CustomMetaDataRef	NodeId	PropertyType	O,R
HasProperty	Variable		IncludeStatus	Boolean	PropertyType	O,R
HasProperty	Variable		IncludeSourceTimestamp	Boolean	PropertyType	O,R
HasProperty	Variable		IncludeDictionaryReference	Boolean	PropertyType	O,R
Configuration of the SerializationEntity (requires locking)
HasComponent	Method		ConfigureSerialization	see 6.3.3		O
Conformance Units
ObjectSerialization Base

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.

Table 2 – Default values for serialization filter Properties

Property Name	Default setting
IncludeReferenceTypes	[HasChild]
ExcludeReferenceTypes	[] //empty array
SerializationDepth	1
ConsiderSubElementSerializationProperties	False
CustomMetaDataProperties	[] //empty array
CustomMetaDataRef	{0}
IncludeStatus	False
IncludeSourceTimestamp	False
IncludeDictionaryReference	False

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.

Note 1: It may be useful to use GUID NodeIds due to the dynamic of the process.

Note 2: It is recommended, that Servers persist DataType NodeIds so that these NodeIds remain in place after restart, if the SerializationScope has not changed.

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

);

Table 3 – ConfigureSerialization Method arguments

Argument	Description
SerializationFilterProperties	Array of KeyValuePair Structures containing the desired settings. The key field of each Structure contains the BrowseName of a serialization filter Property. The value field contains the desired value to set for this component and must have the same DataType as the serialization filter Property. A Property can be reset by setting the default Value for the Property.
Results	List of results for the Properties to set (see below). The size and order of the list matches the size and order of the SerializationFilterProperties argument. There is one entry in this list for each Property contained in the SerializationFilterProperties argument. This array is empty if the Method execution was successful (Method result code Good). Possible result values. 0 – OK -1 – E_InvalidProperty – the Property name is unknown -2 – E_Duplicate – the Property is not unique in SerializationFilterProperties -3 – E_NotConfigurable – the Property cannot be changed -4 – E_InvalidType – the DataType is not the same as the one of the Property -5 – E_UnknownValue – the value provided is not appropriate for the Property -6 – E_InvalidSetting – the value provided is not allowed as serialization filter An example is that non-hierarchical References are not allowed to be included

Table 4 – ConfigureSerialization Method AddressSpace definition

Attribute	Value
BrowseName	ConfigureSerialization
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
HasProperty	Variable	InputArguments	Argument[]	PropertyType	M
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	M
Conformance Units
ObjectSerialization Configuration Support

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.

Table 5 – Possible Method Result Codes

Result Code	Description
Good	The Method execution was successful. The Results array is empty.
Uncertain	The Server is not able to apply the requested changes due to invalid parameters. The Results argument provides more details.
Bad_InvalidArgument	The SerializationFilterProperties argument array is empty.
Bad_Locked	The SerializationEntity is locked by a different Client’s Session.
Bad_RequiresLock	The SerializationEntity is not locked. Clients must lock the SerializationEntity before invoking a Method.
Bad_UserAccessDenied	The user has not the right to execute the Method.
Bad_UnexpectedError	The Server is not able to execute the function because an unexpected error occurred.

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

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.

Figure 8 – ReferenceType Properties Usage

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.

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”.

Figure 9 – ConsiderSubElementSerializationProperties Example

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.

Figure 10 – CustomMetaDataProperties example

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.

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.

Note: As all metadata created by the PubSub mechanism are omitted, the metadata does not contain type information.

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.

Note: Setting these Properties to False leads to a leaner result when the JSON EncodingFormat “compact” is used.

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

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.

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).

Figure 11 – IncludeStatus and IncludeSourceTimestamp Properties Example for Variable without child Node

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).

Note: The SerializationValue DataType for a SerializationScope only consisting of one Variable and a SerializationScope consisting of one Object with this Variable as child Node are identical.

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 12 – IncludeStatus and IncludeSourceTimestamp Properties Example with child Node

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.

Figure 13 – Serialization of Variables 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

Figure 14 – Serialization of Objects with children

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”.

Figure 15 – Nested subtrees represented by one SerializationValue

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.

Table 6 – HasSerializationEntity definition

Attributes	Value
BrowseName	HasSerializationEntity
InverseName	SerializationEntityOf
Symmetric	False
IsAbstract	False
References	NodeClass	BrowseName	Comment
Subtype of HierarchicalReferences defined in OPC 10000-5.
Conformance Units
ObjectSerialization Base