A.3 JSON Header Layouts

A.3.1 DataSets for examples

The following DataSets are used for the following JSON message examples.

Table A.13 shows the field for example DataSet1.

Table A.14 shows the field for example DataSet2.

Table A.15 shows the field for example DataSet3.

The following example shows the DataSetMetaData message for DataSet1.

{
  "MessageId": "66D65CA4-92EE-4195-9867-E6E27794B692",
  "MessageType": "ua-metadata",
  "PublisherId": "MyPublisher",
  "DataSetWriterId": 101,
  "MetaData": {
    "Name": "DataSet1",
    "Fields": [
      {
        "Name": "Active",
        "FieldFlags": 0,
        "BuiltInType": 1,
        "DataType": "i=1",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "f355bfe8-d5c0-4073-aa89-c8d9d9f8c0c4"
      },
      {
        "Name": "Temperature",
        "FieldFlags": 0,
        "BuiltInType": 11,
        "DataType": "i=11",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "4b91e1cc-61f5-411a-9fb3-ea9087d2154c"
      },
      {
        "Name": "Counter",
        "FieldFlags": 0,
        "BuiltInType": 7,
        "DataType": "i=7",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "885d0b3b-8a83-41ae-882a-3a528041140f"
      },
      {
        "Name": "AdditionalInfo",
        "FieldFlags": 0,
        "BuiltInType": 12,
        "DataType": "i=12",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "b020c4a8-c427-4d33-83ea-b0f437a9c6ea"
      }
    ],
    "DataSetClassId": "e95258a4-0b50-41b0-9f37-505e90565584",
    "ConfigurationVersion": {"MajorVersion": 672338910, "MinorVersion": 672341762}
  },
  "DataSetWriterName": "Writer101"
}

The following example shows the DataSetMetaData message for DataSet2.

{
  "MessageId": "66D65CA4-92EE-4195-9867-E6E27794B692",
  "MessageType": "ua-metadata",
  "PublisherId": "MyPublisher",
  "DataSetWriterId": 102,
  "MetaData": {
    "StructureDataTypes": [
      {
        "DataTypeId": "nsu=http://test.org/UA/Data/;s=CoordinateDataType",
        "Name": "nsu=http://test.org/UA/Data/;CoordinateDataType",
        "StructureDefinition": {
          "DefaultEncodingId": "nsu=http://test.org/UA/Data/;i=24351",
          "BaseDataType": "i=22",
          "StructureType": 0,
          "Fields": [
            {
              "Name": "X",
              "Description": {"Text": "The X coordinate."},
              "DataType": "i=10",
              "ValueRank": -1,
              "MaxStringLength": 0,
              "IsOptional": false
            },
            {
              "Name": "Y",
              "Description": {"Text": "The Y coordinate."},
              "DataType": "i=10",
              "ValueRank": -1,
              "MaxStringLength": 0,
              "IsOptional": false
            }
          ]
        }
      }
    ],
    "Name": "DataSet2",
    "Fields": [
      {
        "Name": "LocationName",
        "FieldFlags": 0,
        "BuiltInType": 12,
        "DataType": "i=12",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "8968e376-e281-47bf-b621-e1fb710c8954"
      },
      {
        "Name": "Coordinate",
        "FieldFlags": 0,
        "BuiltInType": 22,
        "DataType": "nsu=http://test.org/UA/Data/;s=CoordinateDataType",
        "ValueRank": -1,
        "MaxStringLength": 0,
        "DataSetFieldId": "4a1a1f3c-76c0-46ac-92bd-b02bfbe59dcf"
      },
      {
        "Name": "Measurements",
        "FieldFlags": 0,
        "BuiltInType": 6,
        "DataType": "i=6",
        "ValueRank": 1,
        "MaxStringLength": 0,
        "DataSetFieldId": "7d177014-32de-421e-a0a3-bc48ede8ac9d"
      }
    ],
    "DataSetClassId": "4f457b18-32f8-48a5-a6f0-18ae5ebdc7f4",
    "ConfigurationVersion": {"MajorVersion": 672338910, "MinorVersion": 672341762}
  },
  "DataSetWriterName": "Writer102"
}

A.3.2 JSON message headers for minimal messages

A.3.2.1 Motivation

One of the use cases for PubSub is the publication of data to IT applications through a topic or message queue where the IT application does not have any knowledge about OPC UA. In such a use case, the messages that are sent to the message queue can only contain one DataSetMessage and there should be no OPC UA specific information or header.

The header layout described in this section is optimized for this use case.

This header layout cannot be used for Actions.

A.3.2.2 Overview

A minimal message has the following settings:

Each NetworkMessage contains one DataSetMessage

The NetworkMessage header is not included

The DataSetMessage header is not included

The DataSet field encoding is set to VerboseEncoding with RawData.

A.3.2.3 Header layout URI

The header layout URI for the mimimal layout as specified in A.3.2.4 is

A.3.2.4 Configuration parameters

Table A.16 defines the values for the WriterGroup configuration parameters representing this layout.

Table A.17 defines the values for the DataSetWriter configuration parameters representing this layout.

A.3.2.5 Examples

Example for DataSet1.

{
  "Active":true,
  "Temperature":25.5,
  "Counter":0,
  "AdditionalInfo":"The system is running normally (1)"
}

Example for DataSet2.

{
  "LocationName":"Building A",
  "Coordinate":
  {
    "X":0,
    "Y":0.2
  },
  "Measurements":
  [
    20030,
    20020,
    20010
  ]
}

Example for DataSet3.

{
  "BooleanValue":false,
  "Int32Value":0,
  "Int64Value":"1",
  "UInt32Value":1,
  "UInt64Value":"1",
  "DoubleValue":0.5,
  "DateTimeValue":"2021-09-14T07:14:30Z",
  "StringValue":"String 1",
  "GuidValue":"ebfc352a-3142-4b99-9bbe-89a517d6a77e",
  "StatusCodeValue":
  {
    "Code":2147483648,
    "Symbol":"Bad"
  },
  "LocalizedTextValue":
  {
    "Locale":"en"
    "Text":"Localized text 1"
  },
  "ByteStringValue":"AAEC",
  "NodeIdValue":"nsu=http://test.org/UA/Data/Instance;s=Pipe001.Valve001.Input",
  "QualifiedNameValue":"nsu=http://test.org/UA/Data/;PipeX001"
}

A.3.3 JSON message headers for single DataSetMessage

A.3.3.1 Motivation

One of the use cases for PubSub is the publication of data to IT applications through a message queue where one DataSet is related to one message queue.

The IT application does not need to have knowledge about OPC UA but OPC UA specific header may be used for the message processing.

In such a use cases, the messages sent to a message queue can only contain one DataSetMessage but a OPC UA specific header is provided.

The header layout described in this section is optimized for this use case.

This header layout cannot be used for Actions.

A.3.3.2 Overview

A single DataSet message has the following settings:

Each NetworkMessage contains one DataSetMessage

The NetworkMessage header is not included

The DataSetMessage header is included, the header fields can be configured

The DataSet field encoding can be configured

A.3.3.3 Header layout URI

The header layout URI for the single DataSetMessage layout as specified in A.3.3.4 is

A.3.3.4 Configuration parameters

Table A.18 defines the values for the WriterGroup configuration parameters representing this layout.

Table A.19 defines the values for the DataSetWriter configuration parameters representing this layout.

A.3.3.5 Examples

Example for DataSet1 with all configurable JsonDataSetMessageContentMask flags set to false and no flags set for DataSetFieldContentMask.

{
  "PublisherId":"MyPublisher",
  "DataSetWriterId":101,
  "SequenceNumber":68468,
  "MinorVersion":672341762,
  "Timestamp":"2021-09-27T18:45:19.555Z",
  "Payload":
  {
    "Active":true,
    "Temperature":25.5,
    "Counter":0,
    "AdditionalInfo":"The system is running normally (1)"
  }
}

Example for DataSet2 with all configurable JsonDataSetMessageContentMask flags set to true and no flags set for DataSetFieldContentMask.

{
  "PublisherId":"MyPublisher",
  "DataSetWriterId":102,
  "SequenceNumber":25460,
  "MinorVersion":672341762,
  "Timestamp":"2021-09-27T18:45:19.555Z",
  "Status":{"Code":1073741824},
  "MessageType":"ua-keyframe",
  "WriterGroupName":"WriterGroup1",
  "DataSetWriterName":"Writer102",
  "Payload":
  {
    "LocationName":"Building A",
    "Coordinate":
    {
      "X":1,
      "Y":0.2
    },
    "Measurements":
    [
      20030,
      20020,
      20010
    ]
  }
}

Example for DataSet1 with all configurable JsonDataSetMessageContentMask flags set to false and with SourceTimestamp and StatusCode flags set in the DataSetFieldContentMask. The Status is omitted if the Code is 0.

{
  "PublisherId":"MyPublisher",
  "DataSetWriterId":101,
  "SequenceNumber":68468,
  "MinorVersion":672341762,
  "Timestamp":"2021-09-27T18:45:19.555Z",
  "Payload":
  {
    "Active":
    {
      "Value":true,
      "Status":{"Code":1073741824,"Symbol":"Uncertain"},
      "SourceTimestamp":"2021-09-27T11:32:38.349925Z"
    },
    "Temperature":
    {
      "Value":25.5,
      "SourceTimestamp":"2021-09-27T11:32:38.349925Z"
    },
    "Counter":
    {
      "Value":0,
      "SourceTimestamp":"2021-09-27T11:32:38.349925Z"
    },
    "AdditionalInfo":
    {
      "Value":"The system is running normally (1)",
      "SourceTimestamp":"2021-09-27T11:32:38.349925Z"
    }
  }
}

A.3.4 JSON message headers for multiple DataSetMessages

A.3.4.1 Motivation

One of the use cases is streaming of multiple different data and event DataSets through a single message queue for further processing in cloud applications.

Another use case is the execution of Actions.

The header layout described in this section is optimized for this use case.

In general this header layout is the most flexible option and should be used if only one header layout is preferred.

A.3.4.2 Overview

A minimal message has the following settings:

Each NetworkMessage contains an array of DataSetMessages

The NetworkMessage header is included, the header fields can be configured

The DataSetMessage header is included, the header fields can be configured

The DataSet field encoding can be configured

A.3.4.3 Header layout URI

The header layout URI for the multiple DataSetMessages layout as specified in A.3.4.4 is

A.3.4.4 Configuration parameters

Table A.20 defines the values for the WriterGroup configuration parameters representing this layout.

Table A.21 defines the values for the DataSetWriter configuration parameters representing this layout.

A.3.4.5 Examples

Example for DataSet1, DataSet2 and DataSet3 with all configurable JsonNetworkMessageContentMask and JsonDataSetMessageContentMask flags set to false and no flags set for DataSetFieldContentMask.

{
  "MessageId":"9279c0b3-da88-45a4-af74-451cebf82db0",
  "MessageType":"ua-data",
  "PublisherId":"MyPublisher",
  "Messages":
  [
    {
      "DataSetWriterId":101,
      "SequenceNumber":68468,
      "MinorVersion":672341762,
      "Timestamp":"2021-09-27T18:45:19.555Z",
      "Payload":
      {
        "Active":true,
        "Temperature":25.5,
        "Counter":0,
        "AdditionalInfo":"The system is running normally (1)"
      }
    },
    {
      "DataSetWriterId":102,
      "SequenceNumber":25460,
      "MinorVersion":672341762,
      "Timestamp":"2021-09-27T18:45:19.555Z",
      "Status":{"Code":1073741824},
      "Payload":
      {
        "LocationName":"Building A",
        "Coordinate":{"X":0,"Y":0.2},
        "Measurements":[20030,20020,20010]
      }
    },
    {
      "DataSetWriterId":103,
      "SequenceNumber":66915,
      "MinorVersion":672341762,
      "Timestamp":"2021-09-27T18:45:19.555Z",
      "Payload":
      {
        "BooleanValue":false,
        "Int32Value":0,
        "Int64Value":"1",
        "UInt32Value":1,
        "UInt64Value":"1",
        "DoubleValue":0.5,
        "DateTimeValue":"2021-09-14T07:14:30Z",
        "StringValue":"String 1",
        "GuidValue":"ebfc352a-3142-4b99-9bbe-89a517d6a77e",
        "StatusCodeValue":
        {
          "Code":2147483648,
          "Symbol":"Bad"
        },
        "LocalizedTextValue":
        {
          "Locale":"en"
          "Text":"Localized text 1"
        },
        "ByteStringValue":"AAEC",
        "NodeIdValue":"nsu=http://test.org/UA/Data/Instance;s=Pipe001.Valve001.Input",
        "QualifiedNameValue":"nsu=http://test.org/UA/Data/;PipeX001"
      }
    }
  ]
}