[%settitle Directory of all Versions of FHIR%] [%file newheader%] [%file newnavbar%]

FHIR NPM Packages

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

FHIR NPM 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.

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.

package.json

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

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

A dependency on a core package is required, and this dependency defines the 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 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, if this package represents a single Implementation Guide. This SHALL be present if the package is for an Implementation 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., 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 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 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.

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" }

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

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.)

FHIR Package Caching

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

FHIR NPM Package Registry

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

To load a package onto the package servers:

• Publish the package at a known place on the web
• Register the package in an RSS feed. Use http://hl7.org/fhir/package-feed.xml as a template
• Register the RSS feed in the master list of package feeds at https://github.com/FHIR/ig-registry/blob/master/package-feeds.json. Make the change via a Git PR
• The package registries crawl the registered feeds looking for new packages on a regular basis

[%file newfooter%]