This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The XMLtoJSON policy converts messages from the extensible markup language (XML) format to JavaScript Object Notation (JSON), giving you several options for controlling how messages are converted.

Assuming that the intent is to convert an XML-formatted response into a JSON-formatted response, the policy would be attached to a response Flow (for example, Response / ProxyEndpoint / PostFlow).

In a typical mediation scenario, a JSON to XML policy on the inbound request flow is often paired with an XML to JSON policy on the outbound response flow. By combining policies this way, a JSON API can be exposed for backend services that natively support only XML.

For scenarios where APIs are consumed by diverse client apps that may require either JSON or XML, the response format can be dynamically set by configuring JSON to XML and XML to JSON policies to execute conditionally. SeeFlow variables and conditions for an implementation of this scenario.

This policy is aStandard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, seePolicy types.

Samples

For a detailed discussion on converting between JSON and XML, seethis article.

<XMLToJSON name="ConvertToJSON">  <Options>  </Options>  <OutputVariable>response</OutputVariable>  <Source>response</Source></XMLToJSON>

Element reference

Following are elements and attributes you can configure on this policy.

<XMLToJSONasync="false"continueOnError="false"enabled="true"name="XML-to-JSON-1"><DisplayName>XMLtoJSON1</DisplayName><Source>response</Source><OutputVariable>response</OutputVariable><Options><RecognizeNumber>true</RecognizeNumber><RecognizeBoolean>true</RecognizeBoolean><RecognizeNull>true</RecognizeNull><NullValue>NULL</NullValue><NamespaceBlockName>#namespaces</NamespaceBlockName><DefaultNamespaceNodeName>&</DefaultNamespaceNodeName><NamespaceSeparator>***</NamespaceSeparator><TextAlwaysAsProperty>true</TextAlwaysAsProperty><TextNodeName>TEXT</TextNodeName><AttributeBlockName>FOO_BLOCK</AttributeBlockName><AttributePrefix>BAR_</AttributePrefix><OutputPrefix>PREFIX_</OutputPrefix><OutputSuffix>_SUFFIX</OutputSuffix><StripLevels>2</StripLevels><TreatAsArray><Pathunwrap="true">teachers/teacher/studentnames/name</Path></TreatAsArray></Options><!--UseOptionsorFormat,notboth--><Format>yahoo</Format></XMLToJSON>

<XMLtoJSON> attributes

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to thename attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<Source> element

The variable specifying the XML message that you want to convert to JSON.

The HTTP Content-type header of the source message must be set toapplication/xml, otherwise the policy is not enforced.

If<Source> is not defined, then it is treated asmessage, which resolves torequest when the policy is attached to a request flow, orresponse when the policy is attached to a response flow.

If the source variable cannot be resolved, or resolves to a non-message type, the policy throws an error.

<Source>response</Source>

<OutputVariable> element

Specifies where to store the output of the XML to JSON format conversion. Typically, this element is not included in the policy configuration.

Apigee parses the payload of the XML message specified inSource, converts it into JSON, stores the result into the payload ofOutputVariable, and sets the HTTP Content-type header of theOutputVariable message toapplication/json.

IfOutputVariable is not specified, the value ofSource is used by default. For example, if thesource isresponse, thenOutputVariable defaults toresponse.

<OutputVariable>response</OutputVariable>

<Options>

Options give you control over the conversion from XML to JSON. Use either the<Options> group, which lets you add specific conversion settings, or the<Format> element, which lets you reference a template of predefined options. You cannot use both<Options> and<Format>.

<Options> is required if<Format> isn't used.

<RecognizeNumber> element

If true, then number fields in the XML payload retain their original format.

<RecognizeNumber>true</RecognizeNumber>

Consider the following XML example:

<a>  <b>100</b>  <c>value</c></a>

IfRecognizeNumber istrue, the policy converts this to:

{    "a": {        "b": 100,        "c": "value"    }}

IfRecognizeNumber isfalse, the policy converts this to:

{  "a": {    "b": "100",    "c": "value"  }}

<RecognizeBoolean> element

Lets the conversion maintain boolean true/false values rather than turning the values into strings.

<RecognizeBoolean>true</RecognizeBoolean>

For the following XML example:

<a>  <b>true</b>  <c>value</c></a>

IfRecognizeBoolean istrue, the policy converts this to:

{    "a": {        "b": true,        "c": "value"    }}

IfRecognizeBoolean isfalse, the policy converts this to:

{    "a": {        "b": "true",        "c": "value"    }}

<RecognizeNull> element

Lets you convert empty values to null values.

<RecognizeNull>true</RecognizeNull>

For the following XML:

<a>  <b></b>  <c>value</c></a>

IfRecognizeNull istrue, and if there is noNullValue option, this XML converts to:

{  "a": {    "b": null,    "c": "value"  }}

IfRecognizeNull isfalse, this XML converts to:

{  "a": {    "b": {},    "c": "value"  }}

<NullValue> element

Indicates the value to which recognized null values in the source message should be converted. By default the value isnull. This option is effective only ifRecognizeNull is true.

<NullValue>not-present</NullValue>

For the following XML:

<a>  <b></b>  <c>value</c></a>

IfRecognizeNull istrue, andNullValue is not specified, this XML converts to:

{  "a": {    "b": null,    "c": "value"  }}

IfRecognizeNull istrue, andNullValue isnot-present, this XML converts to:

{  "a": {    "b": "not-present",    "c": "value"  }}

Namespace options

By default, this policy omits XML namespaces in the generated JSON. To specify that namespaces in the XML document should be translated into the generated JSON, use these elements together.

<NamespaceBlockName>#namespaces</NamespaceBlockName><DefaultNamespaceNodeName>&</DefaultNamespaceNodeName><NamespaceSeparator>***</NamespaceSeparator>

Consider the following XML example:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">  <ns1:b>value</ns1:b></a>

IfNamespaceSeparator is not specified, the following JSON structure is generated:

{    "a": {        "b": "value"    }}

If the elementsNamespaceBlockName,DefaultNamespaceNodeName, andNamespaceSeparator are specified as#namespaces,&, and***, respectively, then the following JSON structure is generated:

{    "a": {        "#namespaces": {            "&": "http://ns.com",            "ns1": "http://ns1.com"        },        "ns1***b": "value"    }}

Text options

Use these elements together.

      <TextAlwaysAsProperty>true|false</TextAlwaysAsProperty>      <TextNodeName>TEXT</TextNodeName>

When the policy encounters an XML element that contains only a single text node as a child, the policy translates the text content of that XML element into a property in the JSON hash.

When the policy encounters an XML element that contains multiple children ofmixed content, these options allow you to control the output JSON of any child text nodes.

For example, consider this policy configuration:

<XMLToJSON name='XMLToJSON-1'>  <Options>    <TextAlwaysAsProperty>???</TextAlwaysAsProperty>    <TextNodeName>#text</TextNodeName>  </Options></XMLToJSON>

For the given XML inputs, the policy will generate these outputs, depending on whetherTextAlwaysAsProperty istrue orfalse:

<a>value1</a>

{  "a": "value1"}

{  "a": {    "#text": "value1"  }}

<a>value1  <b>value2</b></a>

{  "a": {    "#text": "value1\n",    "b": "value2"  }}

{  "a": {    "#text": "value1\n",    "b": {      "#text": "value2"    }  }}

Attribute options

These elements, together, allow you to group attribute values into a JSON block and append prefixes to the attribute names.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName><AttributePrefix>BAR_</AttributePrefix>

Consider the following XML example:

<a attrib1="value1" attrib2="value2"/>

If both the attributes (AttributeBlockName andAttributePrefix) are specified as defined in the XML to JSON example, the following JSON structure is generated:

{  "a": {    "FOO_BLOCK": {      "BAR_attrib1": "value1",      "BAR_attrib2": "value2"    }  }}

If onlyAttributeBlockName is specified, the following JSON structure is generated:

{    "a": {        "FOO_BLOCK": {            "attrib1": "value1",            "attrib2": "value2"        }    }}

If onlyAttributePrefix is specified, the following JSON structure is generated:

{    "a": {        "BAR_attrib1": "value1",        "BAR_attrib2": "value2"    }}

If neither is specified, the following JSON structure is generated:

{    "a": {        "attrib1": "value1",        "attrib2": "value2"    }}

<OutputPrefix> and <OutputSuffix> elements

Use these elements together to apply a prefix and/or suffix to the generated JSON.

<OutputPrefix>PREFIX_</OutputPrefix><OutputSuffix>_SUFFIX</OutputSuffix>

Consider the following XML example:

<a>value</a>

Suppose the policy configuration is as follows:

<XMLToJSON name='XMLToJSON-4'>  <Options>    <OutputPrefix>{ "result": </OutputPrefix>    <OutputSuffix>}</OutputSuffix>  </Options></XMLToJSON>

The following JSON structure is generated:

{  "result": {    "a": "value"  }}

You may omit either or both ofOutputPrefix andOutputSuffix.

Using these elements, it is possible to generate invalid JSON. For example, using this policy configuration:

<XMLToJSON name='XMLToJSON-4'>  <Options>    <OutputPrefix>PREFIX_</OutputPrefix>  </Options></XMLToJSON>

The policy generates the following, which is not valid JSON:

PREFIX_{  "a" : "value"}

If the configuration specifies neitherOutputPrefix norOutputSuffix, the policy generates the following JSON structure:

{  "a": "value"}

<StripLevels> element

<Options>    <StripLevels>4</StripLevels></Options>

Sometimes XML payloads, such as SOAP, have many parent levels you don't want to include in the converted JSON. Here's an example SOAP response containing many levels:

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/Schemata-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GetCityWeatherByZIPResponsexmlns="http://ws.cdyne.com/WeatherWS/"><GetCityWeatherByZIPResult><State>CO</State><City>Denver</City><Description>Sunny</Description><Temperature>62</Temperature></GetCityWeatherByZIPResult></GetCityWeatherByZIPResponse></soap:Body></soap:Envelope>

There are 4 levels before you get to the State, City, Description, and Temperature level. Without using<StripLevels>, the converted JSON response would look like this:

{   "Envelope" : {      "Body" : {         "GetCityWeatherByZIPResponse" : {            "GetCityWeatherByZIPResult" : {               "State" : "CO",               "City" : "Denver",               "Description" : "Sunny",               "Temperature" : "62"            }         }      }   }}

If you want to strip those first 4 levels in the JSON response, you'd set<StripLevels>4</StripLevels>, which would give you the following JSON:

{  "State" : "CO",  "City" : "Denver",  "Description" : "Sunny",  "Temperature" : "62"}

You can strip levels away up to the first element that contains multiple children. What does that mean? Let's look at a more complex JSON example:

{   "Envelope" : {      "Body" : {         "GetCityForecastByZIPResponse" : {            "GetCityForecastByZIPResult" : {               "ResponseText" : "City Found",               "ForecastResult" : {                  "Forecast" : [                     {                        "ProbabilityOfPrecipiation" : {                           "Nighttime" : "00",                           "Daytime" : 10                        }  ...

Level 3 in this example isGetCityForecastByZIPResponse, which has only one child. So if you were to use<StripLevels>3</StripLevels> (remove the first three levels), the JSON would look like this:

{   "GetCityForecastByZIPResult" : {      "ResponseText" : "City Found",      "ForecastResult" : {         "Forecast" : [            {               "ProbabilityOfPrecipiation" : {                  "Nighttime" : "00",                  "Daytime" : 10               }  ...

Notice thatGetCityForecastByZIPResult has multiple children. Since it's the first element containing multiple children, you can strip this last level using<StripLevels>4</StripLevels>, which will give you the following JSON:

{   "ResponseText" : "City Found",   "ForecastResult" : {      "Forecast" : [         {            "ProbabilityOfPrecipiation" : {               "Nighttime" : "00",               "Daytime" : 10            }  ...

Because level 4 is the first level containing multiple children, you can't strip any levels lower than this. If you set the strip level to 5, 6, 7, and so on, you'll continue to get the response above.

<TreatAsArray>/<Path> element

<Options>    <TreatAsArray>        <Path unwrap="true">teachers/teacher/studentnames/name</Path>    </TreatAsArray></Options>

This element combination lets you ensure that values from an XML document are always translated to a JSON array. This can be useful when the number of child elements varies for different payloads. Apigee's default behavior is to convert multiple child elements of the same name to a JSON array and single child elements to a JSON primitive. TheTreatAsArray option lets you ensure that child elements are always translated to a JSON array.

UsingTreatAsArray can improve the structure of subsequent code that handles the output, because data from the array is returned the same way every time. For example, evaluating a JSONPath of$.teachers.teacher.studentnames.name[0] will return the first name value consistently, whether the original XML contained one, or more than one,name element.

Let's take a step back and look at the XML to JSON default behavior, then explore how to control the output using<TreatAsArray>/<Path>.

When an XML document contains an element with multiple occurrences (which can happen when the XML schema specifiesmaxOccurs='unbounded' for the element), the XML to JSON policy automatically puts those values in an array. For example, the following XML block

<teacher>    <name>teacherA</name>    <studentnames>        <name>student1</name>        <name>student2</name>    </studentnames></teacher>

...gets converted into the following JSON automatically with no special policy configuration:

{  "teachers" : {    "teacher" : {      "name" : "teacherA",      "studentnames" : {        "name" :[          "student1",          "student2"        ]      }    }  }}

Notice that the two student names are contained in an array.

However, if only one student appears in the XML document, the XML to JSON policy automatically treats the value as a single string, not an array of strings, as shown in the following example:

{  "teachers" : {    "teacher" : {      "name" : "teacherA",      "studentnames" : {        "name" :"student1"      }    }  }}

In the previous examples, similar data was converted differently, once to an array, another to a single string. The<TreatAsArray>/<Path> element lets you control the output to make sure that the student names are always converted into an array even if there's only one value. You configure this by identifying the Path to the element whose values you want to convert into an array, like so:

<Options>    <TreatAsArray>        <Path>teachers/teacher/studentnames/name</Path>    </TreatAsArray></Options>

{  "teachers" : {    "teacher" : {      "name" : "teacherA",      "studentnames" : {        "name" :["student1"]      }    }  }}

<Options>    <TreatAsArray>        <Pathunwrap="true">teachers/teacher/studentnames/name</Path>    </TreatAsArray></Options>

{  "teachers" : {      "teacher" : {          "name" : "teacherA",          "studentnames" : {              "name" : [                 "student1",                 "student2"              ]}...

<TreatAsArray>    <Path unwrap="true">teachers/teacher</Path>    <Path unwrap="true">teachers/teacher/studentnames/name</Path></TreatAsArray>

{  "teachers" : [{      "name" : "teacherA",      "studentnames" : ["student1","student2"]      }]...

For more examples and a feature walkthrough, see this Google Cloud Community article..

<Format>

Format gives you control over the conversion from XML to JSON. Enter the name of a predefined template that contains a specific combination of Options elements described in this topic. Predefined formats include:xml.com,yahoo,google,badgerFish.

Use either the<Format> element or the<Options> group. You cannot use both<Format> and<Options>.

Following are the Format definitions of each predefined template.

xml.com

<RecognizeNull>true</RecognizeNull><TextNodeName>#text</TextNodeName><AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber><TextNodeName>content</TextNodeName>

google

<TextNodeName>$t</TextNodeName><NamespaceSeparator>$</NamespaceSeparator><TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName><TextAlwaysAsProperty>true</TextAlwaysAsProperty><AttributePrefix>@</AttributePrefix><NamespaceSeparator>:</NamespaceSeparator><NamespaceBlockName>@xmlns</NamespaceBlockName><DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

Element syntax:

<Format>yahoo</Format>

Schemas

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, seeWhat you need to know about policy errors andHandling faults.

Runtime errors

These errors can occur when the policy executes.

These variables are set when a runtime error occurs. For more information, seeWhat you need to know about policy errors.

Example error response

{  "fault": {    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",    "detail": {      "errorcode": "steps.xml2json.SourceUnavailable"    }  }}

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">    <Step>        <Name>AM-SourceUnavailableMessage</Name>        <Condition>(fault.name Matches "SourceUnavailable") </Condition>    </Step>    <Step>        <Name>AM-BadXML</Name>        <Condition>(fault.name = "ExecutionFailed")</Condition>    </Step>    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition></FaultRule>

JSON to XML:JSONtoXML policy