On this page:

6.9Packages and Implementation Guides

 

Around the time FHIR R4 was released, the FHIR community standardized on the NPM (Node Package Manager) format as a standard mechanism for distributing shared FHIR artifacts. The most common use case for these packages is in distributing Implementation Guides. This page describes Smile CDR support for Implementation Guides, and the use of Packages as a distribution mechanism.

6.9.1Background: Implementation Guides

 

An Implementation Guide (often called an "IG") is a profile on the FHIR specification that constrains it down for a specific set of use cases. Implementation guides can be thought of as a "mini FHIR spec" that is defined by a particular geographic region, specialty organization, project, etc.

For example, the US Core Implementation Guide describes a set of profiles on the FHIR specification in order to ensure a common data models for interoperable applications in the United States. Among other things, the US Core IG includes resources such as StructureDefinion, ValueSet, SearchParameter, etc. See Conformance Data to learn more about what these are used for.

6.9.2Background: Packages

 

When an Implementation Guide is published, it takes two main forms. The first is a collection of web pages that can be browsed to learn about the specification (e.g. the US Core IG described above). The second is a collection of machine readable artifacts (i.e. the FHIR Conformance Data resources mentioned above) that can be used to validate content to ensure that it conforms with the given Implementation Guide constraints.

These resources are assembled into a Package, using the format defined by the Node Package Manager (NPM) specification.

6.9.3Ingesting Packages into Smile CDR

 

Packages Overview

The Smile CDR FHIR Storage Module (RDBMS) contains a set of database tables dedicated to native storage of package contents. This allows the Conformance Data contained within a package to be stored and made available to the validator.

This FHIR Storage (RDBMS) module can ingest packages from both local files, as well as the Official FHIR Package Server (packages.fhir.org). Packages are stored in a dedicated set of tables in the FHIR Storage (RDBMS) module database schema. Package binaries (i.e. the actual contents of the package) are stored as Binary resources, meaning that Externalized Binary Storage will be used for storing large binary payloads if it is enabled.

Adding packages to the package registry has several purposes:

  • If the package contains conformance resources for the same version of FHIR as the FHIR Storage module, these resources become available to the FHIR validator. Note that the package registry is able to store and serve packages for other versions of FHIR, but the individual resources will not be available to the validator.

  • Package contents can be automatically extracted and saved as individual resources in the repository.

  • Packages can be served via the Package Registry Endpoint.

6.9.4Package Pre-Seed Installation

 

When Smile CDR starts, the FHIR Storage module can be configured to automatically import packages into the local registry. This makes the conformance artifacts in these packages available to the validator. It can also optionally import resources from the package directly into FHIR Storage, so that these resources become available for FHIR searches, reads, etc.

See Pre-Seeding Packages and FHIR Resources for information on how to do this.

6.9.5Pre-Seeding Resources into the Repository

 

Packages can also be used to seed a set of data into the FHIR repository itself (i.e. not simply making these resources available to the validator, but actually storing them in the database so that they are standard FHIR resources that can be searched, read, etc.). This is called Store And Install mode. This functionality is not limited to validation/conformance resources: It can also be used to seed a new environment with a common set of Organization resources for a project, to seed SearchParameters to every environment, etc.

Note that using Store and Install mode is not required in order to perform resource validation. Regardless of the mode used, when a package is ingested the contents are also stored outside of FHIR resource storage and it is that copy that is used to power validation. This mode is only needed if you want to store the FHIR resources in the repository and use a FHIR REST API to query them.

Resources loaded using method must include either a url or identifier element, which is used to ensure that the package loader doesn't create duplicate resources.

A sample spec file is shown below:

{
  "name" : "com.example.my-resources",
  "version" : "1.0",
  "packageUrl" : "classpath:/my-resources.tgz",
  "installMode" : "STORE_AND_INSTALL",
  "installResourceTypes" : [ "Organization", "Medication", "PlanDefinition", "SearchParameter" ],
  "fetchDependencies" : false
}

6.9.6Package Registry Endpoint module

 

A module called the Package Registry Endpoint module provides an NPM compatible REST API that can be used to:

  • Load new packages into package storage

  • Query for and access packages stored in package storage

This module is not required in order to use packages. If you simply want to load packages and use them for validation, you do not need a package registry. However, if you want to create a local enterprise server to act as the authoritative source for packages, or wish to allow local users to browse a query endpoint, this can be a useful option.

Packages Registry

6.9.7Creating Packages

 

Packages are available from the FHIR Package Registry at packages.fhir.org. You can also create your own using the smileutil Create Package Command.