π₯The FHIR model developed in Project Forge
If you have never heard of FHIR, are unfamiliar with how to implement FHIR, or are confused by any of the terms in this README, then check out the π FHIR 101 Jupyter Notebook.
If you are a new contributor to the Project Forge FHIR model, please review the π NCPI Project Forge Development Guide Notion page. It will walk you through the NCPI software development life cycle for the FHIR model using a practical example.
This repository contains:
- NCPI Project Forge ImplementationGuide - the files and required folder structure needed to build HL7 documentation (known as an ImplementationGuide) for the FHIR data model
- NCPI Project Forge FHIR Model - conformance and example resource files that make up the FHIR model
- Unit Tests - to test the FHIR model
- Git clone this repository
git clone [email protected]:ncpi-fhir/ncpi-model-forge.git
cd ncpi-model-forge
- Set up a Python virtual environment
# Create virtualenv
python3 -m venv venv
# Activate virtualenv
source venv/bin/activate
- Install the necessary requirements
pip install -e .
Test the installation by running the CLI: fhirutil -h
. You should see
something that contains:
Usage: fhirutil [OPTIONS] COMMAND [ARGS]...
A CLI utility for validating FHIR Profiles and Resources
- Install Docker CE: https://docs.docker.com/install/
Docker is needed because the fhirutil CLI executes the model validation inside a Dockerized version of the HL7 IG Publisher.
This section gives a quick overview of how to contribute to the Project Forge FHIR model. Developers are highly encouraged to go through the π NCPI FHIR Software Development Guide. to learn the NCPI software development life cycle, NCPI modeling standards, and development tools.
Follow the steps below to get an idea of how FHIR model development and validation works.
cp docs/data/StructureDefinition-research-study.json site_root/input/resources/profiles
cp docs/data/ResearchStudy-sd-001.json site_root/input/resources/examples
There are two ways to use the fhirutil
CLI to validate the model.
# Method 1 - Uses the Dockerized IG publisher
fhirutil validate ./site_root/ig.ini --publisher_opts='-tx n/a'
# Method 2 - Uses native IG publisher - faster than above method
fhirutil add ./site_root/input/resources
java -jar org.hl7.fhir.publisher.jar -ig site_root/ig.ini -tx n/a
This method is slower since the fhirutil
CLI has to spin up the Docker
container which runs the IG Publisher. The benefit of this is that, you
do not have to install the IG Publisher or its dependencies (Java, Jekyll)
on your machine.
The Docker images for the IG Publisher are built in the NCPI FHIR IG Publisher repository.
Method 2 is faster since it's running the IG Publisher on your local machine, but it means that you must first install the IG Publisher yourself.
-
Install the dependencies: IG Publisher installation instructions.
-
Download the right version of the IG Publisher jar.
The version you use should be identical to what the Dockerized IG Publisher uses. You can use the Fetch IG Publisher script to download the correct version of the IG Publisher jar.
The CLI will log output to the screen and tell you whether
validation succeeded or failed. You can view detailed validation
results at ./site_root/output/qa.html
- Source files for FHIR Model ImplementationGuide (IG):
site_root
- Unit tests:
tests
site_root
βββ ig.ini -> IG configuration file
βββ input
βββ ImplementationGuide-KidsFirst.json -> IG FHIR resource
βββ resources -> FHIR resources that make up the models
βββ examples -> Example resources
βββ extensions -> Extensions
βββ profiles -> StructureDefinition (non-Extension)
βββ search -> SearchParameters
βββ terminology -> CodeSystems, ValueSets
The files ig.ini
and ImplementationGuide-NCPI-Project-Forge.json
contain
configuration information for the FHIR model's ImplementationGuide and
affect which resources are validated and included in the generated site.
Read more about them at https://build.fhir.org/ig/FHIR/ig-guidance/index.html and http://www.hl7.org/fhir/implementationguide.html
Since the NCPI FHIR model is validated using the ncpi-fhir-utility
,
the FHIR resource payloads and filenames are expected to follow certain
standards otherwise validation will fail.
Please see the NCPI FHIR Utility's naming conventions doc for details.
The unit test for the FHIR model is the same as the Validate the Model step in FHIR Model Development section.
The unit test is automatically run by the repository's CI pipeline.