Nupital Pomp Mesmerises


    1.8.7 • Public • Published

    Blue Button XML

    Blue Button XML Parsing Infrastructure


    Build Status Coverage Status

    This library provides the following functionality

    • Parse XML documents and find XML elements using XPath via libxmljs (node.js) or DomParser (browsers).
    • Use XPath based formalism to simplify XML to JSON transforms.

    blue-button-xml is primarily designed to support blue-button parsers to convert CCDA or C32 based XML health data into JSON according to the model in blue-button-model. Full XML to JSON transformations such as xml2s are not appropriate for such conversions since not all data in the XML files are clinically significant or useful and often normalization is necessary. blue-button-xml formalism simplifies selection and normalization of XML elements into a JSON model.

    This library is primarily implemented for node.js and is available via npm. A browser version is also available via bower. The browser version is created using browserify and can be used in the same way that you would use it in node.js.

    Quick up and running guide


    • Node.js (v14.19+) and NPM
    • Grunt
    # Install dependencies
    npm i
    # Install grunt
    npm i -g grunt
    # Test


    Require blue-button-xml module

    var bbxml = require("@amida-tech/blue-button-xml");

    and load some XML content in an example.xml

    <?xml version="1.0" encoding="UTF-8"?>
      <root name="example">
        <element ready="true">82</element>
        <element ready="false">16</element>
    var data = fs.readFileSync('example.xml', 'utf-8');

    XML Utilities

    Parse data into an XML object

    var doc = bbxml.xmlUtil.parse(data)

    Use XPath to find XML elements

    var nodes = bbxml.xmlUtil.xpath(doc, "//element[@ready='true']/text()");

    Convert text or attribute nodes to values

    var value = bbxml.processor.asString(nodes[0]);
    console.log(value); // 82

    XML to JSON Conversion Infrastructure

    Define hieararchical parsers, JSON keys, JSON values and cardinality using component and processor

    var component = bbxml.component;
    var processor = bbxml.processor;
    var element = component.define("element");
      ["value", "1..1", "text()", processor.asFloat],
      ["flag", "0..1", "@ready", processor.asBoolean]
    var compA = component.define("compA");
      ["name", "0..1", "@name", processor.asString],
      ["element", "1..*", "element", element]
    var root = component.define("root");
      ["data", "1:1", "//document/root", compA]

    Transform XML content into JSON

    var instance =;
    var r = instance.toJSON();
      "data": {
          "name": "example",
          "element": [{
             "value": 82,
             "flag": true
          }, {
             "value": 16,
             "flag": false

    Add some normalization for a component

    element.cleanupStep(function() {
      if (this.js && this.js.flag && this.js.value) {
        this.js.value = this.js.value + 10

    Transform to verify normalization

    var instance2 =;
    var r2 = instance2.toJSON();
    console.log([0].value); // 92

    Component Fields

    Component fields method is used specify JSON properties and accepts an array. Each element is itself an array with a maximum lenght of 5

    • Index 0: This specifies the JSON key where XML data will be stored. Multiple hieararcy keys such as propa.prob is accepted.
    • Index 1: This specifies the cardinality. 1..1, 0.., 1..*, and 0..* respectively specify required object or value, optional object or value, required array of objects or values, and optional array of objects and values. * can be replaced with a maximum value. Cardinality errors are listed in errors property of results.
    • Index 2: This is an XPath from the current XML element. Any valid XPath expression can be used here provided it finds a node consistent with the type as specified in Index 3.
    • Index 3: This can be either another component in which case this JSON property is an object or an array of objects, or a function in which case JSON property is a value or an array of values. The following functions for value types are provided
      • processor.asString
      • processor.asFloat
      • processor.asBoolean
      • processor.asTimestamp
      • processor.asTimestampResolution
    • Index 4: This specifies names for vendor specific specializations.


    Normalization can be added to each component


    where 'compAStep1' and 'compAStep2' are functions that can remove or modify existing fields or add new fields after the primary parsing step. Normalization steps are executed in order.

    this.js is available inside the normalization functions as the result before normalization. this.js includes all the JSON keys and values defined for the component and normalization is done by changing this.js.

    By default all null and undefined values are removed as the first normalization step. Currently this normalization cannot be removed.

    bbxml.cleanup provides the following common normalizations: renameField, replaceWithObject, extractAllFields, replaceWithField, sn removeField.


    An existing component can be extended to create a new component that includes all the fields and cleanup steps of the existing component

    var compB = compA.define("compB");
      ["addlElement", "0..*", "h:addlElement",  addlElement]

    blue-button-xml generates a JSON object from this definition with 'name', 'element', and 'addlElememt'. Normalization steps will include 'compAStep1', 'compAStep2', and 'compBStep3'.

    Vendor Specific Fields

    Any field in the component can be redefined for a specific key

    var compA = component.define("compA");
        ["name", "0..1", "@name"],
        ["name", "0..1", "@displayName", undefined, 'vendor'],
        ["vendorField", "0..1", "@vendorField", undefined, 'vendor'],
        ["element", "1..1", "h:element", element]

    And if 'vendor' key is passed in the run step from the API, blue-button-xml uses the vendor specific "name" and "vendorField", 'vendor');

    Vendor Specific Normalization

    Normalization steps can be included only for specific vendors

    compA.cleanupStep(compAStep4, ['vendor1', 'vendor2']);

    and compAStep4 will only be used if 'vendor1' or 'vendor2' is passed from run.

    Normalization steps can also be excluded for specific vendors

    compA.cleanupStep(compAStep5, undefined, ['vendor1', 'vendor2']);

    and compAStep5 will not be executed if 'vendor1' or 'vendor2' is passed from run. For no key or other keys compAStep5 will be executed.


    Licensed under Apache 2.0.

    Project was influenced by and used some code from:

    Josh Mandel's ccda-to-json library licensed under Apache 2.0.


    npm i @amida-tech/blue-button-xml

    DownloadsWeekly Downloads






    Unpacked Size

    2.17 MB

    Total Files


    Last publish


    • manhydra