UA Part 14: PubSub - 7.2.5 JSON message mapping

The JSON message mapping uses the OPC UA JSON encoding defined in OPC 10000-6. If an ExtensionObject is encoded, the TypeId shall be the DataType NodeId of the contained structure.

JSON is a format that uses human readable text. It is defined in IETF RFC 8259.

The JSON based message mapping allows OPC UA Applications to interoperate with web and enterprise software that use this format and do not understand OPC UA specific encodings.

The JSON message mapping defines different optional header fields, variations of field settings and different message types. Available layouts with standard settings and the corresponding URI Strings for JSON are defined in A.3.

7.2.5.2 MessageType mapping

The mapping of MessageTypes to JSON NetworkMessage MessageTypes and the reference to the detailed definition is listed in Table 162.

Table 162 – JSON NetworkMessage MessageType mapping

MessageType	JSON NetworkMessage MessageType	Specification Reference
DataSetMessage	ua-data	Defined in 7.2.5.3 and 7.2.5.4.
DataSetMetaData	ua-metadata	Defined in 7.2.5.5.2.
ApplicationDescription	ua-application	Defined in 7.2.5.5.3.
ServerEndpoints	ua-endpoints	Defined in 7.2.5.5.4.
Status	ua-status	Defined in 7.2.5.5.5.
PubSubConnection	ua-connection	Defined in 7.2.5.5.6.

7.2.5.3 NetworkMessage containing DataSetMessages

Each JSON NetworkMessage can contain one or more JSON DataSetMessages. The JSON NetworkMessage is a JSON object with the fields defined in Table 163.

Table 163 – JSON NetworkMessage definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. The unique identifier can be created by converting a Guid to a String or through another algorithm that creates a unique string. This value is always present.
MessageType	String	This value shall be “ua-data” for NetworkMessages containing DataSetMessages. This value is always present.
PublisherId	String	A unique identifier for the Publisher. It identifies the source of the message. The presence of the value depends on the setting in the JsonNetworkMessageContentMask. The source is the PublisherId on a PubSubConnection (see 6.2.7.1). If the PublisherId is a UInteger, the UInteger value is converted to a String without leading zeros.
WriterGroupName	String	The name of the WriterGroup which created the NetworkMessage. The presence of the value depends on the setting in the JsonNetworkMessageContentMask.
DataSetClassId	String	The DataSetClassId associated with the DataSets in the NetworkMessage. The DataSetClassId is a Guid and shall be converted to a String. The presence of the value depends on the setting in the JsonNetworkMessageContentMask. If specified, all DataSetMessages in the NetworkMessage shall have the same DataSetClassId. The source is the DataSetClassId on the PublishedDataSet (see 6.2.3.3) associated with the DataSetWriters that produced the DataSetMessages.
Messages	*	A JSON array of JSON DataSetMessages (see 7.2.5.4). This value is always present.

All fields with a concrete DataType defined are encoded using reversible OPC UA JSON Data Encoding defined in OPC 10000-6.

The fields in the JSON NetworkMessage are controlled by the NetworkMessageContentMask of the JSON NetworkMessage mapping(see 6.3.2.1.1).

If the NetworkMessageHeader bit of the NetworkMessageContentMask is not set, the NetworkMessage is the contents of the Messages field (e.g. a JSON array of DataSetMessages).

If the DataSetMessageHeader bit of the NetworkMessageContentMask is not set, the content of the Messages field is an array of content from the Payload field for each DataSetMessage (see 7.2.5.4).

If the SingleDataSetMessage bit of the NetworkMessageContentMask is set, the content of the Messages field is a JSON object containing a single DataSetMessage.

If the NetworkMessageHeader and the DataSetMessageHeader bits are not set and SingleDataSetMessage bit is set, the NetworkMessage is a JSON object containing the set of name/value pairs defined for a single DataSet.

If the JSON encoded NetworkMessage size exceeds the Broker limits the message is dropped and a PubSubTransportLimitsExceeded Event is reported.

7.2.5.4 DataSetMessage

A DataSetMessage is produced by a DataSetWriter and contains list of name/value pairs which are specified by the PublishedDataSet associated with the DataSetWriter. The contents of the DataSetMessage are formally described by a DataSetMetaData Object. A DataSetMessage is a JSON object with the fields defined in Table 164.

A key frame DataSetMessage or an event based DataSetMessage contains name and value for all fields of the DataSet.

A delta frame DataSetMessage contains only name and value for the changed fields.

DataSetWriters may periodically provide keep-alive messages which are DataSetMessages without any Payload field.

Table 164 – JSON DataSetMessage definition

Name	Type	Description
DataSetWriterId	UInt16	An identifier for DataSetWriter which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. It is unique within the scope of a Publisher.
DataSetWriterName	String	The name of the DataSetWriter which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
PublisherId	String	A unique identifier for the Publisher. It identifies the source of the message. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The source is the PublisherId on a PubSubConnection (see 6.2.7.1). If the PublisherId is a UInteger, the UInteger value is converted to a String without leading zeros. The value shall be omitted if the NetworkMessage header is present.
WriterGroupName	String	The name of the WriterGroup which created the DataSetMessage. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the WriterGroupName is contained in the NetworkMessage header.
SequenceNumber	UInt32	Sequence number for each new DataSetMessage as defined in 7.2.3. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. For the DataSetMessage MessageType “ua-keepalive”, the sequence number provides the next expected sequence number for the DataSetWriter.
MetaDataVersion	ConfigurationVersionDataType	The version of the DataSetMetaData which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
MinorVersion	VersionTime	The minor version of the DataSetMetaData which describes the contents of the Payload. The presence of the value depends on the setting in the JsonDataSetMessageContentMask. The value shall be omitted if the MetaDataVersion is contained in the DataSetMessage header.
Timestamp	DateTime	The time the DataSetMessage was created. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
Status	StatusCode	The overall status of the DataSetMessage. The dependencies to the status of DataSet fields are defined in Table 26. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
MessageType	String	Possible values are “ua-keyframe”, “ua-deltaframe”, “ua-event” and “ua-keepalive”. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
Payload	Object	A JSON object containing the name-value pairs specified by the PublishedDataSet. The format of the value depends on the DataType of the field and the flags specified by the DataSetFieldContentMask. For MessageType “ua-event”, only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used.

All fields with a concrete DataType are encoded using reversible OPC UA JSON Data Encoding defined in OPC 10000-6.

The fields in the DataSetMessage are specified by the DataSetFieldContentMask in the DataSetWriter parameters.

The format of the field values in the Payload depend on the setting of the ReversibleFieldEncoding flag in the DataSetMessageContentMask.

7.2.5.5 Discovery Messages

7.2.5.5.1 General

The JSON message mapping defines optional discovery messages. The main purpose is the exchange of additional information not contained in the DataSetMessages like Properties for the DataSet fields.

7.2.5.5.2 DataSetMetaData

DataSetMetaData describe the content of DataSetMessages published by a DataSetWriter. More specifically, it specifies the names and data types of the values that shall appear in the Payload of a DataSetMessage.

When the DataSetMetaData of a DataSet changes, the DataSetWriter may be configured to publish the updated value through the mechanism defined by the transport protocol mapping.

The DataSetWriterId and Version fields in a DataSetMessage are used to correlate a DataSetMessage with a DataSetMetaData.

A NetworkMessage with MessageType DataSetMetaData is a JSON object with the fields defined in Table 165.

Table 165 – JSON DataSetMetaData definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. This value is mandatory.
MessageType	String	This value shall be “ua-metadata”. This value is mandatory.
PublisherId	String	A unique identifier for the Publisher. It identifies the source of the message. This value is mandatory.
DataSetWriterId	UInt16	An identifier for DataSetWriter which published the DataSetMetaData. This value is mandatory. It is unique within the scope of a Publisher.
DataSetWriterName	String	The name of the DataSetWriter. This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
Timestamp	UtcTime	When the message was first sent to the middleware. This value is mandatory.
MetaData	DataSetMetaDataType	The metadata as defined in 6.2.3.2.3. This value is mandatory.

All fields with a concrete DataType are encoded using reversible OPC UA JSON Data Encoding defined in OPC 10000-6.

7.2.5.5.3 ApplicationDescription

A NetworkMessage with MessageType ApplicationDescription is a JSON object with the fields defined in Table 166.

Table 166 – JSON ApplicationDescription definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. This value is mandatory.
MessageType	String	This value shall be “ua-application”. This value is mandatory.
PublisherId	String	The Publisher that sent the message. This value is mandatory.
Timestamp	UtcTime	When the message was first sent to the middleware. This value is mandatory.
Description	ApplicationDescription	The ApplicationDescription Structure is described in OPC 10000-4.
ServerCapabilities	String []	The set of Server capabilities supported by the Server associated with the Publisher. The set of allowed Server capabilities are defined in OPC 10000-12.

7.2.5.5.4 ServerEndpoints

A NetworkMessage with MessageType ServerEndpoints is a JSON object with the fields defined in Table 167.

Table 167 – JSON ServerEndpoints definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. This value is mandatory.
MessageType	String	This value shall be “ua-endpoints”. This value is mandatory.
PublisherId	String	The Publisher that sent the message. This value is mandatory.
Timestamp	UtcTime	When the message was first sent to the middleware. This value is mandatory.
Endpoints	EndpointDescription []	The list of Server Endpoints of the OPC UA Application. The EndpointDescription Structure is described in OPC 10000-4.

7.2.5.5.5 Status

A NetworkMessage with MessageType Status is a JSON object with the fields defined in Table 168.

Table 168 – JSON Status definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. This value is mandatory.
MessageType	String	This value shall be “ua-status”. This value is mandatory.
PublisherId	String	The Publisher that sent the message. This value is mandatory.
Timestamp	UtcTime	When the message was sent to the Middleware. Mandatory if IsCyclic=TRUE. The field is omitted if IsCyclic=FALSE.
IsCyclic	Boolean	If TRUE the Publisher periodically updates the status. If FALSE the Middleware is responsible for detecting changes to the status.
Status	PubSubState	The current state of the Publisher. This value is mandatory.
NextReportTime	UtcTime	When the Publisher is expected to send the next update. Mandatory if IsCyclic=TRUE. The field is omitted if IsCyclic=FALSE.

IsCyclic is set to FALSE if a PublisherId is used exclusively by a single application and the Message Oriented Middleware can detect when Publishers go offline. In these cases, the Publisher sends updates only when its state changes and the Message Oriented Middleware will send an update with PubSubState Error if the Publisher goes offline. The status message from the Message Oriented Middleware does not contain the Timestamp.

If IsCyclic is set to TRUE the Publisher only reports when it is Operational. The NextReportTime indicates when the Publisher is expected to send an update. If the Subscriber does not receive updates and the NextReportTime is a reasonable time in the past, the Subscriber assumes the PubSubState Error.

7.2.5.5.6 PubSubConnection

A NetworkMessage with MessageType PubSubConnection is a JSON object with the fields defined in Table 169.

Table 169 – JSON PubSubConnection definition

Name	Type	Description
MessageId	String	A globally unique identifier for the message. This value is mandatory.
MessageType	String	This value shall be “ua-connection”. This value is mandatory.
PublisherId	String	The Publisher that sent the message. This value is mandatory.
Timestamp	UtcTime	When the message was first sent to the Middleware. This value is mandatory.
Connection	PubSubConnectionDataType	The PubSubConnectionDataType Structure is defined in 6.2.7.5.1. The ReaderGroup lists and the Address in PubSubConnectionDataType shall be empty. The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType.