Firely .NET SDK: FHIR packages, one major upgrade a year

Four FHIR releases, four NuGet packages

HL7 has published several updates of the FHIR specification and each one carries breaking changes, so the first decision with this SDK is not the API but the version. The project lists the four supported releases: STU3, published March 2017 and older but still widely in use, R4 from January 2019, R4B from May 2022, and R5, published on 26 March 2023, which is the latest official release of the specification. All four are described as fully supported by the SDK, and each ships as its own NuGet package: Hl7.Fhir.STU3, Hl7.Fhir.R4, Hl7.Fhir.R4B and Hl7.Fhir.R5, with the matching source branches under release/6.0.0. The guidance for most developers is that including the right NuGet package is enough to get started. The trap is that a library chosen for the wrong FHIR version compiles and then misbehaves against a real server.

What sits behind the POCO models

The SDK covers more than serialization. Class models for the FHIR data model are exposed as POCOs, so a Patient or an Observation is an ordinary object with properties rather than an XML node to walk. On top of that sit XML and JSON parsers and serializers, a REST client for talking to FHIR compliant servers, helper classes for working with the specification metadata, most notably StructureDefinition and the generation of differentials, validation of instances against profiles, and evaluation of FhirPath expressions. The FhirPath piece is what lets you ask a resource a question in the same expression language the specification defines, rather than writing bespoke traversal code per resource type. The validation support depends on profile metadata, which is where the StructureDefinition helpers earn their keep, since a profile is a resource before it is a rule.

Getting the package and the source

The project points at the Firely documentation site for setup details and at the NuGet gallery for the packages, and for most cases the install is just a package reference in a .NET project, so there is no separate install script to run. The one command the documentation gives is for the pre-release feed. Every commit on the develop branch produces a pre-release NuGet package, and those packages are public, but they live behind the GitHub package feed, so the source has to be registered first. A Personal Access token from GitHub with the read:packages scope is needed, and the console command is:

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

After that, a project can restore from the GitHub feed alongside the normal NuGet feed. The documentation frames this as an option for people willing to use pre-release packages.

Upgrades arrive as a major version about once a year

The SDK team says it spends a lot of effort keeping compile compatibility, not binary compatibility, between minor releases, and publishes a new major version with breaking changes about once a year. The major upgrades are tracked with one wiki page each, for 2.x, 3.x, 4.x, 5.x and 6.x, so the cost of an upgrade is a page to read rather than a surprise at compile time. The 6.0 upgrade is the one with the widest reach: it no longer supports netstandard2.0, and the minimum target framework is now netstandard2.1, with the 5.x line kept available for projects that still need the older target. The other structural change worth planning for is that the profile validator was split off into its own repository, firely-validator-api, with compatible validator packages for the 6.0 release published as Hl7.Fhir.Validation.Legacy.

The pipeline fails the build when the public API breaks

Binary compatibility is treated as a build concern rather than a review comment. The build pipeline automatically checks for binary compatibility and fails when it is broken, with occasional exceptions made deliberately. For contributors, the escape hatch is a generated suppression file, and the documented command to produce it locally is:

dotnet pack /p:ApiCompatGenerateSuppressionFile=true

The generated file is expected to be committed so the pipeline passes, which keeps the deliberate exceptions visible in the repository rather than hidden in a local setting. That is a reasonable pattern for a library other people depend on, and it also means a consumer can assume that a minor version bump will not silently change the shape of an assembly. Compile compatibility is explicitly not guaranteed, so source level changes can still require edits in a minor release, and only the major versions carry the documented breaking change list.

Contributions target a single develop branch

Branch management uses Git Flow, and pull requests are submitted against the develop branch, which is also the default branch of the repository. The layout changed with the 5.0 release: the branches for STU3 and newer were combined into one develop branch that holds the code for all FHIR releases from STU3 upward, and the common code was refactored into projects inside that branch, so the separate firely-net-common repository is no longer in use. Contributors who cloned that old repository will find it dead, and the guidance in the README says the consolidation greatly simplifies management and PR creation. At the top level the tree shows a solution file, Hl7.Fhir.slnx, a Directory.Packages.props for central package versions, a global.json pinning the SDK, a nuget.config and a release-notes.md, with the actual projects under src/.

Custom licence, community support and paid support

The licence field on the repository says Other, because GitHub cannot classify it, and the LICENSE file at the root holds the actual terms, so anyone deploying this in a commercial product should read that file rather than assume a standard open source licence. Support comes in three layers. Issues and feature suggestions go through the GitHub issue tracker, which the team says it monitors, and broader questions go to the.NET FHIR Implementers chat on Zulip. Firely also offers optional commercial support for organisations that rely on the SDK in production and want guaranteed response times or implementation help. On the release side, the version history is short and fast: v6.6.0 on 2026-10-02, v6.7.0 on 2026-10-15 and v6.8.0 on 2026-10-19, with the last push to the develop branch on 2026-10-21. Release notes live on the releases page of the repository.

Editorial conclusion

Adopt the Firely .NET SDK when your .NET application has to speak HL7 FHIR and you would otherwise hand-roll parsing, validation and FhirPath, and pick the package that matches the FHIR release your server actually runs, Hl7.Fhir.R5, R4B, R4 or STU3. Do not adopt it if you must keep netstandard2.0, since version 6 dropped it, or if you want the profile validator in the same package, since that code was split into the firely-validator-api repository. Verify first that the major version you pin matches your FHIR release, that the breaking changes page for that major covers your own call sites, and that the licence file matches what your organisation expects from a library that ships under a custom licence.

Frequently asked questions

Official sources

1. FirelyTeam/firely-net-sdk on GitHub
2. Issues
3. README
4. Releases