Blue Button
Blue Button JavaScript library
This library is part of blue-button family of parsers and provides the following functionality:
- Parse XML documents
- Sense type of data (CCDA, CMS, C32, etc.)
- Parse CCDA into JSON representation
- Parse CCDA elements (sections) into JSON representation
- Parse C32 into JSON representation
- Parse C32 elements (sections) into JSON representation
- Parse CMS into JSON representation
- Generate JSON object based on data model
Actual implementation of sensing type of data and parsing CCDA and C32 reside in this repository. Implementation of other functionalities reside in
- blue-button-xml provides XML parsing infrastructure
- blue-button-cms provides CMS parsing
- blue-button-model provides data model schema and validation
In addition CCDA generation from blue-button, JSON objects is available in blue-button-generate.
Quick up and running guide
Prerequisites
- Node.js (v14.19+) and NPM
- Grunt.js
# Install dependencies
npm i
# Install grunt
npm i -g grunt
# Test
grunt
Usage
Require blue-button module
var bb = require("@amida-tech/blue-button")
Load some health data content. Currently CCDA (CCD), C32 and CMS are supported
var data = "some CCDA.xml, C32.xml or CMS.txt here...";
Generate JSON representation of the health data
var doc = bb.parse(data);
parse
method senses the type of the health data, parses and converts it into JSON. All types of health data is converted into a common model. Validate doc
according to the common model schema
var valid = bb.validator.validateDocumentModel(doc);
if (! valid) {
throw new Error('failed');
}
Do changes to doc
in your application
doc.data.demographics.phone.number = "(555)555-5555";
Create a CCDA (CCD) document that includes your changes
var bbg = require("@amida-tech/blue-button-generate")
var modifiedDataCCD = bbg.generateCCD(doc);
Data Model
Blue Button library converts all types of health data (CCDA, C32, CMS) into a common model. Data model schema and validation implementation can be found in blue-button-model.
API
XML Utilities
Blue Button library provides basic XML parsing and XPath functionality via libxmljs (node.js) and DomParser (browsers). All XML related API methods are inherited from blue-button-xml and available from xml
object
var xml = bb.xml;
parse(src)
Parses XML content string into an XML Object which can be used in other API methods. Details of the actual XML object can be found in the documentation of underlying libraries libxmljs (node.js) and DomParser (browsers).
Arguments
-
src
- XML content in string. - returns - XML Object.
xpath(doc, p, ns)
Finds the XML nodes that are specified by p
.
Arguments
-
doc
- XML document or any parent XML node inside the document that is found by a previousxpath
call. -
p
- A valid XPath string. -
ns
- XML namespace specifications. By defaulth: urn:hl7-org:v3"
andxsi: http://www.w3.org/2001/XMLSchema-instance
are used as they are the namespaces used in CCDA. - returns - XML object node.
Sensing
senseString(data)
Senses the type of the string content.
Arguments
-
data
- String content for which the type is to be found. - returns - A result object. In the case of an error either
null
is returned or an error is thrown. Result object has the following properties-
type
- A string that identifies the type of the content. Currently can beccda
,c32
,cda
,xml
,cms
,va
,format-x
,json
,blue-button.js
,va
,pdf
orunknown
. -
xml
- In the case of XML content (ccda
,c32
,cda
,xml
) this is set to the parsed XML object. -
json
- In the case of JSON content (blue-button.js
,json
) this is set to the passed JSON object.
-
senseXml(data)
Senses the type of an XML object.
Arguments
-
data
- XML object for which the type is to be found. - returns - A result object. In the case of an error either
null
is returned or an error is thrown. Result object has the following properties-
type
- A string that identifies the type of the content. Currently can beccda
,c32
,cda
,xml
,unknown
.
-
JSON Generation
parse(data, options)
This is the primary method in Blue Button library that both senses the type of the input content and generates JSON out of it. Underneath it calls to other sensing and JSON generation methods.
Arguments
-
data
- Any string data content. Currently CCDA (CCD), C32 and CMS are supported. - options - The following properties are supported
-
component
- Specifies a component of CCDA or C32 document; not used for CMS documents.data
should only contain content for the component. The following CCDA (CCD) sections are supported:ccda_demographics
,ccda_vitals
,ccda_medications
,ccda_problems
,ccda_immunizations
,ccda_results
,ccda_allergies
,ccda_encounters
,ccda_procedures
,ccda_social_history
,ccda_plan_of_care
,ccda_payers
. The following C32 sections are supported:c32_demographics
,c32_vitals
,c32_medications
,c32_problems
,c32_immunizations
,c32_results
,c32_allergies
,c32_encounters
,c32_procedures
. In addition individual entries in each section can also be specified (ccda_vitals_entry
,ccda_medications_entry
, ...,c32_vitals_entry
, ...).
-
- returns - JSON representation of the data.
parseString(data, options)
This is similar to parse
but it assumes data
to be valid XML.
parseXml(data, options)
This is similar to parse
but it assumes data
to be an XML object.
parseText(data)
This is similar to parse
but it assumes data
to be Text (ASCII) and options
is not used. Currently only Text content in CMS format is supported.
Examples
See scripts in /example or /test directories that use the above API methods for CCDA, C32 and CMS examples.
Goals
- Full support of CCDA, C32 and CMS
- Ability to extend to support other data formats
- Solid, well-documented JSON-based data model for patient health data
- Modularity - easy to extend (both parser and data model)
- Node.js support
- Browser support
- Speed of parsing
- Well tested on entire corpora of CCDA samples from https://github.com/jmandel/sample_ccdas
Future Roadmap
- Merge back into bluebutton.js repo
- Refactoring into smaller components (sub-modules)
Contributing
Contributors are welcome. See issues https://github.com/amida-tech/blue-button/issues
Release Notes
See release notes here
License
Licensed under Apache 2.0
Project was influenced by and used some code from:
bluebutton.js library licensed under MIT
Josh Mandel's ccda-to-json library licensed under [Apache 2.0] (https://github.com/jmandel/ccda-to-json/blob/master/LICENSE)