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.

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

Table 182 – 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.

ActionRequest

ua-action-request

Defined in 7.2.5.6.2.

ActionResponse

ua-action-response

Defined in 7.2.5.6.3.

ActionMetaData

ua-action-metadata

Defined in 7.2.5.5.7.

ActionResponder

ua-action-responder

Defined in 7.2.5.5.8.

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

Table 183 – 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) or a JSON object if SingleDataSetMessage is set.

This value is always present.

All fields with a concrete DataType defined are encoded using CompactEncoding 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.

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

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 184 – 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 34.

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 VerboseEncoding if FieldEncoding1 is FALSE and CompactEncoding if FieldEncoding1 is TRUE. See the OPC UA JSON Data encodings 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 DataSetFieldContentMask, the FieldEncoding1 and the FieldEncoding2 flag in the DataSetMessageContentMask. The resulting JSON encoding is defined in Table 111.

If the DataSetFieldContentMask is 0x0 or 0x20 (only the RawData flag is set), the DataSetMessage fields are encoded as Variant. Otherwise the fields are encoded as DataValue. If the KeyFrameCount is 0, the DataSetFieldContentMask shall be 0x0 or 0x20.

If the FieldEncoding1 is FALSE in the DataSetMessageContentMask, the Variant at the top level of a field is encoded as a JSON value containing only the value of the Body field. If this Variant contains an ExtensionObject, the ExtensionObject shall be encoded as a Structure without the UaTypeId field. This also applies to the Variant in a DataValue at the top level of a field.

If the RawData flag is set, the UaType fields of Variants and the UaTypeId fields of ExtensionObjects are always omitted.

If the RawData flag ist set, it is not possible to reverse the data in a DataSetReader in the following cases.

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.

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

Table 185 – 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.

WriterGroupName

String

The name of the WriterGroup which created the NetworkMessage.

This value is mandatory.

DataSetWriterName

String

The name of the DataSetWriter.

This value is mandatory.

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 CompactEncoding OPC UA JSON Data Encoding defined in OPC 10000-6.

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

Table 186 – 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.

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

Table 187 – 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.

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

Table 188 – 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 PubSubConnection. 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.

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

Table 189 – 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.

A NetworkMessage with MessageType ActionMetaData is a JSON object with the fields defined in Table 190.

Table 190 – JSON ActionMetaData definition

Name

Type

Description

MessageId

String

A globally unique identifier for the message. This value is mandatory.

MessageType

String

This value shall be “ua-action-metadata”. This value is mandatory.

PublisherId

String

The Publisher that sent the message. This value is mandatory.

DataSetWriterId

UInt16

An identifier for DataSetWriter which published the metadata.

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.

ActionTargets

ActionTargetDataType[]

The set of Action targets that may be executed.

If an Action target is mapped to a Method of an Object in an OPC UA Server, then the related Object and Method are defined by the corresponding entry in the ActionMethods array.

The ActionTargetId in the ActionTargetDataType is used to address the Method referenced by the ActionMethodDataType.

Request

DataSetMetaDataType

The structure and content of the ActionRequest message.

The name of the Action is defined by the Name field in the DataSetMetaDataType.

Response

DataSetMetaDataType

The structure and content of the ActionResponse message.

The fields Name and ConfigurationVersion of the Request and the Response DataSetMetaDataType shall have equal values.

ActionMethods

ActionMethodDataType[]

The optional array of Action sources. If the source information is provided, the array shall match the size and order of the ActionTargets.

A NetworkMessage with MessageType ActionResponder is a JSON object with the fields defined in Table 190.

Table 191 – JSON ActionResponder definition

Name

Type

Description

MessageId

String

A globally unique identifier for the message.

This value is mandatory.

MessageType

String

This value shall be “ua-action-responder”.

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.

Only DataSetWriters used for Actions are included. All WriterGroups and DataSetWriters not used for Actions shall be excluded.

The ReaderGroup lists in PubSubConnectionDataType shall be empty.

The configuration properties shall not be included in the PubSubConnectionDataType, WriterGroupDataType and DataSetWriterDataType.

Each JSON Action NetworkMessage can contain one or more JSON Request or Response messages. A JSON Action NetworkMessage is a JSON object with the fields defined in Table 192.

Table 192 – JSON Action NetworkMessage definition

Name

Type

Description

MessageId

String

A globally unique identifier for the message. This value is mandatory.

MessageType

String

This value shall be “ua-action-request” Request messages or “ua-action-response” for Response messages.

This value is mandatory.

PublisherId

String

The PublisherId of the Responder for the “ua-action-request” and “ua-action-response” message.

This value is mandatory.

Timestamp

UtcTime

When the message was first sent to the Middleware.

This value is mandatory.

ResponseAddress

String

The address used to send the Response messages. The handling of the ResponseAddress and default values are defined for the different transport protocol mappings.

This value is mandatory for Request messages.

This value shall be omitted for Response message.

CorrelationData

ByteString

Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message.

The value may be provided in the Request message.

The value shall be provided in the Response message if it was included in the Request message.

RequestorId

String

The PublisherId of the Requestor for the “ua-action-request” and “ua-action-response” message.

This value is mandatory.

TimeoutHint

Duration

The timeout used by the Requestor to wait for a Response messages and by the Responder to stop processing the request.

This value is mandatory for the Request message.

This value is not used for Response messages.

Message

*

A JSON array of JSON ActionRequest or JSON ActionResponse messages.

This value is mandatory.

It contains one or more ActionRequest or ActionResponse messages with a layout defined by the Request and Response fields in the ActionMetaData.

The Action execution sequences and execution related request and response message values are defined in 6.2.11.2.

A NetworkMessage with MessageType “ua-action-request” contains a JSON array with ActionRequest messages. A ActionRequest message is a JSON object with the fields defined in Table 193.

Table 193 – JSON ActionRequest definition

Name

Type

Description

DataSetWriterId

UInt16

An identifier for DataSetWriter in the Responder which creates the Response.

This value is mandatory.

It is unique within the scope of a Responder.

ActionTargetId

UInt16

The numeric identifier assigned to the Action target which is unique within one ActionMetaData.

This value is mandatory.

It is used to address the Action target in combination with the PublisherId and the DataSetWriterId.

DataSetWriterName

String

The name of the DataSetWriter which created the DataSetMessage.

The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

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.

MetaDataVersion

ConfigurationVersionDataType

The version of the ActionMetaData Request 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 ActionMetaData Request 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 Request was created.

The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

MessageType

String

“ua-action-request”

The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

RequestId

UInt16

Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message.

ActionState

ActionState

Specifies the expected Action state on Responder side.

The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2.

Payload

Object

A JSON object containing the name-value pairs specified by the ActionMetaData.

The format of the value depends on the DataType of the field and the flags specified by the DataSetFieldContentMask.

Only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used.

The encoding rules defined in 7.2.5.4 for DataSetMessages also apply to the ActionRequest message. The DataValue encoding shall not be used in ActionRequest message. The RawData flag shall be FALSE for ActionRequest messages.

A NetworkMessage with MessageType “ua-action-response” contains a JSON array with ActionResponse messages. An ActionResponse message is a JSON object with the fields defined in Table 194.

Table 194 – JSON ActionResponse definition

Name

Type

Description

DataSetWriterId

UInt16

An identifier for DataSetWriter which created the Response.

This value is mandatory.

It is unique within the scope of a Responder.

ActionTargetId

UInt16

The numeric identifier assigned to the Action target which is unique within one ActionMetaData.

This value is mandatory.

It is used to address the Action target in combination with the PublisherId and the DataSetWriterId.

DataSetWriterName

String

The name of the DataSetWriter which created the DataSetMessage.

The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

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.

MetaDataVersion

ConfigurationVersionDataType

The version of the ActionMetaData Response 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 ActionMetaData Response 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 result of the Action Response.

The value shall be present.

MessageType

String

“ua-action-response”.

The presence of the value depends on the setting in the JsonDataSetMessageContentMask.

RequestId

UInt16

Data provided by the Requestor in the Request message that is returned to the Requestor in the Response message.

ActionState

ActionState

The current state of this currently running Action.

The details for the use of this value and the relation to other values for a Action execution is defined in 6.2.11.2.

Payload

Object

A JSON object containing the name-value pairs specified by the ActionMetaData.

The format of the value depends on the DataType of the field and the flags specified by the DataSetFieldContentMask.

Only Variant or RawData encoding shall be allowed. If bits for DataValue encoding are set, the Variant encoding shall be used.

The encoding rules defined in 7.2.5.4 for DataSetMessages also apply to the ActionResponse message. The DataValue encoding shall not be used in ActionResponse message. The RawData flag shall be FALSE for ActionResponse messages.