7 PubSub mappings ToC Previous Next

7.2 Message mappings ToC Previous Next

7.2.3 JSON message mapping ToC Previous Next

7.2.3.1 General ToC

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

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.

7.2.3.2 NetworkMessage ToC

Each JSON NetworkMessage contains one or more JSON DataSetMessages. The JSON NetworkMessage is a JSON object with the fields defined in Table 158.

Table 158 – 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 mandatory.
MessageType String    This value shall be “ua-data”.This value is mandatory.
PublisherId String    A unique identifier for the Publisher. It identifies the source of the message.    This value is optional. 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.
DataSetClassId String    The DataSetClassId associated with the DataSets in the NetworkMessage. The DataSetClassId is a Guid and shall be converted to a String.   This value is optional. 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.3.3).This value is mandatory.

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

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.3.3 DataSetMessage ToC

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

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 159 – JSON DataSetMessage definition

Name Type Description
DataSetWriterId UInt16    An identifier for DataSetWriter which created the DataSetMessage.    This value is optional. 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 value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
SequenceNumber UInt32    Sequence number, incremented by exactly one, assigned to the DataSetMessage by the DataSetWriter.    This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.Subscribers   shall discard the records they keep for sequence numbers if they do not receive messages with the expected SequenceNumber for two times the keep alive time to deal with Publishers or brokers that are out of service and were not able to continue from the last used SequenceNumber.
MetaDataVersion ConfigurationVersionDataType    The version of the DataSetMetaData which describes the contents of the Payload. This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
Timestamp DateTime    A timestamp which applies to all values contained in the DataSetMessage. This value is optional. The presence of the value depends on the setting in the JsonDataSetMessageContentMask.
Status StatusCode    A status code which applies to all values contained in the DataSetMessage. This value is optional. 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.

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.3.4 Discovery Messages ToC

7.2.3.4.1 General ToC

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

7.2.3.4.2 DataSetMetaData ToC

DataSetMetaData describe the content a DataSet 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 DataSetMetaData is a JSON object with the fields defined in Table 160.

Table 160 – 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.
MetaData DataSetMetaDataType    The metadata as defined in 6.2.3.2.2.This value is mandatory.
DataSetWriterName String The name of the DataSetWriter.

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

Previous Next