On this page:

5.21Packages 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 Gudes, and the use of Packages as a distribution mechanism.

5.21.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:

  • StructureDefinition resources describing mandatory fields in various FHIR resources. These fields are not mandatory in the base FHIR specification, but are mandatory for applications trying to support the US Core IG.

  • StructureDefinition resources describing extensions that have been defined for specific data requirements in the US.

  • ValueSet and CodeSystem resources describing terminology requirements that are specific to US requirements.

  • SearchParameter resources describing a minimum set of supportable FHIR search parameters

5.21.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 resources described 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.

5.21.3Smile CDR Package Registry

 

Packages Overview

The Smile CDR FHIR Storage Module (RDBMS) contains a built-in package registry.

This package registry 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.

5.21.4Package Pre-Seed Installation

 

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

To configure pre-seeding of resources, one or more PackageInstallationSpec documented should be created, and linked to from the Package Pre-Seed Installation Spec Files property of the FHIR Storage (RDBMS) module. Multiple spec files may be created (one per package to install) and linkes to from the same configuration property.

For example, the following Package Spec file will automatically install the US Core implementation guide.

{
	"name" : "hl7.fhir.us.core",
	"version" : "3.1.0",
	"installMode" : "STORE_ONLY",
	"fetchDependencies" : true
}

If this file is placed into the Smile CDR installation under classes/config_seeding/package-spec.json, the Package Pre-Seed Installation Spec Files property can be set to classpath:/config_seeding/package-spec.json in order to have ths package seeded on startup.

Pre-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 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: Resources loaded using method must include either a url or identifier element.

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
}

5.21.5Creating 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.