jsonify-xml

A lightweight and efficient library for converting XML to JSON. Perfect for developers needing a simple yet powerful solution to transform XML data structures into JSON format with ease. Ideal for web applications, API integrations, and data parsing workflows.

It does not parse the following elements:

• CDATA sections (*)
• Processing instructions
• XML declarations
• Entity declarations
• Comments

Installation

1npm install jsonify-xml

Usage

1import { jsonify } from "jsonify-xml";
2import path from "path";
3import customValueParser from "../src/helpers/customValueParser";
4
5// Option 1: Simple XML string
6const jsonResult = jsonify(xmlString);
7
8// Option 2: XML String with custom data parser
9const options: JsonifyXMLOptions = {
10	xml: xmlString,
11	valueParser: customValueParser,
12	parseAttributes: true
13}
14const jsonResult = jsonify(options);
15
16// Option 3: XML file
17const options: JsonifyXMLOptions = {
18	input: path.join(__dirname, "path/to/xml/file"),
19	output: path.join(__dirname, "path/to/json/output")
20	valueParser: "string"
21}
22const jsonResult = jsonify(options);

Options

Option	Description	Type
xml	XML content as a string. Required if the input option is not provided.	string
input	Path to the XML source file. Required if the xml option is not provided.	string
output	Path to the JSON output file. Optional.	string
valueParser	Specifies how to parse XML tag or attribute values. It can either be "string", which keeps values in their original string format, or a custom function for custom parsing	"string" | "default" or function
parseAttributes	Determines whether to parse attribute values or leave them as strings. Optional.	boolean
santize	Determines whether special XML characters are replaced with their corresponding ASCII values. Defaults to true. Optional.	boolean

Special Characters Sanitization

The sanitizing process handles the following special XML characters:

1const specialCharsMap = {
2    "&": "&",
3    '"': """,
4    "'": "'",
5    "<": "&lt;",
6    ">": "&gt;",
7    "(": "&#40;",
8    ")": "&#41;",
9    "#": "&#35;",
10    " ": "&#32;",
11    "%": "&#37;",
12    "+": "&#43;",
13    "-": "&#45;",
14    ".": "&#46;",
15    "/": "&#47;",
16    ":": "&#58;",
17    ";": "&#59;",
18    "=": "&#61;",
19    "?": "&#63;",
20    "@": "&#64;",
21    "[": "&#91;",
22    "]": "&#93;",
23    "_": "&#95;",
24    "`": "&#96;",
25    "{": "&#123;",
26    "|": "&#124;",
27    "}": "&#125;",
28    "~": "&#126;",
29    "^": "&#94;",
30    "\\": "&#92;",
31    "$": "&#36;",
32    "!": "&#33;",
33    "*": "&#42;",
34    ",": "&#44;",
35    "\n": "&#10;",
36    "\r": "&#13;",
37    "\t": "&#9;",
38    "©": "&#169;",
39    "®": "&#174;",
40    "¢": "&#162;",
41    "£": "&#163;",
42    "¥": "&#165;",
43    "€": "&#8364;",
44    "§": "&#167;",
45    "•": "&#8226;",
46    "°": "&#176;",
47    "¶": "&#182;",
48    "∞": "&#8734;",
49    "÷": "&#247;",
50    "×": "&#215;",
51    "±": "&#177;",
52    "²": "&#178;",
53    "³": "&#179;",
54    "¼": "&#188;",
55    "½": "&#189;",
56    "¾": "&#190;"
57};

It also handles decimal and hex numbers using:

1const decimalNum = /&#([0-9]+);/g;
2const hexNum = /&#x([0-9A-Fa-f]+);/g;

It also handles numeric references, both decimal and hexadecimal, using the following regular expressions:

• Decimal Numeric References: Matches numeric references like A which represent characters by their decimal Unicode value.

1const decimalNum = /&#([0-9]+);/g;

• Hexadecimal Numeric References: Matches numeric references like A which represent characters by their hexadecimal Unicode value.

1const hexNum = /&#x([0-9A-Fa-f]+);/g;

Example

input.xml

1<Order status="active" priority="high" isUrgent="false" itemCount="3">
2	<DeliveryPerson>John Doe</DeliveryPerson>
3  <IsCanceled>false</IsCanceled>
4	<IsDelivered>true</IsDelivered>
5	<OrderCode>12345</OrderCode>
6	<OrderDate>2024-11-09</OrderDate>
7</Order>

index.ts

1import path from "path";
2import { jsonify, JsonifyXMLOptions, JsonifyResult, Node } from "../src";
3import { docs } from "./docs";
4
5const INPUT = path.join(__dirname, "index.xml");
6const OUTPUT = path.join(__dirname, "output.json");
7
8const options: JsonifyXMLOptions = {
9    input: INPUT,
10    output: OUTPUT,
11    valueParser,
12    parseAttributes: true,
13    sanitize: true
14};
15
16const [rootName, jsonResult]: JsonifyResult = jsonify(options);
17const order: Node = jsonResult[rootName];
18
19console.log(order.attributes.status, result.tagname, result.value, result.nodes.DeliveryPerson.value);
20
21function valueParser(value: string) {
22    // Check if value is a boolean
23    if (value.toLowerCase() === 'true') return true;
24    if (value.toLowerCase() === 'false') return false;
25    
26    // Check if value is a number
27    const num = Number(value);
28    if (!isNaN(num)) return num;
29    
30    // Check if value is a valid date
31    const date = Date.parse(value);
32    if (!isNaN(date)) return new Date(date);
33
34    // Default case: return the original string
35    return value;
36}

output.json

1[
2  "Order",
3  {
4    "Order": {
5      "tagname": "Order",
6      "attributes": {
7        "status": "active",
8        "priority": "high",
9        "isUrgent": false,
10        "itemCount": 3
11      },
12      "nodes": {
13        "DeliveryPerson": {
14          "tagname": "DeliveryPerson",
15          "value": "John Doe"
16        },
17        "IsCanceled": {
18          "tagname": "IsCanceled",
19          "value": false
20        },
21        "IsDelivered": {
22          "tagname": "IsDelivered",
23          "value": true
24        },
25        "OrderCode": {
26          "tagname": "OrderCode",
27          "value": 12345
28        },
29        "OrderDate": {
30          "tagname": "OrderDate",
31          "value": "2024-11-09T00:00:00.000Z"
32        }
33      }
34    }
35  }
36]