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.