(fhir-package-source)=
# The FHIR Package Source

Since version 5 of the SDK (and version R4 of FHIR), the FHIR specification has introduced a new way to manage and distribute FHIR artifacts using
NPM packages. This method of distribution gives third parties and standardization bodies a way to distribute their own FHIR artifacts for
FHIR implementation guides. Implementation guides usually depend on other implementation guides, and NPM's versioning and dependency management
provide a strong, standard way to manage these dependencies.

Conceptually, a FHIR NPM Package is a collection of FHIR Resources (like a directory with a JSON file-per-resource), and the `FhirPackageSource`
can resolve conformance resources (like ValueSets) from one or multiple of these packages.

```{note}
This functionality can be found in a separate NuGet package called `Firely.Fhir.Packages`.
```

There are multiple ways to create a `FhirPackageSource` that queries for artifacts in packages.

```{note}
Since the Package library is not FHIR version aware, you always have to provide a `ModelInspector` to give it type information.
The easiest way to do this is by passing it the `ModelInspector` from the SDK's `ModelInfo` class. This passes the type information of the FHIR version you are currently using to the package source.
If you want to resolve artifacts from multiple versions of FHIR, you have to create a `FhirPackageSource` for each version.
```

If you have a local copy of the packages you want to use, you can just specify the package file paths to create your `FhirPackageSource`:

```csharp
var package1 = "c:/files/packages/package1.tgz";
var package2 = "c:/files/packages/package2.tgz";
FhirPackageSource resolver = new(ModelInfo.ModelInspector, new string[] { package1, package2 });
```

However, if you don't have the packages you want to resolve your artifacts from yet, you can specify a FHIR package server, and the names and versions (using an `@`) of the packages, to install the packages locally and create a `FhirPackageSource` immediately:

```csharp
var package1 = "hl7.fhir.r3.core.xml@3.0.2";
var package2 = "hl7.fhir.r3.expansions@3.0.2";
FhirPackageSource resolver = new(ModelInfo.ModelInspector, "https://packages.simplifier.net", new string[] { package1, package2 });
```

In case you just want to resolve FHIR Core artifacts, you can create a `FhirPackageSource` by calling the `CreateCorePackageSource()` method, which will pull the core FHIR packages of the version specified from a package server:

```csharp
var packageServer = "https://packages.simplifier.net";
var fhirRelease = FhirRelease.STU3;
FhirPackageSource resolver = FhirPackageSource.CreateCorePackageSource(ModelInfo.ModelInspector, fhirRelease, packageServer);
```

Besides the core and expansions packages, `CreateCorePackageSource` also pulls in the FHIR extensions (`hl7.fhir.uv.extensions`) and tools
(`hl7.fhir.uv.tools`) packages, using their latest available versions by default. If you need reproducible builds, you can pin those with the
optional `extensionsVersion` and `toolsVersion` parameters. Note that DSTU2 and R4B have no extensions or tools packages, so passing these
arguments for those releases is not supported.

```{note}
You need an active internet connection to connect to a package server. The `FhirPackageSource` will first check if the specified packages are already installed locally before searching for the packages online. FHIR packages are installed by default in `C:\Users\{user}\.fhir\packages\` (Windows) or `~/.fhir/packages/` (macOS and Linux).
```