standardhealth/shr-json-export

ES6 library for exporting SHR models to JSON

Deprecated

The shr-json-export repo has been deprecated and is no longer used or maintained.

SHR JSON Export

The Standard Health Record (SHR) initiative is working to create a single, high-quality health record for every individual in the United States. For more information, see standardhealthrecord.org.

This GitHub repository contains an ES6 library for exporting SHR data elements represented using SHR models to a simple JSON format for easy consumption by RESTful applications.

The SHR text definitions and grammar files can be found in the shr_spec repo. As the SHR text format (and content files) are still evolving, so is this library.

Setting Up the Environment

This project has been developed and tested with Node.js 6.6, although other versions may work. After installing Node.js, change to the project directory and npm install the dependencies:

$ npm install

Running the Tests

This project contains unit tests for testing the SHR text importer, JSON schema exporter, and FHIR StructureDefinition exporter. To run the tests, execute the following command:

$ npm test

During development, it is often helpful to run tests in watch mode. This launches a process that watches the filesystem for changes to the javascript files and will automatically re-run the tests whenever it detects changes. To run the tests in watch mode, execute the following command:

$ npm run test:watch

Linting the Code

To encourage quality and consistency within the code base, all code should pass eslint without any warnings. Many text editors can be configured to automatically flag eslint violations. We also provide an npm script for running eslint on the project. To run eslint, execute the following command:

$ npm run lint

Running

To enable executing, go to the shr-cli project directory:

$ npm install

To run (while still in shr-cli project directory):

$ node cli.js ../shr-spec/spec ./out

the 2nd argument (../shr-spec/spec) represents the location of the shr spec txt files

Changing shr-json-export project

To make changing to the shr-json-export project and test them, you will need to link your local shr-json-export project directory as the current npm module. Here are the steps to do that:

$ cd ../shr-json-export/

$ npm link

$ cd ../shr-cli/

$ npm link shr-json-export

Now to run the current json export and test changes made (from the shr-cli project directory):

$ node cli.js ../shr_spec/spec/ ./out

When done making changes, restore use of the published version of shr-json-export:

$ cd ../shr-cli

$ npm unlink shr-json-export

$ npm install

License

Copyright 2016 The MITRE Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

shr-json-export's Issues

Structure of `isA` in `TypeConstraint`

Currently, the isA property of a TypeConstraint has _name and _namespace properties, as shown below:

{
    "min": 0,
    "max": 1,
    "constraints": [
    {
        "type": "TypeConstraint",
        "isA": {
            "_namespace": "shr.lab",
            "_name": "TestMethod"
        },
        "onValue": false,
        "path": ""
    }
    ],
    "type": "IdentifiableValue",
    "label": "shr.observation:Method",
    "identifier": {
        "label": "Method",
        "type": "Identifier",
        "namespace": "shr.observation"
    }
}

These are intended to be private properties (hence the _ prefix). Since isA is an Identifier in the models, I think this should be represented in the JSON the same way identifiers are represented elsewhere. So, the example above probably should be:

{
    "min": 0,
    "max": 1,
    "constraints": [
    {
        "type": "TypeConstraint",
        "isA": {
            "type": "Identifier",
            "label": "TestMethod",
            "namespace": "shr.lab"
        },
        "onValue": false,
        "path": ""
    }
    ],
    "type": "IdentifiableValue",
    "label": "shr.observation:Method",
    "identifier": {
        "label": "Method",
        "type": "Identifier",
        "namespace": "shr.observation"
    }
}

@gregquinn2001, @Dtphelan1 : Any objections?

No method of expressing constraint paths on inherited fields for Incomplete Values

Consider:

EntryElement:	Immunization
Concept:		MTH#C0020971
Description:	"A statement relating to a vaccination that was or was not administered to the subject."
Based on:		Action
1..1 			Vaccine // in the case of immunication not given, the vaccine will have a SpecificType, but not a lot or manufacturer. 
1..1			NonOccurrenceModifier
				NonOccurrenceModifier.Reason from http://hl7.org/fhir/ValueSet/no-immunization-reason
0..1			BodySite   // from core
0..1			RouteIntoBody  // from medication
0..1			AmountOfMedication  // from medication
0..1			TBD "DoseSequenceNumber"

In the inherited field constraint: NonOccurrenceModifier.Reason from http://hl7.org/fhir/ValueSet/no-immunization-reason, the NonOccurrenceModifier path doesn't get translated to to the json, making a back and forth conversion impossible.

For Type Constraints on value, the onValue boolean is not exported.

Naming Conventions: Label as used in Data Elements and CodeSystems

Our conceptualization of label for CodeSystems seem sufficiently divorced from the use of label in DataElement . In the DataElement case, label seems synonymous with something like an shr_identifier, the thing you look up in the shr to get to that value. In the Codesystem Value Case, label seems synonymous with the display value, but separate from the code, which appears to me to be the closest thing to an shr_identifier. Let me know if this disambiguation is clear at all and what we'd want to do, or if this is too hazy an explanation. For context:

DataElement Value:
{
"type": "DataElement",
"label": "ActiveFlag",
"isEntry": false,
"concepts": [],
"description": "If the ActiveFlag is false, it indicates the record is no longer to be used and should generally be hidden for the user in the UI.",
"grammarVersion": { ... },
"value": { ... }
},
"children": []
}

CodeSystem Value:
{
"label": "Preferred language (http://standardhealthrecord.org/fhir/CodeSystem/shr-actor-LanguageQualifierVS:preferred_spoken)",
"type": "Concept",
"system": "http://standardhealthrecord.org/fhir/CodeSystem/shr-actor-LanguageQualifierVS",
"code": "preferred_spoken",
"display": "Preferred language",
"url": "http://standardhealthrecord.org/fhir/CodeSystem/shr-actor-LanguageQualifierVS"
},