This documentation is for WSO2 Enterprise Integrator version 6.0.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Anchor
MessageBuildersandFormatters
MessageBuildersandFormatters
JSON message builders and formatters

The WSO2 EI provides two types of the following message builders and formatters for JSON. The default builder and formatter keep . These are configured in the Axis2 configuration files located in the <EI_HOME>/conf/axis2 directory. 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
  • org.apache.synapse.commons.json.JsonStreamBuilder

  • org.apache.synapse.commons.json.JsonStreamFormatter

Other message builders and formatters

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

If you want to convert the JSON representation to XML before the mediation flow begins, use the following you need to add the message builder and formatter insteadshown 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 are configured in the messageBuilders and messageFormatters sections, respectively, of the Axis2 configuration files located in the <EI_HOME>/conf/axis2 directory. Both types of JSON builders use StAXON as the underlying JSON processor.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 are also included can also enabled. Note that this is necessary for compatibility with previous versions of the EI (WSO2 ESB):

...

ESB):

  • <parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONBuilder</parameter>
  • <parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONBuilderJSONMessageFormatter</JSONMessageFormatterparameter>
  • <parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONStreamBuilder/JSONStreamFormatter</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>

Note

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

...

You can use JSON path expressions with following mediators:

MediatorUsage
Log

As a log property:

Code Block
languagehtml/xml
<log>
    <property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>
</log>
Property

As a standalone property:

Code Block
languagehtml/xml
<property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>
PayloadFactory  

As the payload arguments:

Code Block
languagehtml/xml
<payloadFactory media-type="json">
    <format>{"RESPONSE":"$1"}</format>
    <args>
        <arg evaluator="json" expression="$.coordinates.location[0].name"/>
    </args>
</payloadFactory>

IMPORTANT: You MUST omit the json-eval() method within the payload arguments to evaluate JSON paths within the PayloadFactory mediator. Instead, you MUST select the correct expression evaluator (xml or json) for a given argument.

Switch

As the switch source:

Code Block
languagehtml/xml
<switch source="json-eval($.coordinates.location[0].name)">
Filter

As the filter source:

Code Block
languagehtml/xml
<filter source="json-eval($.coordinates.location[0].name)" 
        regex="Eiffel.*">

JSON path syntax

Suppose we have the following payload:

...

The following table summarizes sample JSONPath expressions and their outputs:

ExpressionResult
$.
{ "id":12345, "id_str":"12345", "array":[1, 2, [[],[{"inner_id":6789}]]], "name":null, "object":{}, "$schema_location":"unknown", "12X12":"image12x12.png"}
$.id
12345
$.name
null
$.object
{}
$.['$schema_location']
unknown
$.12X12
image12x12.png
$.array
[1, 2, [[],[{"inner_id":6789}]]]
$.array[2][1][0].inner_id
6789

You can learn more about JSONPath syntax here.

...

Following are the XML to JSON transformation parameters and their descriptions:

Parameter

Description

Default Value

synapse.commons.json.preserve.namespace

Preserves the namespace declarations in the JSON output in XML to JSON transformations.

false

synapse.commons.json.buildValidNCNames

Builds valid XML NCNames when building XML element names in XML to JSON transformations.

false

synapse.commons.json.output.autoPrimitive

Allows primitive types in the JSON output in XML to JSON transformations.

true

synapse.commons.json.output.namespaceSepChar

The namespace prefix separation character for the JSON output in XML to JSON transformations.

The default separation character is -

synapse.commons.json.output.enableNSDeclarations

Adds XML namespace declarations in the JSON output in XML to JSON transformations.

false

synapse.commons.json.output.disableAutoPrimitive.regex

Disables auto primitive conversion in XML to JSON transformations.

null

synapse.commons.json.output.jsonoutAutoArray

Sets the JSON output to an array element in XML to JSON transformations.

true

synapse.commons.json.output.jsonoutMultiplePI

Sets the JSON output to an xml multiple processing instruction in XML to JSON transformations.

true

synapse.commons.json.output.xmloutAutoArray

Sets the XML output to an array element in XML to JSON transformations.

true

synapse.commons.json.output.xmloutMultiplePI

Sets the XML output to an xml multiple processing instruction in XML to JSON transformations.

false

synapse.commons.json.output.emptyXmlElemToEmptyStr

Sets an empty element to an empty JSON string in XML to JSON transformations.

true

Anchor
troubleshooting
troubleshooting

...

The parameters available in this section are as follows.

Parameter NameDescription
Schema keys defined for Validate MediatorThis section is used to specify the key to access the main schema based on which validation is carried out, as well as to specify the JSON, which needs to be validated. 
SourceThe JSONPath expression to extract the JSON that needs to be validated. E.g: json-eval($.msg)"

Following example use the below sample schema  StockQuoteSchema.json file. Add this sample schema file (i.e. StockQuoteSchema.json) to the following Registry path:  conf:/schema/StockQuoteSchema.json. For instructions on adding the schema file to the Registry path, see Adding a Resource.

...