Convert XML text to Javascript object / JSON text (and vice versa).

Synopsis

Motivation

There are many XML to JavaScript object / JSON converters out there, but could not satisfy the following requirements:

• Maintain Order of Sub-elements: Instead of converting <a/><b/><a/> to {a:[{},{}],b:{}}, I wanted to preserve order of elements by doing this: {"elements":[{"type":"element","name":"a"},{"type":"element","name":"b"},{"type":"element","name":"a"}]}.

• Fully XML Compliant: Can parse: Comments, Processing Instructions, XML Declarations, Entity declarations, and CDATA Sections.

• Reversible: Whether converting xml→json or json→xml, the result should be convertable to its original form.

• Change Property Key Name: Usually output of XML attributes are stored in @attr, _atrr, $attr, $, or whatever in order to avoid conflicting with name of sub-elements. This library store them in attributes, but most importantly, you can change this to whatever you like.

• Portable Code: Written purely in JavaScript (this is default behavior, but this can be slow for very large XML text).

• Fast Code (if required): With little effort, the underlying sax engine (based on JavaScript) can be sustituted with node-expat engine (based on VC++).

• Support Command Line: To quickly convert xml or json files, this module can be installed globally or locally (i.e. use it as script in package.json).

• Support Streaming: ...

Compact vs Non-Compact

Most XML parsers (including online parsers) convert <a/> to some compact output like {"a":{}} instead of non-compact output like {"elements":[{"type":"element","name":"a"}]}.

While compact output might work in most situations, there are cases when different elements are mixed inside a parent element: <n><a x="1"/><b x="2"/><a x="3"/></n>. In this case, the compact output will be {n:{a:[{_:{x:"1"}},{_:{x:"3"}}],b:{_:{x:"2"}}}}, which has merged the second <a/> with the first <a/> into an array and so the order is not preserved.

Although non-compact output is more accurate representation of original XML than compact version, the non-compact consumes more space. This library provides both options. Use {compact: false} if you are not sure because it preserves everything; otherwise use {compact: true} if you want to save space and you don't care about mixing elements of same type.

Usage

Installation

npm install xml-js

You can also installed it globally to use it as a command line convertor.

npm install -g xml-js

Quick start

var convert = require('xml-js');
var xml = 
'<?xml version="1.0" encoding="utf-8"?>' +
'<note importance="high" logged="true">' +
'    <title>Happy</title>' +
'    <todo>Work</todo>' +
'    <todo>Play</todo>' +
'</note>';
var result1 = convert.xml2json(xml, {compact: true, spaces: 4});
var result2 = convert.xml2json(xml, {compact: false, spaces: 4});
console.log(result1, '\n', result2);

To see the output of this code, see the picture above in Synopsis section.

Sample Conversions

API Reference

Convert JS object / JSON → XML

To convert JavaScript object to XML text, use js2xml(). To convert JSON text to XML text, use json2xml().

var convert = require('xml-js');
var json = require('fs').readFileSync('test.json', 'utf8');
var options = {ignoreText: true, spaces: 4};
var result = convert.json2xml(json, options);
console.log(result);

Options for Converting JS object / JSON → XML

The below options are applicable for both js2xml() and json2xml() functions.

Convert XML → JS object / JSON

To convert XML text to JavaScript object, use xml2js(). To convert XML text to JSON text, use xml2json().

var convert = require('xml-js');
var xml = require('fs').readFileSync('test.xml', 'utf8');
var options = {ignoreText: true, alwaysChildren: true};
var result = convert.xml2js(xml, options); // or convert.xml2json(xml, options)
console.log(result);

Options for Converting XML → JS object / JSON

The below options are applicable for both xml2js() and xml2json() functions.

The below option is applicable only for xml2json() function.

Options for Changing Key Names

To change default key names in the output object or the default key names assumed in the input JavaScript object / JSON, use the following options:

Note: You probably want to set {textKey: 'value', cdataKey: 'value', commentKey: 'value'} for non-compact output to make it more consistent and easier for your client code to go through the contents of text, cdata, and comment.

Command Line

Because any good library should support command line usage, this library is no difference.

As Globally Accessible Command

npm install -g xml-js       // install this library globally
xml-js test.json            // test.json will be converted to test.xml
xml-js test.xml             // test.xml will be converted to test.json

As Locally Accessible Command

If you want to use it as script in package.json (can also be helpful in task automation via npm scripts)

npm install --save xml-js   // no need to install this library globally

In package.json, write a script:

...
  "dependencies": {
    "xml-js": "latest"
  },
  "scripts": {
     "convert": "xml-js test.json"
  }

npm run convert             // task 'scripts.convert' will be executed

CLI Arguments

Usage: xml-js src [options]

  src                  Input file that need to be converted.
                       Conversion type xml->json or json->xml will be inferred from file extension.

Options:
  --help, -h           Display this help content.
  --version, -v        Display number of this module.
  --out                Output file where result should be written.
  --spaces             Specifies amount of space indentation in the output.
  --full-tag           XML elements will always be in <a></a> form.
  --no-decl            Declaration instruction <?xml ..?> will be ignored.
  --no-attr            Attributes of elements will be ignored.
  --no-text            Texts of elements will be ignored.
  --no-cdata           Cdata of elements will be ignored.
  --no-comment         Comments of elements will be ignored.
  --trim               Whitespaces surrounding texts will be trimmed.
  --compact            JSON is in compact form.
  --sanitize           Special xml characters will be replaced with entity codes.
  --native-type        Numbers and boolean will be converted (coreced) to native type instead of text.
  --always-children    Every element will always contain sub-elements (applicable if --compact is not set).
  --text-key           To change the default 'text' key.
  --cdata-key          To change the default 'cdata' key.
  --comment-key        To change the default 'comment' key.
  --attributes-key     To change the default 'attributes' key.
  --declaration-key    To change the default 'declaration' key.
  --type-key           To change the default 'type' key (applicable if --compact is not set).
  --cdata-key          To change the default 'name' key (applicable if --compact is not set).
  --elements-key       To change the default 'elements' key (applicable if --compact is not set).

Contribution

Comparison with Other Libraries

xml2js xml2json xml-objects xml-js-converter fast-xml2js co-xml2js xml-simple xml2js-expat

Testing

To perform tests on this project:

cd node_modules/xml-js
npm install
npm test

For live testing, use npm start instead of npm test.

Reporting

Use this link to report an issue or bug. Please include a sample code or Jasmine test spec where the code is failing.

License

MIT