Firely .NET SDK Documentation

The Firely .NET SDK is the official support SDK for working with HL7 FHIR on the Microsoft .NET platform. It provides the following core capabilities:

• FHIR Data Models: Class models using POCOs (Plain Old CLR Objects) for working with FHIR resources.
• Parsing & Serialization: XML and JSON parsers and serializers.
• REST Client: A client for interacting with FHIR-compliant servers.
• Metadata Helpers: Tools for working with specification metadata, specifically StructureDefinition and generating differentials.
• Validation: Validation of FHIR instances based on profiles.
• Expression Evaluation: Evaluation of FhirPath expressions.

The SDK is distributed via NuGet packages split by FHIR specification version. You must choose the package that matches the FHIR version your project requires.

Important Compatibility Note: Version 6.0 of the SDK no longer supports netstandard 2.0. The minimum target framework is now netstandard 2.1. If your project requires netstandard 2.0 support, you must use the 5.x version of the SDK.

| Spec version | NuGet Package |
|--------------|---------------|
| R5           | `Hl7.Fhir.R5` |
| R4B          | `Hl7.Fhir.R4B` |
| R4           | `Hl7.Fhir.R4` |
| STU3         | `Hl7.Fhir.STU3` |

The SDK maintains compile compatibility between minor releases, but major version upgrades introduce breaking changes.

Note for SDK 6.x users: The profile validator has been moved to a separate repository. If you are using SDK 6.0, you should use the compatible validator packages found on NuGet under the name Hl7.Fhir.Validation.Legacy.

Every commit on the develop branch results in a public pre-release package available via the GitHub NuGet feed. To use these, you must add the GitHub NuGet source to your local configuration using a GitHub Personal Access Token (PAT) with read:packages scope.

1. Generate a PAT from GitHub with read:packages scope.
2. Run the following command to add the source:

dotnet nuget add source --name github --username <USERNAME> --password <PAT> https://nuget.pkg.github.com/FirelyTeam/index.json

Replace <USERNAME> with your GitHub username and <PAT> with your token.