Was this helpful?

Apigee Edge enables developers to convert messages from the JavaScript object notation (JSON) format to the extensible markup language (XML) format by using the JSONtoXML policy type. This policy is useful for enabling backend XML services to support RESTful apps that require JSON (for example, due to a lack of an XML parsing capabilities on the client).

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

For scenarios where APIs are consumed by diverse clients apps which may require either JSON and XML, the format of the response can be dynamically set by configuring JSONtoXML and XMLtoJSON policies to execute conditionally.

See Flow variables and conditions for an implementation of this scenario.

Sample

A set of configuration options are provided to customize the XML output by the JSONtoXML policy. The JSONtoXML policy defines a set of reasonable defaults. It is often useful to apply the default (empty) JSONtoXML policy and iteratively add configuration elements as required.

The minimum required configuration is the following:

<JSONToXML name="jsontoxml">
  <Options>
  </Options>
</JSONToXML>

Configuring a JSONtoXML policy

All elements in this policy type are optional unless you need to define XML namespaces. If NamespaceBlockName is set, DefaultNamespaceNodeName and NamespaceSeparator must also be specified.

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

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

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
Source The variable containing the JSON-formatted message to be converted to XML. Usually, you set this to request or response, depending on whether the message to be transformed is inbound or outbound.
  • If source is missing, it is treated as a simple message. For example, <Source>message</Source>
  • If the source variable cannot be resolved, or resolves to a non-message type, the policy execution fails.
OutputVariable

The variable name of the resultant XML-formatted message. Usually, you set this to request or response, depending on whether the message to be transformed is inbound or outbound. In most cases, an JSON request is transformed into an XML request. Similarly, a JSON response is usually transformed into an XML response.

If OutputVariable is not specified, then the source variable is treated as OutputVariable. That is, the policy assumes that a JSON request, for example, is being converted into an XML request.

InvalidCharsReplacement
To assist with handling invalid XML that may cause issues with a parser, this setting replaces any JSON elements that produce invalid XML with the string. For example, the following setting:
<InvalidCharsReplacement>_</InvalidCharsReplacement>

Converts this JSON object

{
    "First%%%Name": "John"
}

to this XML structure:

<First_Name>John<First_Name>
TextNodeName

Converts a JSON property into an XML text node with the specified name. For example, the following setting:

<TextNodeName>age</TextNodeName>

converts this JSON:

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

to this XML structure:

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

If TextNodeName is not specified, the XML is generated, using the default setting for a text node:

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>
NullValue Indicates a null value. By default the value is NULL.

For example the following setting:

<NullValue>I_AM_NULL</NullValue>
Converts the following JSON object:
{"person" : "I_AM_NULL"}

to the following XML element:

<person></person>

Where no value (or a value other than I_AM_NULL) is specified for the Null value, then the same payload converts to:

<person>I_AM_NULL</person>
AttributeBlockName

Enables you to specify when JSON elements are converted into XML attributes (rather than XML elements).

For example, the following setting converts properties inside an object named #attrs into XML attributes:

<AttributeBlockName>#attrs</AttributeBlockName>

The following JSON object:

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },        
        "occupation" : "explorer",
    }
}

is converted to the following XML structure:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>
AttributePrefix

Converts the property starting with the specified prefix into XML attributes. Where the attribute prefix is set to @, for example:

<AttributePrefix>@</AttributePrefix>

Converts the following JSON object:

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

to the following XML structure:

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>
NamespaceBlockName

JSON has no support for namespaces, while XML documents often require them. The NamespaceBlockName enables you to define a JSON property that serves as the source of a namespace definition in the XML that is produced by the policy. (This means that the source JSON must provide a property that can be mapped into a namespace that is expected by application that consumes the resulting XML.)

For example, the following settings:

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

indicates that a property called #namespaces exists in the source JSON that contains at least one namespace designated as the default. For example:

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "xmlns:exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}
converts to:
<person xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</person>
ArrayRootElementName

Converts a JSON array into a list of XML elements with specified parent and child element names.

For example, the following settings:

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

Converts the following JSON array:

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

into the following XML structure:

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

Policy-specific error codes

The default format for error codes returned by Policies is:

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

The JSONToXML Policy type defines the following error codes:

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

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)