JSON Support

WSO2 EI provides support for JavaScript Object Notation (JSON) payloads in messages. The following sections describe how to work with JSON in the EI:

1 JSON message builders and formatters
2 XML representation of JSON payloads
3 Converting a payload between XML and JSON
4 Accessing content from JSON payloads
5 Logging JSON payloads
6 Constructing and transforming JSON payloads
7 XML to JSON transformation parameters
8 Validating JSON messages
9 Troubleshooting, debugging, and logging

JSON message builders and formatters

WSO2 EI provides the following message builders and formatters for JSON. These are configured in the Axis2 configuration files located in the <EI_HOME>/conf/axis2 directory. Both types of JSON builders use StAXON as the underlying JSON processor.

Default message builder and formatter

Given below is the default message builder and formatter in WSO2 EI. These will maintain the JSON representation intact without converting it to XML during message mediation. You can access the payload content using JSON Path or XPath and convert the payload to XML at any point in the mediation flow. These will also be used by default for JSON mapping when you expose datasources as data services using WSO2 EI.

org.wso2.carbon.integrator.core.json.JsonStreamBuilder
org.wso2.carbon.integrator.core.json.JsonStreamFormatter

Other message builders and formatters

Other message builders and formatters can be enabled by adding the required parameters to the axis2.xml file as explained below.

If you want to convert the JSON representation to XML before the mediation flow begins, you need to add the message builder and formatter shown below. Note that some data loss can occur during the JSON to XML to JSON conversion process.

<parameter name="passthruJsonBuilder">org.apache.synapse.commons.json.JsonBuilder</parameter>
<parameter name="passthruJsonFormatter">org.apache.synapse.commons.json.JsonFormatter</parameter>

The following builders and formatters can be enabled for JSON mapping in data services.

<parameter name="dsJsonBuilder">org.apache.axis2.json.gson.JsonBuilder</parameter>
<parameter name="dsJsonFormatter">org.apache.axis2.json.JSONMessageFormatter</parameter>

The following builders and formatters can also enabled. Note that this is necessary for compatibility with previous versions of the EI (WSO2 ESB):

<parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONBuilder</parameter>
<parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONMessageFormatter</parameter>
<parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONStreamBuilder</parameter>
<parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONStreamFormatter</parameter>
<parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONBadgerfishOMBuilder</parameter>
<parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONBadgerfishMessageFormatter</parameter>

Always use the same type of builder and formatter combination. Mixing different builders and formatters will cause errors at runtime.

If you want the EI to handle JSON payloads that are sent using a media type other than application/json, you must register the JSON builder and formatter for that media type in the following two files at minimum (for best results, register them in all Axis2 configuration files found in the <EI_HOME>/conf/axis2 directory):

<EI_HOME>/conf/axis2/axis2.xml
<EI_HOME>/conf/axis2/axis2_blocking_client.xml

For example, if the media type is text/javascript, register the message builder and formatter as follows:

<messageBuilder contentType="text/javascript" 
               class="org.apache.synapse.commons.json.JsonStreamBuilder"/>

<messageFormatter contentType="text/javascript" 
                class="org.apache.synapse.commons.json.JsonStreamFormatter"/>

When you modify the builders/formatters in Axis2 configuration, make sure that you have enabled only one correct message builder/formatter pair for a given media type.

XML representation of JSON payloads

When building the XML tree, JSON builders attach the converted XML infoset to a special XML element that acts as the root element of the final XML tree. If the original JSON payload is of type object, the special element is <jsonObject/>. If it is an array, the special element is <jsonArray/>. Following are examples of JSON and XML representations of various objects and arrays.

Null objects

JSON:

{"object":null}

XML:

<jsonObject>
    <object></object>
</jsonObject>

Empty objects

JSON:

{"object":{}}

XML:

<jsonObject>
   <object></object>
</jsonObject>

Empty strings

JSON:

{"object":""}

XML:

<jsonObject>
   <object></object>
</jsonObject>

Empty array

JSON:

[]

XML (JsonStreamBuilder):

<jsonArray></jsonArray>

XML (JsonBuilder):

<jsonArray>
   <?xml-multiple jsonElement?>
</jsonArray>

Named arrays

JSON:

{"array":[1,2]}

XML (JsonStreamBuilder):

<jsonObject>
   <array>1</array>
   <array>2</array>
</jsonObject>