Send Docs Feedback

XML to JSON policy

  About | Samples | Element reference | Error codes | Related topics

What

This 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.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

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).

About

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. See Flow variables and conditions for an implementation of this scenario.


Samples

For a detailed discussion on converting between JSON and XML, see http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

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

This configuration—which is the minimal configuration required to convert XML to JSON—takes an XML-formatted response message as the source, and then creates a JSON-formatted message that is populated in the response OutputVariable. Edge automatically uses the content of this variable as the message for next processing step.


Element reference

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

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</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>
    </Options>
</XMLToJSON>

<XMLtoJSON> attributes

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

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<DisplayName> element

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

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<Source> element

The variable, request or response, that contains the XML message that you want to convert to JSON.

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

If <Source> is not defined, then it is treated as message (which resolves to request when the policy is attached to a request flow, or response 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>
Default request or response, determined by where the policy is added to the API proxy flow
Presence Optional
Type message

<OutputVariable> element

Stores the output of the XML to JSON format conversion. This is usually the same value as the source, that is, usually XML response is converted to a JSON response.

The payload of the XML message is parsed and converted into JSON, and the HTTP Content-type header of the XML-formatted message is set to application/json.

If OutputVariable is not specified, the source is treated as OutputVariable. For example, if the source is response, then OutputVariable defaults to response.

<OutputVariable>response</Response>
Default request or response, determined by where the policy is added to the API proxy flow
Presence Optional
Type message

<Options>/<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>

If true, converts to:

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

If false, converts to:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}
Default false
Presence Optional
Type Boolean

<Options>/<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>

If true, converts to:

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

If false, converts to:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}
Default false
Presence Optional
Type Boolean

<Options>/<RecognizeNull> element

Lets you convert empty values to null values.

<RecognizeNull>true</RecognizeNull>

For the following XML:

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

If true, converts to:

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

If false, converts to:

{
  "a": {
    "b": {},
    "c": "value"
  }
}
Default false
Presence Optional
Type Boolean

<Options>/<NullValue> element

Indicates what constitutes a null value in the message to be converted. By default the value is NULL.

<NullValue>NULL</NullValue>
Default NULL
Presence Optional
Type String

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> elements

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>

If NamespaceSeparator is not specified, the following JSON structure is generated:

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

If the elements NamespaceBlockName, DefaultNamespaceNodeName, and NamespaceSeparator 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"
    }
}
Default See examples above.
Presence Optional
However, if you specify <NamespaceBlockName>, you must also specify the other two elements.
Type Strings

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName> elements

Use these elements together.

If set to true, the content of the XML element is converted to a string property.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

For the following XML:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

If TextAlwaysAsProperty is set to true and TextNodeName specified as TEXT, the following JSON structure is generated:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

If TextAlwaysAsProperty is set to false and TextNodeName specified as TEXT, the following JSON structure is generated:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}
Default <TextAlwaysAsProperty>: false
<TextNodeName>: N/A
Presence Optional
Type <TextAlwaysAsProperty>: Boolean
<TextNodeName>: String

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> elements

Use these elements together.

Lets you group 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 and AttributePrefix) 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 only AttributeBlockName is specified, the following JSON structure is generated:

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

If only AttributePrefix 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"
    }
}
Default See examples above.
Presence Optional
Type String

<Options>/<OutputPrefix>
<Options>/<OutputSuffix> elements

Use these elements together.

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

Consider the following XML example:

<a>value</a>

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

PREFIX_{
    "a": "value"
}_SUFFIX

If only OutputPrefix is specified, the following JSON structure is generated:

PREFIX_{
  "a" : "value"
}

If only OutputSuffix is specified, the following JSON structure is generated:

{
  "a" : "value"
}_SUFFIX

If neither OutputPrefix nor OutputSuffix is specified, the following JSON structure is generated:

{
    "a": "value"
}
Default See samples above.
Presence Optional
Type String

Schemas

See our GitHub repository samples for the most recent schemas.


Error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The XMLToJSON Policy type defines the following error codes:

Error Code Message
FormatUnavailable XMLToJSON[{0}]: Format {1} is not available
SourceUnavailable XMLToJSON[{0}]: Source {1} is not available
ExecutionFailed XMLToJSON[{0}]: Execution failed. reason: {1}
InvalidSourceType JSONToXML[{0}]: Invalid source type {0}. Valid source types are {1}.
InCompatibleTypes JSONToXML[{0}]: String can not be assigned to message type.
OutputVariableIsNotAvailable JSONToXML[{0}]: Output variable is not available.

Related topics

For working samples of API proxies, see the Samples reference.

JSON to XML: JSON to XML policy

Help or comments?