Written and maintained by CASRAI Editorial Board
Last updated
Firely (originating as the HL7 FHIR core team at Furore in Amsterdam alongside co-founders such as Ewout Kramer) develops the reference Microsoft .NET software development kit, enterprise server runtime, and national profiling infrastructure for Fast Healthcare Interoperability Resources (FHIR). In clinical informatics, translational research registries, and national health information exchanges, the Firely ecosystem connects four tightly integrated layers: the open-source Firely .NET SDK for C# (`Hl7.Fhir.*`), the enterprise Firely Server (formerly Vonk), the Forge desktop profile editor, and the Simplifier.net FHIR package registry and Implementation Guide (IG) platform.
1. The Firely .NET SDK for C# (`Hl7.Fhir.*`)
The Firely .NET SDK is the official, open-source C# library for working with HL7 FHIR data models, RESTful APIs, and conformance specifications across FHIR versions STU3, R4, R4B, and R5. Maintained on GitHub (`FirelyTeam/firely-net-sdk`) and distributed via NuGet, the SDK separates release-independent abstractions (`Hl7.Fhir.Base`) from version-specific resource assemblies (such as `Hl7.Fhir.R4` or `Hl7.Fhir.R5`).
| NuGet Package / Namespace | Architectural Role | Core Classes & Interfaces |
|---|---|---|
Hl7.Fhir.Model (within Hl7.Fhir.R4 / R5) |
Strongly typed Plain Old CLR Object (POCO) representations of every FHIR resource, complex data type, primitive type, and coded enumeration | Patient, Observation, Bundle, CodeableConcept, Identifier, ResourceReference, FhirDateTime |
Hl7.Fhir.Serialization |
Bidirectional parsing and serialization between C# POCOs (or abstract ITypedElement trees) and FHIR JSON or XML wire payloads |
FhirJsonDeserializer / FhirJsonSerializer (including System.Text.Json integration), FhirXmlParser, FhirXmlSerializer |
Hl7.Fhir.Rest |
HTTP REST client implementing the FHIR RESTful specification, search parameters, conditional operations, and history bundles | FhirClient, SearchParams, Bundle pagination (ContinueAsync), TransactionBuilder |
Hl7.FhirPath |
Evaluation engine for the HL7 FHIRPath navigation and extraction language used in search parameter extraction and invariants | FhirPathCompiler, ITypedElement.Select(), Predicate() |
Hl7.Fhir.Specification & Firely.Fhir.Validation |
Snapshot generation, StructureDefinition resolution from FHIR packages, and instance validation against profiles and terminology |
Validator, ZipSource, FhirPackageSource, SnapshotGenerator, LocalTerminologyService |
POCO Model vs. Version-Independent `ITypedElement`
Developers writing clinical data pipelines in C# can manipulate FHIR resources using two complementary programming models in the Firely SDK:
- Strongly Typed POCOs (`Hl7.Fhir.Model`): Ideal when application logic targets a known FHIR release (for example, FHIR R4 for US Core EHR integrations). Cardinality-many elements (`0..*` or `1..*`) map to `List<T>`, while polymorphic choice elements (`value[x]` on `Observation`, such as `valueQuantity` vs. `valueCodeableConcept`) expose a base `DataType` property (`obs.Value = new Quantity(5.4m, “mmol/L”, “http://unitsofmeasure.org”)`).
- Abstract Element Navigation (`ITypedElement` / `ISourceNode`): Enables release-agnostic engines, FHIRPath evaluators, and structural validators to traverse JSON or XML payloads via metadata provided by an `IStructureDefinitionSummaryProvider` without compiling against a single FHIR version’s C# classes.
2. Firely Server (Formerly Vonk) Architecture and Plugins
Firely Server (originally released as Vonk) is a commercial, cross-platform FHIR server built on ASP.NET Core and the Firely .NET SDK. Unlike simple persistence wrappers, Firely Server implements a modular middleware pipeline where every FHIR interaction (`read`, `vread`, `update`, `patch`, `delete`, `search-type`, `transaction`, `$validate`, `$export`) traverses configurable plugins.
- Multi-Version and Multi-Storage Abstraction: A single Firely Server deployment can expose distinct tenant or version endpoints (`/r4`, `/stu3`, `/r5`) backed by pluggable storage providers including Microsoft SQL Server, PostgreSQL, MongoDB, and Azure Cosmos DB, or by a custom Facade (`ISearchRepository` and `IChangeRepository`) mapped over a legacy relational clinical database or electronic health record (EHR) schema.
- Profile Conformance and Terminology Validation: Administrators load pre-compiled `StructureDefinition`, `ValueSet`, `CodeSystem`, and `SearchParameter` artifacts directly from standard FHIR NPM packages (`.tgz`). Incoming write requests (`POST` / `PUT`) or explicit `$validate` calls are checked against target profiles (`meta.profile`), enforcing slicing rules, fixed values, must-support constraints, and FHIRPath invariants (`ele-1`, `dom-6`).
- SMART on FHIR and Bulk Data (`$export`): Through Firely Auth, the server enforces OAuth 2.0 / OpenID Connect and SMART App Launch (v1 and v2) scopes (`patient/*.rs`, `user/*.cruds`, `system/*.read`), alongside asynchronous FHIR Bulk Data Access (`$export`) outputting NDJSON files for population health and clinical research cohorts.
3. Forge and Simplifier.net: Authoring FHIR Implementation Guides
National health agencies, specialty societies, and clinical trial sponsors must constrain the base 80% FHIR specification to match local regulatory requirements. Firely provides the two primary authoring tools used across the HL7 community:
- Forge (Desktop FHIR Profile Editor): A Windows/desktop graphical modeling application that generates valid `StructureDefinition` XML/JSON resources without manual editing. Informaticians use Forge to restrict element cardinalities (such as narrowing `0..*` to `1..1` or prohibiting an element with `0..0`), bind coded fields (`Coding` / `CodeableConcept`) to SNOMED CT or LOINC value sets at `required`, `extensible`, or `preferred` binding strengths, define complex discriminator-based slicing (for example, slicing `Observation.component` into systolic and diastolic blood pressure components), and author custom `Extension` definitions.
- Simplifier.net (FHIR Registry and IG Publisher): A cloud collaboration hub and canonical registry where teams manage FHIR artifacts, integrate with GitHub repositories, validate example instances, publish versioned HL7 FHIR NPM packages (`package.json`), and render web-based Implementation Guides using Firely’s template and FQL (FHIR Query Language) table generators.
4. Frequently Asked Questions
What is the Firely .NET SDK for HL7 FHIR?
The Firely .NET SDK (`Hl7.Fhir.*` on NuGet) is the official open-source C# library for HL7 FHIR. It provides strongly typed POCO resource models (`Hl7.Fhir.Model`), JSON/XML parsers and serializers (`Hl7.Fhir.Serialization`), a full FHIR REST client (`FhirClient`), a FHIRPath expression engine (`Hl7.FhirPath`), and a profile validation engine (`Firely.Fhir.Validation`) across FHIR STU3, R4, R4B, and R5.
How does Firely Server handle FHIR profiling and terminology validation?
Firely Server ingests standard FHIR NPM packages containing `StructureDefinition`, `SearchParameter`, `ValueSet`, and `CodeSystem` resources. When a client submits a resource or invokes the `$validate` operation, Firely Server evaluates structural cardinalities, data types, extensions, slicing discriminators, FHIRPath invariants, and terminology bindings—either using its built-in local terminology service or delegating complex subsumption queries (`$validate-code`, `$expand`) to an external FHIR terminology server.
How do Forge and Simplifier.net support FHIR Implementation Guide authoring?
Forge provides a visual interface for authoring `StructureDefinition` profiles, extensions, and slicing rules against a base FHIR version or parent profile (such as US Core). Those artifacts are synchronized to Simplifier.net, which validates conformance, renders interactive tree views and FQL documentation tables, and publishes immutable FHIR NPM packages that downstream developers consume in the Firely .NET SDK or Firely Server.
