JSON Handling on the OAS Platform

The OAS Platform offers support for handling and manipulating JSON formatted data, which is crucial when integrating with many external systems, and for working within common Industrial IoT scenarios. Specifically, data passed between systems using the MQTT protocol, data sent and received from REST APIs, and even records stored in many database engines all use JSON formatting for hierarchical data. For more information on JSON, see our article “What is JSON?” on how it is structured and compared to other similar formats like XML.

JSON Data Type

Along with other standard Data Types such as Integer, String, Double Float, etc., OAS Tags can be assigned the JSON Data Type. This functions very much like a String Data Type except that internal JSON validation is performed whenever the value changes. This validation ensures that the value set on the Tag is properly formatted JSON. If the validation fails, the Tag will be marked as having Bad Quality. Your applications and other tags can be configured to respond to this state as needed, preventing invalid JSON from reaching other endpoints.

To set a Tag as a JSON Data Type, simply select JSON from the Data Type dropdown and click Apply Changes. Validation will immediately take effect. For all other operations such as Tag Calculations, you can reference a Tag of JSON Data Type just as you would with a String Tag. Values from JSON Tags can also be used in Text Calculations just as you would with String data.

Select JSON as a Data Type for Tag Configurations

JSON Data Visualization

The OAS Configuration Application also has the ability to recognize JSON data and will assist with visualization. For Tags of both String and JSON Data Type, clicking on the current value will display the value in text form. If the value can be parsed as valid JSON, it will be displayed using a hierarchical JSON visualizer allowing you to expand or collapse nodes and arrays, as well as see the data with syntax highlighting.

JSON Calculations

The OAS Platform Calculation Engine provides powerful features for real time data transformations and logic. Additionally, the Calculation Engine supports a set of functions for generating, querying, and manipulating JSON data. For example, if you create a tag containing a JSON structure, you can use the JSON Calculations to locate data points within the structure, add other structures to the JSON, and even set values on a particular node. See our documentation on JSON Calculations for more information.

JSON and MQTT

The OAS Platform can act as an MQTT client as well as an MQTT broker. When used as an MQTT client with the MQTT Connector can publish and subscribe to any MQTT broker. This allows you to send OAS Tag data whenever values have changed. By default, OAS creates a simple JSON message that includes the current Tag value, and timestamp when it was updated in the OAS platform. If you prefer to craft your own custom message format, including more data and even data from multiple Tags, you can set the source Tag to the JSON data type or String data type containing valid JSON and the message published will be used instead of the default format. This includes using JSON Calculations to dynamically generate the Tag value as data changes. With this powerful feature you can guarantee the messages sent to remote systems comply with your requirements.

The OAS Platform built-in message payload for MQTT is simple and concise. The Tag’s current value, timestamp when the value changed, and the data quality of the tag are published as bare values in separate topics. For example, if your Tag name is MyTag, the topic of MyTag will contain the current value of the tag. In the configuration of a Tag with MQTT as the Data Source, you can also configure the topic name. Also, if you check “Include Timestamp” and/or “Include Quality”, an additional topic will be created for each.

While this is simple and easy to configure, there may be cases where you would like to send a custom payload containing the Tag’s value, timestamp, and quality in a single message published to a single topic. Or you may want to send values from multiple tags in a single payload. If you set the Tag Data Type to JSON or String containing a valid JSON structure, the payload will now contain the JSON structure. This means you can use a Calculation tag to construct your JSON, based on string literals or a segment derived from another larger JSON structure, or even combine multiple tags into a single JSON payload and you have the freedom to choose what gets sent to the MQTT Broker. For example, this JSON could be created from a JSON Calculation containing four tags in an array along with additional wrapper values:

{
  "title" : "MyTagData",
  "tags" : [
    {"n" : "Tag1", "v": true, "ts" : 1234567890, "q": "GOOD" },
    {"n" : "Tag2", "v": 99.12, "ts" : 1234567890, "q": "GOOD" },
    {"n" : "Tag3", "v": 14, "ts" : 1234567890, "q": "BAD" },
    {"n" : "Tag4", "v": "data", "ts" : 1234567890, "q": "GOOD" }
  ]
}