FHIR NPM Package Spec

A FHIR package groups a coherent collection of conformance resources, like StructureDefinitions and valuesets into an easily distributed NPM package. FHIR packages use a subset of the features used by npm packages.

All FHIR Implementation Guides are published as NPM packages, one package for each IG. Additional packages containing subsets of a package information can be created

Package name

Each package has a canonical name (a globally unique identifier). A package name consists of one or more namespaces separated by a dot. Each namespace starts with an lowercase alphabet character followed by a lowercase alphanumeric character or a dash.

The first part of the namespace should identify the author, the authoring organization, or region. The second part of the namespace should identify the functional scope or purpose of the package.

Examples:

 hl7.fhir.core (main build)
 hl7.fhir.us.core
 hl7.au.base
 hl7.nl.medmij
 ihe.pix
 ihe.mhd

Name Management

Names under hl7.fhir. or fhir. are assigned by the FHIR Product Director - contact fhir-director@hl7.org for assistance. Implementers may (of course) use any names they wish in other namespaces, but should be careful to preserve global uniqueness.

For Packages published by HL7, when implementers create a subset of the package, implementers are pre-approved to use the following suffixes:

.terminology .conformance .[type]

e.g. hl7.fhir.us.core.structuredefinition - creating packages with names like this does not require approval. Other combinations - use a name in a different namespace, or ask for approval.

Format

A FHIR package is a tarball (tar in gzip). The package contains

• a subfolder named 'package'
• a package manifest (package/package.json)
• A set of conformance resource files, also in the package subfolder
• It MAY contain additional content, like example resources or documentation:
  • such files SHALL not be in the package subfolder
  • this may include XML schemas in an "xml" subfolder
  • this may include openAPI files in an "openapi" subfolder
  • this may include turtle RDF representations in an rdf folder
  • Package consumers SHALL ignore content in other subfolders that they do not use (and most consumers will only use the resources in /package)

Tarballs SHALL be in the original tarball format (e.g. a 99 character file name length limit).

Note: discussion on this - see [[1]]

Package manifest

A package manifest is a json file called 'package.json'. It conforms to the npm package.json format, but contains only a subset of properties. Other properties are allowed, but should be ignored by a FHIR package consumer.

{
 "name": "hl7.fhir.us.acme",
 "version" : "0.1.0",  
 "canonical" : "http://hl7.org/fhir/us/acme",
 "web" : "http://hl7.org/fhir/us/acme/Draft1",
 "title" : "ACME project IG",
 "description": "Describes how the ACME project uses FHIR for it's primary API",
 "dependencies": {
    "hl7.fhir.core": "3.0.0",
    "hl7.fhir.us.core": "1.1.0",
 },
 "keywords": [
   "us",
   "United States",
   "ACME"
 ],
 "author": "hl7",
 "maintainers": [
   {
     "name": "US Steering Committee",
     "email": "ussc@lists.hl7.com"
   }
 ],
 "license": "CC0-1.0"
}

Package Manifest Properties

- name - mandatory - the globally unique identifier of the package as described above = ImplementationGuide.packageId - version - mandatory - SHOULD use [SemVer](https://semver.org/) - note: Semver SHALL be used for packages published by HL7 or the FHIR Foundation = ImplementationGuide.version - canonical - optional (but required for IGs) = canonical URL for the IG. = ImplementationGuide.url - url - optional (but required for IGs) = where information about the package can be found on the web. = ImplementationGuide.manifest.rendering - title - optional short description for the package (= ImplementationGuide.title) - description - mandatory = ImplementationGuide.description - dependencies - at least one to fhir core (from ImplementationGuide.dependsOn) - keywords - optional - author - mandatory = ImplementationGuide.publisher - maintainers - optional = ImplementationGuide.contacts - license - optional. Follow the [spdx naming convention](https://spdx.org/licenses/) = ImplementationGuide.license (mandatory for packages published by HL7 or the FHIR Foundation)

Other properties (e.g. from base NPM spec) are ignored if present

Dependencies

A fhir package may have dependencies. It SHALL always have at least one dependency to hl7.fhir.core which specifies the FHIR version. Package consumers should be aware of these dependencies and resolve them by downloading and installing each dependency recursively.

Package Content

A package contains a set of FHIR conformance resources in the JSON format for the specified FHIR version. Each conformance resource is saved in a separate .JSON file. All conformance resource files are saved directly in the 'package' directly under the root.

Meta packages

Packages MAY instead of having content only reference other packages. This is called a meta package. It's purpose is to group certain packages and their use case together.

Example: acme.api

Containing only references to acme.api.terminology acme.api.extensions acme.api.profiles