JSONtoXML policy

Standard policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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

The policy is particularly useful if you want to transform messages using XSL. After converting a JSON payload to XML, use the XSL Transform policy with a custom style sheet to perform the transformation you need.

Note: The HTTP Content-type header of the source message must be set to application/json, otherwise the policy is not enforced, meaning it is skipped during processing.

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

This policy is a Standard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, see Policy types.

Samples

For a detailed discussion, see Converting between XML and JSON with Apigee: what you need to know.

Converting a request

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

This configuration takes JSON-formatted request message as the source, and then creates an XML-formatted message that is populated in the request OutputVariable. Apigee 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.

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

<JSONToXML> 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 `<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. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	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

<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

Default	N/A If you omit this element, the value of the policy's `name` attribute is used.
Presence	Optional
Type	String

N/A

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

Presence Optional

Type String

<Source> element

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

Note: The HTTP Content-type header of the source message must be set to application/json, otherwise the policy is not enforced, meaning it is skipped during processing.

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>request</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 JSON to XML format conversion. This is usually the same value as the source, that is, usually a JSON request is converted to an XML request.

The payload of the JSON message is parsed and converted into XML, and the HTTP Content-type header of the XML-formatted message is set to text/xml;charset=UTF-8.

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

<OutputVariable>request</OutputVariable>

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 `<Source>` element is of type string.
Type	message

<Options>/<OmitXmlDeclaration>

Specifies to omit the XML declaration line from the output. An XML declaration line can optionally appear at the top of an XML document. A typical example looks like this:

<?xml version="1.0" encoding="UTF-8"?>

In some cases it's important to avoid including such a line in the output of this policy. One good example is if you plan to embed the output of this policy as a fragment into a larger XML document. Because the declaration must appear only once in a document, and only at the top of the document, it would be important in that case to suppress the XML declaration line in the XML fragment.

The default value for this option is false, which means the policy will include the XML declaration line in the output. The following setting will configure the policy to omit the XML Declaration:

<OmitXmlDeclaration>true</OmitXmlDeclaration>

There is no way to shape or affect the contents of the XML declaration line via the configuration of this policy. The policy always generates UTF-8 encoded text, and always uses XML version 1.0, and the declaration line, if it is included, will reflect that.

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

JSON has no support for namespaces, while XML documents often require them. 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",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

converts to:

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

<Options>/<ObjectRootElementName>

<ObjectRootElementName> specifies the root element name when you convert from JSON, which does not have a named root element, to XML.

For example, if the JSON appears as:

{
  "abc": "123",
  "efg": "234"
}

And you set <ObjectRootElementName> as:

<ObjectRootElementName>Root</ObjectRootElementName>

The resultant XML appears as:

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

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

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

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> element

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>

<Options>/<Indent>

Specifies to indent the XML output. The default value is false meaning do not indent.

For example, the following setting configures the policy to indent the output:

<Indent>true</Indent>

If the JSON input is in the form:

{"n": [1, 2, 3] }

Then the output without intdenting is:

<Array><n>1</n><n>2</n><n>3</n></Array>

With indenting enabled, the output is:

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

<Options>/<TextNodeName> element

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>

<Options>/<NullValue> element

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>

<Options>/<InvalidCharsReplacement> element

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>

Usage notes

In a typical mediation scenario, a JSON to XML 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.

It is often useful to apply the default (empty) JSON to XML policy and iteratively add configuration elements as required.

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 JSON to XML and XML to JSON policies to execute conditionally. See Flow variables and conditions for an implementation of this scenario.

Schemas

Error reference

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因
`steps.jsontoxml.ExecutionFailed`	`500`	输入负载 (JSON) 为空，或传递给 JSON 到 XML 政策的输入 (JSON) 无效或格式错误。
`steps.jsontoxml.InCompatibleTypes`	`500`	如果 `<Source>` 元素和 `<OutputVariable>` 元素中定义的变量类型不同，则会发生此错误。`<Source>` 元素中包含的变量类型和 `<OutputVariable>` 元素必须完全匹配。有效类型为 `message` 和 `string`。
`steps.jsontoxml.InvalidSourceType`	`500`	如果用于定义 `<Source>` 元素的变量类型无效，则会发生此错误。变量的有效类型为 `message` 和 `string`。
`steps.jsontoxml.OutputVariableIsNotAvailable`	`500`	如果 JSON 到 XML 政策的 `<Source>` 元素中指定的变量为字符串类型，且未定义 `<OutputVariable>` 元素，则会发生此错误。如果 `<Source>` 元素中定义的变量为字符串类型，则 `<OutputVariable>` 元素是必填的。
`steps.jsontoxml.SourceUnavailable`	`500`	如果 JSON 到 XML 政策的 `<Source>` 元素中指定的消息变量是以下情况之一，则会发生此错误：超出范围（在执行政策的特定流中不可用）无法解析（未定义）

部署错误

无。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	其中	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name Matches "SourceUnavailable"`
`jsontoxml.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`jsontoxml.JSON-to-XML-1.failed = true`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

故障规则示例

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

JSONtoXML policy Stay organized with collections Save and categorize content based on your preferences.

Samples

Converting a request

Element reference

<JSONToXML> attributes

<DisplayName> element

<Source> element

<OutputVariable> element

<Options>/<OmitXmlDeclaration>

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

<Options>/<ObjectRootElementName>

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

<Options>/<ArrayRootElementName> <Options>/<ArrayItemElementName> element

<Options>/<Indent>

<Options>/<TextNodeName> element

<Options>/<NullValue> element

<Options>/<InvalidCharsReplacement> element

Usage notes

Schemas

Error reference

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

Related topics

JSONtoXML policy

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

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

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> element