Release 5 R6 Ballot (1st Full Ballot)

This page is part of the FHIR Specification (v5.0.0: R5 - STU v6.0.0-ballot4: Release 6 Ballot (1st Full Ballot) (see Ballot Notes ). This is the The current published version in it's permanent home (it will always be available at this URL). is 5.0.0 . For a full list of available versions, see the Directory of published versions for published versions icon

2.1.10 FHIR NPM Packages

Maturity Level : n/a
Responsible Owner: FHIR Infrastructure icon Work Group Standards Status : Informative Normative

FHIR Specifications are published in HTML format for human consumption, and as NPM packages for machine consumption.

Some important packages for FHIR Implementers:

  • hl7.fhir.rX.core : The package that contains the definitions found in the base specification
  • hl7.fhir.rX.examples : The package that contains the example resources found in the base specification
  • hl7.terminology : The package that contains all the code systems and value sets maintained by HL7 for all standards it publishes

2.1.10.1 FHIR NPM Packages Package Structure

Each FHIR package is a tarball (tar in gzip) that contains a package folder that contains:

  • a package.json file that describes the package
  • 0 or more FHIR resources in JSON format
  • 0 or more FHIR resources in an examples folder below the package folder that contains examples in JSON format for the profiles included
  • an .index.json file in both folders that contains key information from the JSON resources for quick access

Packages may contain additional folders below the package folder and files but their use is not defined by this specification.

Note that this specification is published as a package, and each Implementation Guide is published as a package, but this is not the only use for package, and other packages exist.

2.1.10.2 Package composition

In theory, packages can contain an unlimited number of artifacts with unlimited size. However, in practice, real-world tools will struggle or even fail if packages are too large. Authors should consider this when deciding how they package. Ways to help manage this issue include:

  • packaging 'extra' collateral such as testing support and examples in separate packages from the definitional content
  • ensuring package artifacts are expressed in their 'minimal' form whenever possible (e.g. not including expansions of value sets)
  • when it's possible to control size (e.g. examples), try to keep sizes smaller. For example, if there's a need to have an example of a video, make sure it's low resolution and short.
  • consider publishing content in subsets if the overall number of files would be significant. (This will also often speed the publication process.)

NPM FHIR Packages SHOULD contain an ImplementationGuide resource with the url: {package-canonical}/ImplementationGuide/{packageId} and the version to match the package version.

It is reasonable for tooling to resolve a canonical reference to an implementation guide resource as the NPM FHIR Package matching that definition (e.g., per the dependsOn element of the implementation guide.

2.1.10.3 package.json

The format of the package.json file is defined by the NPM Package Specification icon . This specification makes some rules about use of the properties as defined in the NPM specification, and defines some additional FHIR specific properties.

name required Each package SHALL have globally unique identifier for the package in the NPM System. A package name consists of two or more namespaces separated by a dot. Each namespace starts with a lowercase alphabet character followed by zero-or-more lowercase alphanumeric characters or dashes. The first part of the namespace should identify the publisher for the package.
Note: HL7 manages all the packages that start with hl7.
version required All packages SHALL have a version that conforms to Semantic Versioning. See FHIR Versioning for how semantic versioning works with standards.
dependencies required Any dependencies SHALL be listed her here - that is, any other package that contains resources referred to by the resources in the package.

Packages SHOULD be referred to by the whole package version number and not use wildcards, except for the patch version in a semver SemVer version reference. This The x here in the following example means that it should a package resolver should accept the package with the highest found patch number: 
"dependencies": {
  "hl7.fhir.r5.core": "5.0.x"

  "hl7.fhir.r6.core": "6.0.x"

}


A dependency on a core package is required, and this dependency defines the basic FHIR version used to resolve the contents of this dependency tree. If multiple core package dependencies are listed, the first instance is the version used.

Development packages may use a local path for the package version (see Local Paths icon in the NPM documentation)
author required Each package SHALL contain the name of the author - an individual or organization who created and/or published the pacakge
description required Each package SHALL have a human language description of the contents of the package
canonical conditionally required The canonical URL for the Implementation guide represented by the package. package, if this package represents a single Implementation Guide. This SHALL be present if the package is for an Implementation Guide, but not Guide and is optional for other packages.
url recommended The URL at which the specification that the package represents may be found
type recommended The type of resources that the package contains. The type may be one of the following values:
  • Conformance - a set of Conformance Resources in the base package folder (/package)
  • IG - a FHIR implementation guide package (has an ImplementationGuide resource in /package, along with conformance resources, and also contains example resources in /package/example)
  • Core - contains the conformance related resources for the main FHIR specification (effectively, this is a special type of "conformance" that marks it as the core specification, which could also be inferred from its name such as hl7.fhir.r4.core, but other branches / ballots etc. may vary, so this is simpler than inferring from the name)
  • Examples - contains the example resources found in the main FHIR specification in /package
  • Group - a package that only includes (e.g. (e.g., depends on) other packages (won't contain FHIR resources directly). The versions listed in this package must include all the versions found in the included packages. Note that this is used for the set of packages that represent a full core specification
  • Tool - A a package that contains tool specific files to support specific tools (won't contain FHIR resources or specify a FHIR version)
  • IG-Template - an IG template for use by IG publishing tools (won't contain FHIR resources or specify a version)
  • Test - The package contains resources intended to be used for the testing of implementations.
This value is provided to help users find and choose the correct package; it has no meaning to tools using the packages.
jurisdiction optional A URL with the syntax {system}#{code} , from the Jurisdiction icon ValueSet. This value is provided to help users find the right package in the package registry
languages optional An array of strings, where each value is an IETF language code from AllLanguages ValueSet , and indicates that the package contains content suitable for the specified language
fhirVersions optional An array of the FHIR Versions used by the package. Most packages only use one version. In some older packages, this was named fhir-version-list. The value of this property can be determined by inspecting the package

Note: bolded items are introduced by this specification, while other items are those defined by NPM itself.

2.1.10.3 2.1.10.4 Example Package File

This is the package.json file to the US Core Implementation Guide. 

  {
    "name": "hl7.fhir.us.core",
    "version": "5.0.1",
    "type": "IG",
    "date": "20220622194452",
    "license": "CC0-1.0",
    "canonical": "http://hl7.org/fhir/us/core",
    "url": "http://hl7.org/fhir/us/core/STU5.0.1",
    "title": "US Core Implementation Guide",
    "description": "The US Core Implementation Guide...",
    "dependencies": {
      "hl7.fhir.r4.core": "4.0.1",
      "hl7.terminology.r4": "3.1.0",
      "hl7.fhir.uv.bulkdata": "2.0.0",
      "hl7.fhir.uv.smart-app-launch": "2.0.0",
      "us.nlm.vsac": "0.7.0",
      "hl7.fhir.uv.sdc": "3.0.0"
    },
    "author": "HL7 International - Cross-Group Projects",
    "jurisdiction": "urn:iso:std:iso:3166#US"
  }

2.1.10.4 2.1.10.5 .index.json

This optional file contains information from the resources in the package folder. The intention of this file is to save tools from loading every resource in the package; they can read the .index.json file and know what resources are in the package and load only the ones they need.

Note that there is no independent information in the .index.json file; all the information is derived from the resources, and tools can rebuild it at any time (or built it and add it if it is not present). 

{
  "index-version": 2,
  "files": [
  ]
}

The index version is a fixed value that may change if this file format is changed. Tools should rebuild the file if they do not recognize the version. The files array contains an object for each resource in the package with the following properties:

  • filename - the filename in the package directory that is being described
  • resourceType
  • id
  • url
  • version
  • kind
  • type
  • supplements
  • content

These properties are populated if there is a string property with the same name in the resource identified by the filename, irrespective of resource type.

2.1.10.5 2.1.10.6 FHIR Package Composition

In theory, packages can contain an unlimited number of artifacts with unlimited size. However, in practice, real-world tools will struggle or even fail if packages are too large. Authors should consider this when deciding how they create packages. Ways to help manage this issue include:

  • Packaging 'extra' collateral such as testing support and examples in separate packages from the definitional content
  • Ensuring package artifacts are expressed in their 'minimal' form whenever possible (e.g. not including expansions of value sets)
  • When it's possible to control size (e.g. examples), try to keep sizes smaller. For example, if there's a need to have an example of a video, make sure it's low resolution and short.
  • Consider publishing content in subsets if the overall number of files would be significant. (This will also often speed the publication process.)

2.1.10.7 FHIR NPM Package Registry Caching

For user convenience, tools may choose to use a common local cache icon .

2.1.10.6

2.1.10.8 FHIR NPM Package Registry

The FHIR packages are all hosted on the registry http://packages.fhir.org icon . Users can search for packages icon and download them manually, but the main users of the registry are tools that access the registry using the package API icon . A secondary package registry may be found at http://packages2.fhir.org icon .

To load a package onto the package servers: