How to create FHIR NPM package

In this tutorial, you will learn how to create a FHIR NPM package and import it into Aidbox.

A FHIR package groups a coherent collection of conformance resources, like StructureDefinitions, SearchParameters, etc., into an easily distributed NPM package.

1. Prepare the package manifest file

To start, we need to describe the package manifest file for our NPM package. A package manifest is a JSON file called package.json.

package.json

{
    // The globally unique identifier of the package.
    // A package name consists of two or more namespaces separated by a dot.
    // Each namespace starts with a lowercase alphabet character
    "name": "my.fhir.package.name",

    // The version of the package (SemVer).
    // SHALL contain only letters, numbers, and the characters ".", "_", and "-"
    "version": "1.0.0",

    // The description of the package.
    "description": "My FHIR NPM Package",

    // The author of the package.
    "author": "Author Name",

    // The list of package dependencies.
    // Should contain at least one FHIR core package.
    "dependencies": {
        "hl7.fhir.r4.core": "4.0.1",
        "hl7.fhir.us.core": "5.0.1"
    }
}

The list of packages that can be specified in dependencies can be found in the Aidbox FHIR IGs Registry:

Aidbox FHIR IGs Registry

2. Write Package Content

A package contains a set of FHIR resources in the JSON format. Let's describe a few resources for the package.

2.1 StructureDefinition resource

Let's describe a profile on the US Core Patient in the file my-patient-profile.json.

my-patient-profile.json

{
    // Type of the FHIR resource.
    "resourceType": "StructureDefinition",
    
    // How the type relates to the baseDefinition.
    "derivation": "constraint",
    
    // Defines the kind of structure that this definition is describing.
    "kind": "resource",
    
    // Type constrained by this structure.
    "type": "Patient",
    
    // The status of this structure definition.
    "status": "active",
    
    // Name for this structure definition (computer friendly).
    "name": "my-patient-profile",
    
    // 	Whether the structure is abstract.
    "abstract": false,
    
    // Canonical identifier for this structure definition, represented as a URI (globally unique).
    "url": "http://custom-url/my-patient-profile",
    
    // Definition that this type is constrained from.
    "baseDefinition": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
    
    "differential": {
        "element": [
            {
                // Element ID
                "id": "Patient.address",
                
                // Path of the element in the hierarchy of elements
                "path": "Patient.address",
                
                // The minimum number of times this element SHALL appear in the instance.
                "min": 1
            }
        ]
    }
}

We have described a profile that inherits from the US Core Patient and adds a required field for address.

2.2 SearchParameter resource

Let's describe a custom search parameter on the Patient resource in the file my-patient-search.json.

my-patient-search.json

{
    // Type of the FHIR resource.
    "resourceType": "SearchParameter",
    
    // ID of the search parameter.
    "id": "Patient-myname",
    
    // Canonical identifier for this search parameter, represented as a URI (globally unique).
    "url": "http://hl7.org/fhir/SearchParameter/Patient-myname",
    
    // Business version of the search parameter.
    "version": "4.0.1", 
    
    // Name for this search parameter (computer friendly).
    "name": "myname",
    
    // Natural language description of the search parameter.
    "description": "text",
    
    // The resource type(s) this search parameter applies to.
    "base": ["Patient"],
    
    // Status of the search parameter.
    "status": "active", 
    
    // Recommended name for parameter in search url.
    "code": "myname",
    
    // 	The type of value that a search parameter may contain, and how the content is interpreted.
    "type": "string",
    
    //FHIRPath expression that extracts the values.
    "expression": "Patient.name"
}

3. Build NPM package

The resulting npm package has the following structure:

mypackage
├── my-patient-profile.json
├── my-patient-search.json
└── package.json

We need to build the artifacts of the npm package into an archive in the TAR (.tar.gz) format.

Linux

tar -czvf mypackage.tar.gz mypackage 

Windows

If Windows supports a native tar command:

tar -cvzf mypackage.tar.gz mypackage

or download and install 7-Zip

1. "C:\Program Files\7-Zip/7z.exe" a -ttar mypackage.tar mypackage

2. "C:\Program Files\7-Zip/7z.exe" a -tgzip mypackage.tar.gz mypackage.tar

Following the guide below, upload the archive to Aidbox.

Local IG Package