Skip to content

API Manager Documentation 4.1.0JSON Transform Mediator

4.1.0

• 4.1.0
• 4.0.0
• 3.2.0
• 3.1.0
• 3.0.0
• Show All

SearchK

• Home

• Get Started

• Design APIs

• Deploy and Publish APIs

• Consume APIs

• Integrate

• Streaming

• Analytics

• Observe
• Reference
• Administer
• Install and Setup
• Tutorials

Report Issues
•
• Reference
o Product REST APIs
o Product Configurations
o API Controller (APICTL)
o API Kubernetes Operator
o Connectors
o Streaming Connectors
o Integration Artifacts
▪ REST API Properties
▪ Proxy Service Properties
▪ Mediator Catalog
▪ About Mediators
▪ Aggregate Mediators
▪ Builder Mediator
▪ Cache Mediator
▪ Call Mediator
▪ Call Template Mediator
▪ Callout Mediator
▪ Class Mediator
▪ Clone Mediator
▪ Data Mapping
▪ Data Service Call Mediator
▪ DBLookup Mediator
▪ DB Report Mediator
▪ Drop Mediator
▪ EJB Mediator
▪ Enrich Mediator
▪ Entitlement Mediator
▪ FastXSLT Mediator
▪ Fault Mediator
▪ Filter Mediator
▪ ForEach Mediator
▪ Header Mediator
▪ Iterate Mediator
▪ JSON Transform Mediator
▪ Log Mediator
▪ Loopback Mediator
▪ NTLM Mediator
▪ OAuth Mediator
▪ PayloadFactory Mediator
▪ Property Mediator
▪ Property Group Mediator
▪ Respond Mediator
▪ Script Mediator
▪ Send Mediator
▪ Sequence Mediator
▪ Smooks Mediator
▪ Store Mediator
▪ Switch Mediator
▪ Throttle Mediator
▪ Transaction Mediator
▪ URLRewrite Mediator
▪ Validate Mediator
▪ XQuery Mediator
▪ XSLT Mediator
▪ Property Catalog
▪ Scheduled Task Properties
▪ Synapse Properties
▪ Inbound Endpoints
▪ Message Stores and Processors
▪ Templates
▪ Endpoints
▪ Data Services
▪ Transport Configs
▪ Micro Integrator Security References
 o Customizations
o Best Practices
o Accessibility Compliance
o Guides
o Troubleshooting
o FAQ

keyboard_arrow_rightOn this page

• Syntax
• Configuration
• Challenges when converting XML to JSON
o Converting an array of one from XML to JSON
o Losing data type information
• Example
o Example 1 - Overriding global synapse properties
o Example 2 - Using a JSON schema
o Example 3 - Overriding global synapse properties and applying a JSON schema

JSON Transform Mediator¶

The JSON Transform mediator is used for controlling XML to JSON transformations (possibly with a JSON Schema) inside a
mediation. Normally XML to JSON transformations are controlled by the properties defined in synapse.properties.

Those configurations are applied globally and you cannot have independent configurations for each mediation scenario. With JSON
Transform mediator you can define the properties inside the mediation and control the transformation independently. Also you can have
a JSON schema to correct the payload if there are inconsistencies in the transformation.

Info

The JSON Transform mediator is a content aware mediator.

Syntax¶
<jsontransform [schema="string"]>
<property name="string" value="string"/>*
</jsontransform>
Configuration¶
The general parameters available for configuring the JSON Transform mediator are as follows.

Parameter Description
Name
Schema
This parameter is used for specifying the registry location of the JSON schema file. You can
Local Entry as well

Apart from defining a schema, you can also add properties to control XML to JSON transformation. The parameters available for
configuring a property are as follows:

Parameter Description
Name
Schema
The name of the property that needs to be overridden in the sequence. The JSON Transform
mediator supports only the parameters related to XML to JSON conversion. The list of propert
supported can be found here.

Property
Value The value that should be overridden.

Challenges when converting XML to JSON¶

Converting an array of one from XML to JSON¶
Let's say we do a search and get the results in XML. We want the results to be converted to JSON array when returned to the client. A
blind XML to JSON transformation would look like this.

<books>
<book>Harry Potter</book>
<book>Lord of the Rings</book>
</books>
{"books" : { "book" : ["Harry Potter", "Lord of the Rings"]}}

Let's say we get only one result. The converted JSON would come out like below.

<books>
<book>Harry Potter</book>
</books>
{"books" : { "book" : "Harry Potter"}}

Theoretically the above conversion is correct. However, a client might expect an array and not a string.

We can tackle the above issue with a JSON Schema and correct the output to be an JSON Array.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"books": {
"type": "object",
 "properties": {
"book": {
"type": "array"
}
}
}
}
}

Losing data type information¶

Since we cannot differentiate between String, Numeric and Boolean in XML, when we do a conversion from XML to JSON, the data
type of value might be not what we expected. Look at the following the example.

<person>
<id>56783</id>
<name>Alice</name>
<isAdmin>true</isAdmin>
</person>
By default, the JSON output would look like below after the mediation.
{
"person": {
"id": 56783,
"name": "Alice",
"isAdmin": true
}
}
The field id has been converted to number, name to String and isAdmin to boolean.
The runtime has automatically detected and parsed the values to native data-types. But there might be a scenario where the client
expects a String type for id.
We want the native conversion rules applied to name and isAdmin fields and not id.

With JSON Transform mediator, we can use a JSON schema to tackle this issue.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
}
}
}

With this schema correction, the JSON payload would come out as below. This gives granular level control over individual field data
types rather than using a global property.

{
"person": {
"id": "56783",
"name": "Alice",
"isAdmin": true
}
}
Example¶
Given below is a sample schema file (Schema.json) file that you can use for running the examples given below. Add this sample
schema file (i.e. Schema.json) to the following registry path: conf:/Schema.json. For instructions on adding the schema file to the
Registry Resources Project, see Creating Registry Resource.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"fruit": {
"type": "string",
"minLength": 4,
"maxLength": 6,
"pattern": "^[0-9]{1,45}$"
},
"price": {
"type": "number",
"minimum": 2,
"maximum": 20,
"exclusiveMaximum": 20,
"multipleOf": 2.5
}
},
"required": [
"price"
]
}

Use the following payload to test the examples:

<jsonObject>
<fruit>12345</fruit>
<price>7.5</price>
<quantity>10</quantity>
</jsonObject>

Example 1 - Overriding global synapse properties¶

This example will override the XML to JSON transformation properties defined in the synapse.properies configuration with the
properties given by the JSON transform mediator.

<proxy xmlns="http://ws.apache.org/ns/synapse"
name="transformMediatorSimpleAutoPrimitive" startOnLoad="true"
transports="https http">
<description/>
<target>
<inSequence>
<property name="messageType" scope="axis2"
value="application/json"/>
<jsontransform>
<property
name="synapse.commons.json.output.autoPrimitive" value = "false"/>
</jsontransform>
<respond/>
</inSequence>
</target>
</proxy>

Output: All the numeric values have been converted to string values since the auto primitive property is defined as false.
{
"fruit": "12345",
"price": "7.5",
"quantity": "10"
}

Example 2 - Using a JSON schema¶

This will perform the XML to JSON transformation using the global synapse settings and then apply the JSON schema that is added
from the JSON transform mediator.

<proxy name="transformMediatorSimpleSchema" startOnLoad="true"

transports="https http" xmlns="http://ws.apache.org/ns/synapse">
<description/>
<target>
<inSequence>
<property name="messageType" scope="axis2"
value="application/json"/>
<jsontransform schema="conf:/Schema.json"/>
<respond/>
</inSequence>
</target>
</proxy>

Output: The 'fruit' value has been converted to string and the 'price' value has been converted to a number according to the schema
definition. Please note that 'quantity' has been converted to a number because it is the default property according to
the synapse.properties file.

{
"fruit": "12345",
"price": 7.5,
"quantity": 10
}

Example 3 - Overriding global synapse properties and applying a JSON

schema¶
This will first override the XML to JSON transformation properties defined in the synapse.properies configuration with the properties
given by the JSON transform mediator and also apply the JSON Schema given in the mediator.

<proxy xmlns="http://ws.apache.org/ns/synapse"
name="transformMediatorPropertyAndSchema" startOnLoad="true"
transports="https http">
<description/>
<target>
<inSequence>
<property name="messageType" scope="axis2"
value="application/json"/>
<jsontransform schema="conf:/Schema.json">
<property
name="synapse.commons.json.output.autoPrimitive" value = "false"/>
</jsontransform>
<respond/>
</inSequence>
</target>
</proxy>

Output: The 'fruit' value has been converted to a string and the 'price' value has been converted to a number according to the schema
definition. Please note that 'quantity' has been converted to a string because we have overridden the global synapse.properties file.

{
 "fruit": "12345",
"price": 7.5,
"quantity": "10"
}
Top

PreviousIterate Mediator

NextLog Mediator

WSO2 API Manager - Documentation

Copyright © WSO2 LLC (2022-2023)
Content licensed under CC By 4.0. | Sample code licensed under Apache 2.0.