R6 Ballot (2nd Draft)

Publish-box (todo)

2.1.10 FHIR NPM Packages

FHIR Infrastructure icon Work GroupMaturity Level: n/aStandards Status: Informative

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

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.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 - 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 version reference. This x here 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"
}
A dependency on a core package is required, and this dependency defines the basic

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 required The canonical URL for the Implementation guide represented by the package. This SHALL be present if the package is for an Implementation Guide, but not 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)
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
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 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 .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 FHIR NPM Package Registry

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

2.1.10.6 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: