You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info
### 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.
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](https://docs.apigee.com/api-platform/fundamentals/flow-variables-and-conditions)
for an implementation of this scenario.
*** ** * ** ***
### Samples
For a detailed discussion on converting between JSON and XML, see [Converting between XML and JSON with Apigee: What you need to know](https://discuss.google.dev/t/converting-between-xml-and-json-with-apigee-what-you-need-to-know/17451).
### Converting a response
```
responseresponse
```
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.
```
XML to JSON 1responseresponsetruetruetrueNULL#namespaces&***trueTEXTFOO_BLOCKBAR_PREFIX__SUFFIX2teachers/teacher/studentnames/nameyahoo
```
## \ attributes
```
```
The following table describes attributes that are common to all policy parent elements:
| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `` 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` | This attribute is deprecated. | false | Deprecated |
## \ element
Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.
```
Policy Display Name
```
| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|
## \ 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 `` 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.
```
response
```
|---|---|
| **Default** | request or response, determined by where the policy is added to the API proxy flow |
| **Presence** | Optional |
| **Type** | message |
## \ 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`.
```
response
```
|---|---|
| **Default** | request or response, determined by where the policy is added to the API proxy flow |
| **Presence** | This element is mandatory when the variable defined in the `` element is of type string. |
| **Type** | message |
## \
Options give you control over the conversion from XML to JSON. Use either the
`` group, which lets you add specific conversion settings, or the
[``](https://docs.apigee.com/api-platform/reference/policies/xml-json-policy#format) element, which lets you reference a template of
predefined options. You cannot use both `` and
``.
`` is required if `` isn't used.
## \/\ element
If true, then number fields in the XML payload retain their original format.
```
true
```
Consider the following XML example:
```
100value
```
If `true`, converts to:
```
{
"a": {
"b": 100,
"c": "value"
}
}
```
If `false`, converts to:
```
{
"a": {
"b": "100",
"c": "value"
}
}
```
|---|---|
| **Default** | false |
| **Presence** | Optional |
| **Type** | Boolean |
## \/\ element
Lets the conversion maintain boolean true/false values rather than turning the values into
strings.
```
true
```
For the following XML example:
```
truevalue
```
If `true`, converts to:
```
{
"a": {
"b": true,
"c": "value"
}
}
```
If `false`, converts to:
```
{
"a": {
"b": "true",
"c": "value"
}
}
```
|---|---|
| **Default** | false |
| **Presence** | Optional |
| **Type** | Boolean |
## \/\ element
Lets you convert empty values to null values.
```
true
```
For the following XML:
```
value
```
If `true`, converts to:
```
{
"a": {
"b": null,
"c": "value"
}
}
```
If `false`, converts to:
```
{
"a": {
"b": {},
"c": "value"
}
}
```
|---|---|
| **Default** | false |
| **Presence** | Optional |
| **Type** | Boolean |
## \/\ element
Indicates the value to which recognized null values in the source message should be
converted. By default the value is `null`. This option is effective only
if `RecognizeNull` is true.
```
not-present
```
|---|---|
| **Default** | `null` |
| **Presence** | Optional |
| **Type** | String |
## \/\
\/\
\/\ elements
Use these elements together.
```
#namespaces&***
```
Consider the following XML example:
```
value
```
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 ``, you must also specify the other two elements. |
| **Type** | Strings |
## \/\
\/\ elements
Use these elements together.
If set to `true`, the content of the XML element is converted to a string
property.
```
trueTEXT
```
For the following XML:
```
value1value2value3value4
```
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** | ``: false ``: N/A |
| **Presence** | Optional |
| **Type** | ``: Boolean ``: String |
## \/\
\/\ elements
Use these elements together.
Lets you group values into a JSON block and append prefixes to the attribute names.
```
FOO_BLOCKBAR_
```
Consider the following XML example:
```
```
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 |
## \/\
\/\ elements
Use these elements together.
```
PREFIX__SUFFIX
```
Consider the following XML example:
```
value
```
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 |
## \/\ element
```
4
```
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:
```
CODenverSunny62
```
There are 4 levels before you get to the State, City, Description, and Temperature level.
Without using ``, 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
`4`, 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 is `GetCityForecastByZIPResponse`, which has only one
child. So if you were to use `3` (remove the
first three levels), the JSON would look like this:
```
{
"GetCityForecastByZIPResult" : {
"ResponseText" : "City Found",
"ForecastResult" : {
"Forecast" : [
{
"ProbabilityOfPrecipiation" : {
"Nighttime" : "00",
"Daytime" : 10
} ...
```
Notice that `GetCityForecastByZIPResult` has multiple children. Since it's the
first element containing multiple children, you can strip this last level using
`4`, 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.
|---|---|
| **Default** | 0 (no level stripping) |
| **Presence** | Optional |
| **Type** | Integer |
## \/\/\ element
```
teachers/teacher/studentnames/name
```
This element combination lets you ensure that values from an XML document are put in a JSON
array. This is useful, for example, when the number of child elements can vary (from one to
multiple), and you want to ensure the values are always in an array. Doing this helps keep your
code stable, because you can get data from the array the same way every time. For
example: `$.teachers.teacher.studentnames[0]` gets the first student name value
in the array regardless of the number of values in the array.
Let's take a step back and look at the XML to JSON default behavior, then explore how to
control the output using `/`.
When an XML document contains an element with multiple child values (usually based on a schema
where the element's `maxOccurs='unbounded'`), the XML to JSON policy automatically
puts those values in an array. For example, the following XML block
```
teacherAstudent1student2
```
...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 put into 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 as an array, another as
a single string. This is where the `/` element lets
you control the output. You can, for example, make sure that the student names are always put in
an array even if there's only one value. You configure this by identifying the Path to the
element whose values you want to put in an array, like so:
```
teachers/teacher/studentnames/name
```
> [!NOTE]
> **Note:** The Path is **not** JSONPath. It's simply the hierarchical path to the element whose values you want to put in an array.
The configuration above would write the JSON like this:
```
{
"teachers" : {
"teacher" : {
"name" : "teacherA",
"studentnames" : {
"name" : ["student1"]
}
]
}
}
}
```
Notice that student1 is now in an array. Now, regardless of whether there are one or multiple
students, you can retrieve them from a JSON array in your code using the following JSONPath:
`$.teachers.teacher.studentnames.name[0]`
The `` element also has an `unwrap` attribute, explained in
the next section.
|---|---|
| **Default** | NA |
| **Presence** | Optional |
| **Type** | String |
### Attributes
```
teachers/teacher/studentnames/name
```
| Attribute | Description | Presence | Type |
|---|---|---|---|
| unwrap | Default: false Removes the element from the JSON output. Use this to streamline or flatten ("unwrap") the JSON, which also shortens the JSONPath needed to retrieve values. For example, instead of `$.teachers.teacher.studentnames.name[*]`, you could flatten the JSON and use `$.teachers.studentnames[*]`. Here's a JSON example: ``` { "teachers" : { "teacher" : { "name" : "teacherA", "studentnames" : { "name" : [ "student1", "student2" ]}... ``` In this example, you could argue that the `teacher` element and the studentnames `name` element are unnecessary. So you can remove, or unwrap them. Here's how you'd configure the `` element to do this: ``` teachers/teacherteachers/teacher/studentnames/name ``` The `unwrap` attribute is set to true, and the paths to the elements to unwrap are provided. The JSON output will now look like this: ``` { "teachers" : [{ "name" : "teacherA", "studentnames" : ["student1","student2"] }]... ``` Note that because the `` element is in the `` element, both of the elements in the Path will be treated as arrays in the JSON output. | Optional | Boolean |
For more examples and a feature walkthrough, see this Apigee Community article: [Community tutorial: The TreatAsArray option in the XML to JSON policy](https://discuss.google.dev/t/tutorial-the-treatasarray-option-in-the-xmltojson-policy/17573).
## \
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 `` element or the [``](https://docs.apigee.com/api-platform/reference/policies/xml-json-policy#options) group. You cannot use
both `` and ``.
Following are the Format definitions of each predefined template.
### xml.com
```
true#text@
```
### yahoo
```
truecontent
```
### google
```
$t$true
```
### badgerFish
```
$true@:@xmlns$
```
> [!NOTE]
> **Private Cloud:** If you're an Apigee Edge for Private Cloud customer, you can add your own Formats to the following file on each message processor: /opt/apigee/conf/apigee/message-processor/xmltojson-formats.xml. Restart your message processors after modifying the file.
Element syntax:
```
yahoo
```
|---|---|
| **Default** | Enter the name of an available format: `xml.com`, `yahoo`, `google`, `badgerFish` |
| **Presence** | Required if `` isn't used. |
| **Type** | String |
### Schemas
> [!NOTE]
> **Sample:** See our [GitHub
> repository](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy) samples for the most recent schemas.
*** ** * ** ***
## Error reference
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).
### Runtime errors
These errors can occur when the policy executes.
> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.
> [!IMPORTANT]
> **Tip:** Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. See [Set up a policy fault code alert](https://docs.apigee.com/api-monitoring/alerts-notifications#fault-code-alert) for an example. See [Fault code reference](https://docs.apigee.com/api-monitoring/fault-codes) for a complete list of all fault codes that you can handle with API Monitoring.
| Fault code | HTTP status | Cause | Fix |
|---|---|---|---|
| `steps.xmltojson.ExecutionFailed` | 500 | This error occurs when the input payload (XML) is empty or the input XML is invalid or malformed. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/xmltojson-runtime-errors#executionfailed) |
| `steps.xmltojson.InCompatibleType` | 500 | This error occurs if the type of the variable defined in the `` element and the `` element are not the same. It is mandatory that the type of the variables contained within the `` element and the `` element matches. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/xmltojson-runtime-errors#incompatibletypes) |
| `steps.xmltojson.InvalidSourceType` | 500 | This error occurs if the type of the variable used to define the `` element is invalid.The valid types of variable are message and string. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/xmltojson-runtime-errors#invalidsourcetype) |
| `steps.xmltojson.OutputVariableIsNotAvailable` | 500 | This error occurs if the variable specified in the `` element of the XML to JSON policy is of type string and the `` element is not defined. The `` element is mandatory when the variable defined in the `` element is of type string. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/xmltojson-runtime-errors#outputvariableisnotavailable) |
| `steps.xmltojson.SourceUnavailable` | 500 | This error occurs if the [message](https://docs.apigee.com/api-platform/reference/variables-reference#messagevariables) variable specified in the `` element of the XML to JSON policy is either: - out of scope (not available in the specific flow where the policy is being executed) or - can't be resolved (is not defined) | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/xmltojson-runtime-errors#sourceunavailable) |
### Deployment errors
These errors can occur when you deploy a proxy containing this policy.
> [!IMPORTANT]
> Need help resolving an error? Click in the Fix column for detailed troubleshooting information.
| Error name | Cause | Fix |
|---|---|---|
| `EitherOptionOrFormat` | If one of the elements `` or `` is not declared in the XML to JSON Policy, then the deployment of the API proxy fails. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/xmltojson-deployment-errors#eitheroptionorformat) |
| `UnknownFormat` | If the `` element within the XML to JSON policy has an unknown format defined, then the deployment of the API proxy fails. Predefined formats include: `xml.com`, `yahoo`, `google`, and `badgerFish`. | [](https://docs.apigee.com/api-platform/troubleshoot/policies/deployment/xmltojson-deployment-errors#unknownformat) |
### Fault variables
These variables are set when a runtime error occurs. For more information, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors).
| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | fault_name is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/xml-json-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name = "SourceUnavailable"` |
| `xmltojson.policy_name.failed` | policy_name is the user-specified name of the policy that threw the fault. | `xmltojson.XMLtoJSON-1.failed = true` |
### Example error response
> [!NOTE]
> **Note:** For error handling, the best practice is to trap the `errorcode` part of the error response. Do not rely on the text in the `faultstring`, because it could change.
```
{
"fault": {
"faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
"detail": {
"errorcode": "steps.xml2json.SourceUnavailable"
}
}
}
```
### Example fault rule
```
AM-SourceUnavailableMessage(fault.name Matches "SourceUnavailable") AM-BadXML(fault.name = "ExecutionFailed")(xmltojson.XMLtoJSON-1.failed = true)
```
## Related topics
> [!NOTE]
> **Sample:** For working samples of API proxies, see the [Samples list](https://docs.apigee.com/api-platform/samples/samples-reference).
JSON to XML: [JSON to XML
policy](https://docs.apigee.com/api-platform/reference/policies/json-xml-policy)