<!-- BusyBot node reference — https://busybot.net/tools/xml/ -->

> Node: XML (`xml`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# XML

> Convert between XML and JSON

## Overview

The XML tool converts data between XML and JSON. In xmlToJson mode, it parses an XML string from an item field into a JSON object. In jsonToXml mode, it builds an XML string from a JSON object. Uses the xml2js library with configurable options for attribute handling, arrays, root elements, and more.

**Category:** Core Nodes  
**Tool Name:** `xml`  
**Version:** 1

**Appearance:** Icon: `lucide-FileCode` | Color: `#333399`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mode | `options` | No | `xmlToJson` | Conversion direction. |
| | | | | Options: `jsonToXml`, `xmlToJson` |
| Property Name | `string` | Yes | `data` | The name of the property containing the data to convert. The converted value is written back to this same property. |
| Options | `collection` | No | `{}` | Parser and builder settings; which ones apply depends on Mode. |
| — Attribute Key | `string` | No | `$` | Prefix for XML attribute keys in the JSON output. |
| — Character Key | `string` | No | `_` | Key for character content in mixed-content elements. |
| — Explicit Array | `boolean` | No | `false` | Always put child nodes in an array (even single elements). _(shown when Mode is `xmlToJson`)_ |
| — Explicit Root | `boolean` | No | `true` | Whether to include the root element in the JSON output. _(shown when Mode is `xmlToJson`)_ |
| — Ignore Attributes | `boolean` | No | `false` | Ignore all XML attributes. _(shown when Mode is `xmlToJson`)_ |
| — Merge Attributes | `boolean` | No | `true` | Merge attributes and child elements as properties of the parent. _(shown when Mode is `xmlToJson`)_ |
| — Normalize | `boolean` | No | `false` | Trim whitespace inside text nodes. _(shown when Mode is `xmlToJson`)_ |
| — Normalize Tags | `boolean` | No | `false` | Normalize all tag names to lowercase. _(shown when Mode is `xmlToJson`)_ |
| — Trim | `boolean` | No | `false` | Trim leading/trailing whitespace from text nodes. _(shown when Mode is `xmlToJson`)_ |
| — Allow Surrogate Chars | `boolean` | No | `false` | Allow surrogate character pairs in XML output. _(shown when Mode is `jsonToXml`)_ |
| — CDATA | `boolean` | No | `false` | Wrap text nodes in CDATA sections. _(shown when Mode is `jsonToXml`)_ |
| — Headless | `boolean` | No | `false` | Omit the XML declaration header. _(shown when Mode is `jsonToXml`)_ |
| — Root Name | `string` | No | — | Root element name (if input JSON has no root element). _(shown when Mode is `jsonToXml`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The conversion happens **in place**: the property named by **Property Name** is overwritten with the converted value. Every other field in the item JSON passes through unchanged, and binary data is forwarded.

- **`xmlToJson`** — the property must hold an XML **string**, or the item fails with `Property "<name>" does not contain a string value`. It is replaced by the parsed object. Attribute Key and Character Key control where attributes and mixed text end up; note that Merge Attributes is on by default, so attributes appear as ordinary properties of their element rather than nested under the attribute key.
- **`jsonToXml`** — the property is replaced by the generated XML string. An object is serialized directly; a string value is parsed as JSON first, so a stringified payload works too. Root Name supplies the wrapping element when the object does not already have a single root.

Reference the result downstream by expression, e.g. `{{ $json.data }}`.

## Usage Examples

- Parse XML API response into JSON
- Build XML payload from JSON data
- Convert XML string field to navigable JSON object

## Example Configuration

Basic XML to JSON conversion:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "xmlToJson",
    "dataPropertyName": "xmlData"
  }
}
```

XML to JSON with custom options:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "xmlToJson",
    "dataPropertyName": "xmlContent",
    "maxConcurrency": 5,
    "options": {
      "attrkey": "attributes",
      "charkey": "text",
      "explicitArray": true,
      "ignoreAttrs": false,
      "trim": true,
      "normalize": true
    }
  }
}
```

JSON to XML conversion:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "jsonToXml",
    "dataPropertyName": "jsonData",
    "options": {
      "rootName": "document",
      "attrkey": "$",
      "charkey": "_",
      "headless": false,
      "cdata": true
    }
  }
}
```

High-concurrency parsing with a flattened result:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "xmlToJson",
    "dataPropertyName": "batchData",
    "maxConcurrency": 20,
    "options": {
      "explicitRoot": false,
      "mergeAttrs": true,
      "normalizeTags": true,
      "trim": true
    }
  }
}
```

Convert a fetched RSS/XML feed to JSON:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "xmlToJson",
    "dataPropertyName": "feedXml",
    "options": {
      "attrkey": "attr",
      "charkey": "content",
      "explicitArray": false,
      "trim": true,
      "normalize": true,
      "ignoreAttrs": false
    }
  }
}
```

Generate clean XML from structured JSON:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "jsonToXml",
    "dataPropertyName": "structuredData",
    "options": {
      "rootName": "root",
      "headless": false,
      "allowSurrogateChars": false,
      "attrkey": "@",
      "charkey": "#text"
    }
  }
}
```

Parse a configuration file:

```json
{
  "type": "xml",
  "parameters": {
    "mode": "xmlToJson",
    "dataPropertyName": "configXml",
    "options": {
      "explicitRoot": true,
      "mergeAttrs": true,
      "trim": true,
      "normalizeTags": false,
      "explicitArray": false
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Converts between XML strings and JSON objects using xml2js with configurable parser/builder options.

### Behavior notes

- **Explicit Array changes the shape of everything downstream.** Left off, a single `<item>` becomes an object and two become an array, so expressions that work on one feed break on another. Turn it on when the feed's cardinality varies and always index (`{{ $json.data.rss.channel[0].item }}`).
- **Attribute Key and Character Key apply in both directions.** Whatever you choose when parsing is what you must use when building XML back out of the same structure.
- **The source property is overwritten.** If you need the original XML as well, copy it to another field before this node.