Processing JSON Messages using DataPower, Part 2: JSONiq

Screen Shot 2015-06-02 at 2.25.18 PM

Executive Summary

DataPower has first class support for JSON message processing through two frameworks: JSONx and JSONiq. They have their pros and their cons. With JSONx, the message is converted into XML. This encapsulates the input message format from subsequent processing steps and allows the continued use of existing XML tools and experience. With JSONiq, a new syntax is introduced but with the benefit of not requiring an intermediate XML format. This can be useful if your company is already a strong supporter of XQuery, weak on XSLT or just looking for the right tool for the job. In this article, we’ll discuss JSONiq processing in DataPower.


JSON is an encoding standard for data interchange that is becoming the standard for services, displacing SOAP/XML. DataPower provides two distinct methods of working with JSON: JSONx and JSONiq, an extension of XQuery. With JSONx, the data is converted into XML. With JSONiq, the data can be queried natively. This series will discuss the history of the XML appliance and show examples of how to work with JSON in the IBM DataPower Gateway environment.


Introduced in Firmware 6, JSONiq allows DataPower to work directly with JSON formatted messages, bypassing any need for an intermediate XML conversion step. It is an extension to XQuery version 1.0 and the version of the specification implemented by the DataPower platform is 0.4.42. It can extract, filter, transform and query JSON messages. It also has the ability to transform JSON messages into XML. In summary, JSONiq can be used to process JSON in the same way that XML can be processed by XSLT.

Sample Input JSON

This is JSON data that will be used in the subsequent JSONiq examples.

JSONiq – Extraction

In this example, we’ll extract the shipTo object from the incoming payload.

In this example the ‘.’ is used to refer to the root of the input message. ‘.(“shipTo”)’ outputs the root element’s ‘shipTo’ value from the JSON payload.

JSONiq – Message Filtering

In this example, we want to return an error if the “state” in the “shipTo” object is Hawaii. Otherwise we’ll just return the input document untouched.

From this example, we can walk the JSON hierarchy via the (..)(..) notation and perform standard equality checks. Also note that the input JSON is passed untouched to the output through the ‘else .’ statement when the state is not Hawaii.

JSONiq – Transform

This transforms the input JSON into a text format.

JSONiq – Transform to XML

The performs the same transformation as above, but into an XML format instead.

In this example, note the lack of an opening bracket ‘(‘ after the declare statement. To denote inlined JSONiq processing statements, curly braces ‘{}’ are used.

JSONiq – DataPower Extensions

DataPower extensions can be accessed from JSONiq as well. In this example, the http request headers are returned.

The use of a square bracket ‘[]’ denotes an array. Each HTTP header is written as a line of JSON with the header name as the key.

Firmware Version 7

In firmware version 7, the output:method statement:

is no longer required. The DataPower appliance will set the output:method dynamically.

Running JSONiq

In your processing policy, drag in a new transform action and set the following options:

  • Use Document Processing Instructions: Transform with a processing control file, if specified
  • Input language: JSON
  • Transform Language: XQuery
  • Transform file: Select your .xq file

Note that if your file does not end with the .xq extension, then it will not appear in the ‘transform file’ drop box list.


Part two talked about JSONiq and it’s value in being able to work with JSON without requiring an intermediate format. JSONiq introduces an entirely new layer of programming constructs which may not be a very good fit for XML-centric enterprises. My recommendation is to stick with JSONx and XSLT-based tooling as you have already made a strong commitment to those technologies, but continue to keep an eye on the evolution of JSON as a business integration technology. You may one day find out that every new service is now JSON based and clinging to XML formats is holding your platform back.

About the Author

Dan Zrobok


Dan is the owner of Orange Specs Consulting, with over 14 years of experience working in enterprise systems integration. He is an advocate of the IBM DataPower Gateway platform and looks to improve environments that have embraced it. He also occasionally fights dragons with his three year old daughter Ruby, and newborn Clementine.

Share this Post