Northpine Healthcare data engineering — FHIR, X12, and .NET · by Rex Fan

C# & FHIR · Uncategorized

.NET & C# for FHIR Interoperability 3 — Resource Validator

by Rex Fan

0 Abstract

In the era of FHIR-driven healthcare interoperability, data accuracy and standard compliance are non-negotiable. Regulators, including the U.S. Office of the National Coordinator for Health Information Technology (ONC) mandate strict data integrity requirements via rules like (g)(10) and US Core Implementation Guides (IGs) — non-compliant or malformed FHIR data not only breaks cross-system data exchange but also leads to regulatory penalties and compromised clinical decision-making.

C#/.NET has become a staple in U.S. healthcare IT systems for its robustness, security, and seamless integration with enterprise-grade infrastructure: according to a 2025 healthcare IT market analysis by Gartner, .NET/C# powers over 45% of EHR/EMR systems and FHIR integration layers in the U.S. , making it the most adopted framework for healthcare interoperability development alongside Java. Its strong type system, built-in security features, and mature ecosystem (e.g., Hl7.Fhir.Net SDK) make it the ideal choice for building reliable, production-grade FHIR solutions.

This article, the third in the FHIR interoperability series, dives into the Resource Validator module — a critical quality barrier for FHIR data built with the Hl7.Fhir.Validation library. We’ll cover the core value of FHIR resource validation, real-world development pain points, and a step-by-step C# implementation to enforce both FHIR schema rules and custom clinical business logic for resources like Patient.

1. Why FHIR Resource Validation is Non-Negotiable

1. Core Value of the Resource Validator Module

FHIR resources are the building blocks of standardized medical data, but raw data from heterogeneous systems (e.g., legacy EHRs, CSV exports) is prone to format errors and logical inconsistencies. The Resource Validator module acts as a pre-storage/pre-exchange quality check for FHIR resources, with two irreplaceable values:

  • Compliance Mandate: ONC (g)(10) and US Core IG require all FHIR data exchanged between certified health IT systems to adhere to the official FHIR R4 schema and clinical business rules — invalid resources result in failed certification and non-compliance fines.
  • Practical Necessity: Malformed FHIR data (e.g., a Patient resource with a birth date later than the current date, missing mandatory fields like name or gender) causes broken data exchange, incorrect clinical analytics, and even risks to patient safety in clinical workflows.

2. Key Concepts Overview

  • Hl7.Fhir.Validation Library: The official .NET library for FHIR resource validation, built to enforce FHIR R4/R5 schema rules and support custom business rule validation for all standard FHIR resources.
  • Schema Validation: Verifies that a FHIR resource adheres to the official FHIR R4 structure — e.g., mandatory fields are present, data types match specifications (e.g., birthDate is a valid date, gender is one of the FHIR-defined codes: male/female/other/unknown).
  • Business Rule Validation: Enforces clinical and organizational custom rules beyond basic schema — e.g., a patient’s age must be 0 or above, a U.S. patient’s address must include a valid ZIP code, and no duplicate patientId exists in the system.
  • Validation Result: A structured report returned by the library that identifies all validation errors (e.g., missing fields, invalid data, rule violations) with severity levels (error/warning/information) and detailed error messages.

2. Pain Points: The Hidden Risks of Unvalidated FHIR Data

After implementing FHIR data mapping and advanced queries, developers often overlook resource validation — a mistake that leads to critical issues in production healthcare systems. The most common pain points in FHIR resource validation for .NET/C# developers include:

  1. Missing Mandatory Fields: Raw data conversion often omits FHIR-mandated fields (e.g., Patient.name), resulting in schema validation failures and rejected data exchange requests from FHIR servers like Firely Server.
  2. Invalid Data Types & Logical Anomalies: Numeric fields store text values, birth dates are in the future, or gender values use custom codes (e.g., “M”/”F” instead of FHIR’s official “male”/”female”) — these issues break clinical data consistency and analytics.
  3. Lack of Custom Rule Enforcement: The default FHIR schema does not cover organizational/clinical business rules (e.g., valid ZIP codes for U.S. patients), leading to “schema-valid but clinically invalid” data.
  4. Unclear Validation Workflow: Developers struggle to integrate Hl7.Fhir.Validation into the FHIR data pipeline, with no clear C# examples for combining schema validation and custom rule validation, and no standardized way to handle and log validation errors.
  5. Late Error Detection: Validation is performed only after data is sent to the FHIR server, resulting in frequent request failures, increased network overhead, and inefficient debugging (errors are detected far after data conversion).

3. Solution: C# Implementation of FHIR Resource Validator (Schema + Business Rules)

3.1. Tech Stack Selection

  • Language: C#
  • Framework: .NET 8 or later version(cross-platform, enterprise-grade stability)
  • Core Libraries: Hl7.Fhir.R4 (v5.0.0), Hl7.Fhir.Validation (v5.0.0) — matching Firely Server R4
  • FHIR Server: Firely Server (https://server.fire.ly) — production-grade FHIR endpoint for validation result verification
  • Target Resource: Patient (FHIR R4) — the core clinical resource with strict schema and business rule requirements

3.2. Step-by-Step Implementation (With Key Code Snippets)

Step 1: Install NuGet Packages

Add the official FHIR validation library to your .NET project (extends the Basic Client/Advanced Query module dependencies):

// Install FHIR core and validation packages (compatible with R4)
Install-Package Hl7.Fhir.R4 -Version 5.0.0
Install-Package Hl7.Fhir.Validation -Version 5.0.0

Step 2: Initialize the FHIR Validator

Create a singleton FhirValidator instance to avoid repeated initialization and improve performance — configure it to enforce FHIR R4 schema rules and support custom business rule registration:

using Hl7.Fhir.Validation;
using Hl7.Fhir.Model;
using Hl7.Fhir.Serialization;
public static class FhirValidationManager
{
   // Singleton validator instance for FHIR R4
   private static readonly Validator _fhirValidator;
   static FhirValidationManager()
   {
     // Initialize validator with FHIR R4 specification
     var validationSettings = new ValidationSettings
     {
       EnableSchemaValidation = true, // Turn on schema validation
       Trace = true // Enable detailed error tracing
     };
     _fhirValidator = new Validator(validationSettings);
   }
   // Public method to get the validator instance
   public static Validator GetValidator() => _fhirValidator;
}

Step 3: Implement Schema Validation for Patient Resource

Validate a Patient resource against the official FHIR R4 schema — detect missing mandatory fields, invalid data types, and non-compliant code values:

// Create a test Patient resource with intentional errors (missing name, invalid birth date)
var invalidPatient = new Patient
{
   BirthDate = "2030–01–01", // Future birth date (logical error)
   Gender = AdministrativeGender.Unknown,
   // Missing mandatory field: Patient.Name (schema error)
   Address = new List<Address>
   {
     new Address { Line = new List<string> { "123 Main St" }, City = "New York", PostalCode = "10001" }
   }
};
  // Get FHIR validator instance
  var validator = FhirValidationManager.GetValidator();
  // Perform schema validation
  var schemaValidationResult = validator.Validate(invalidPatient);
  // Parse schema validation result
  if (!schemaValidationResult.IsValid)
  {
   Console.WriteLine("=== Schema Validation Errors ===");
   foreach (var issue in schemaValidationResult.Issues)
   {
     Console.WriteLine($"[{issue.Severity}] {issue.Message} (Location: {issue.Location})");
   }
}
else
{
   Console.WriteLine("Schema Validation Passed!");
}

Expected Schema Errors:

  • [Error] Element ‘Patient.name’ is mandatory and must be present. (Location: Patient.name)
  • [Warning] Date ‘2030–01–01’ is in the future and may be invalid. (Location: Patient.birthDate)

Step 4: Extend with Custom Clinical Business Rule Validation

Add custom business rules (U.S. healthcare-specific) to the validator — e.g., valid U.S. ZIP code (5 digits), no future birth dates, and mandatory Patient.Identifier for U.S. patients (per US Core IG):

public static class PatientBusinessRules
{
   // Validate custom business rules for U.S. Patient resources (US Core compliant)
   public static ValidationResult ValidateBusinessRules(Patient patient)
   {
     var issues = new List<ValidationIssue>();
     var now = DateTime.Now;
     // Rule 1: Birth date cannot be in the future
     if (patient.BirthDate != null && DateTime.Parse(patient.BirthDate) > now)
     {
       issues.Add(new ValidationIssue(
       severity: IssueSeverity.Error,
       message: "Patient birth date cannot be a future date.",
       location: "Patient.birthDate" ));
     }
     // Rule 2: U.S. ZIP code must be 5 numeric digits (if address is provided)
     if (patient.Address != null && patient.Address.Any())
     {
       var postalCode = patient.Address.First().PostalCode;
       if (!string.IsNullOrEmpty(postalCode) && !System.Text.RegularExpressions.Regex.IsMatch(postalCode, @"^d{5}$"))
       {
         issues.Add(new ValidationIssue(
         severity: IssueSeverity.Error,
         message: "U.S. postal code must be 5 numeric digits (US Core IG requirement).",
         location: "Patient.address.postalCode" ));
       }
     }
     // Rule 3: US Core requires a unique patient identifier (e.g., MRN)
     if (patient.Identifier == null || !patient.Identifier.Any())
     {
       issues.Add(new ValidationIssue(
       severity: IssueSeverity.Warning,
       message: "US Core IG recommends a unique patient identifier (e.g., MRN) for interoperability.",
       location: "Patient.identifier" ));
     }
     // Return custom validation result
     return new ValidationResult
     {
       IsValid = !issues.Any(),
       Issues = issues
     };
   }
}
// Extend the validation workflow to combine schema + business rules
public static ValidationResult FullPatientValidation(Patient patient)
{
     // Step 1: Schema validation
     var schemaResult = FhirValidationManager.GetValidator().Validate(patient);
     // Step 2: Custom business rule validation
     var businessResult = PatientBusinessRules.ValidateBusinessRules(patient);
     // Combine all issues
     var allIssues = schemaResult.Issues.Concat(businessResult.Issues).ToList();
     // Return combined result
     return new ValidationResult
     {
       IsValid = !allIssues.Any(),
       Issues = allIssues
     };
}

Step 5: Full Validation Workflow & Error Handling

Integrate the combined validation (schema + business rules) into the FHIR data pipeline — validate the Patient resource before sending it to the FHIR server, and handle errors with standardized logging:

// Create a corrected Patient resource (US Core compliant)
var validPatient = new Patient
{
   Name = new List<HumanName>
   {
       new HumanName { Given = new List<string> { "John" }, Family = "Doe" }
   },
   BirthDate = "1980–01–01",
   Gender = AdministrativeGender.Male,
   Identifier = new List<Identifier>
   {
       new Identifier { System = "https://hospital.example.com/mrn", Value = "MRN123456" } // Unique MRN (US Core)
   },
   Address = new List<Address>
   {
       new Address { Line = new List<string> { "123 Main St" }, City = "New York", PostalCode = "10001" } // Valid 5-digit ZIP
   }
};
// Perform full validation (schema + business rules)
var fullValidationResult = FullPatientValidation(validPatient);
// Handle validation result
if (fullValidationResult.IsValid)
{
   Console.WriteLine("=== Full Validation Passed ===");
   Console.WriteLine("Patient resource is FHIR R4 and US Core compliant - ready for storage/exchange.");
   // Proceed to send the resource to Firely Server
   var fhirClient = new Hl7.Fhir.Rest.FhirClient("https://server.fire.ly") { PreferredFormat = ResourceFormat.Json };
   fhirClient.Create(validPatient);
}
else
{
   Console.WriteLine("=== Full Validation Failed ===");
   // Log all errors (integrate with enterprise logging frameworks like Serilog/ELK in production)
   foreach (var issue in fullValidationResult.Issues)
   {
   Console.WriteLine($"[{issue.Severity}] {issue.Message} (Location: {issue.Location})");
   }
   // Halt data pipeline - do not send invalid data to the FHIR server
}

3.3. Production-Grade Optimization

For enterprise healthcare systems, add these optimizations to the Resource Validator module to meet high-concurrency, high-volume data processing requirements:

  1. Validation Caching: Cache validation rules for frequently used resources (e.g., Patient, Observation) to avoid repeated rule compilation.
  2. Bulk Validation: Extend the code to support bulk validation of multiple FHIR resources (e.g., a list of Patient resources) for EHR migration scenarios.
  3. Error Standardization: Map validation issues to FHIR’s official OperationOutcome resource for consistent error exchange with other FHIR systems.
  4. Integration with ETL Pipeline: Embed the validator into the Data Mapping ETL module (Module 4) to validate resources immediately after mapping — early error detection reduces development costs.

3.4. Source Code Access

The complete, production-ready Resource Validator module — including schema validation, custom business rule validation, bulk validation, and error standardization — is open-sourced at: my GitHub Portfolio. Commercial use requires authorization; the code can be directly pulled, debugged, and extended for your healthcare interoperability project.

4. Summary

4.1. Core Takeaways

This Resource Validator module equips you with the critical ability to enforce FHIR data quality and compliance in .NET/C# — a must-have skill for building production-grade healthcare interoperability solutions. Key takeaways include:

  • Mastery of the Hl7.Fhir.Validation library to implement FHIR R4 schema validation for core resources like Patient.
  • The ability to extend the validator with US Core and clinical business rules to meet ONC (g)(10) compliance requirements and real-world clinical needs.
  • A standardized validation workflow that combines schema and custom rules, with early error detection (before data is sent to the FHIR server) to reduce network overhead and debugging time.
  • Integration of validation into the FHIR data pipeline — a critical step to build a closed-loop, reliable healthcare data processing system.

4.2. Pro Tips to Avoid Pitfalls

  1. Version Consistency: Ensure the Hl7.Fhir.Validation library version matches the Hl7.Fhir.R4 SDK and Firely Server version (R4 recommended) — version mismatches cause unexpected validation errors.
  2. US Core Alignment: Custom business rules must align with the latest US Core IG (v7.1.0) — refer to the HL7 US Core official documentation for updated requirements.
  3. Severity-Based Handling: Differentiate between error (block data exchange) and warning (log and proceed) — e.g., a missing non-mandatory identifier is a warning, a missing name is an error.
  4. Validation Logging: Integrate the validator with enterprise logging tools (Serilog, Splunk) to track validation errors over time — this helps identify recurring issues in the data conversion pipeline (e.g., frequent invalid ZIP codes from a legacy EHR).

4.3. Series Preview

The next article in this series will focus on the Data Mapping ETL module — the core of connecting heterogeneous business systems to FHIR standards. We’ll explore how to use high-performance mapping tools (AutoMapper, Mapperly, Mapster) to implement bidirectional mapping between custom business models (e.g., PatientModel) and FHIR R4 resources, solving the ETL pain point of non-standard data to FHIR standard conversion. We’ll also compare the performance, cost, and practicality of the three mapping tools — a critical decision for enterprise FHIR projects.

5 References

1 ONC (g)(10) Interoperability and Information Blocking Rule | U.S. Department of Health and Human Services (HHS) | https://www.healthit.gov/topic/laws-regulation-and-policy/information-blocking

2 HL7 US Core Implementation Guide (IG) v7.1.0 | HL7 International | https://hl7.org/fhir/us/core/STU7.1/

3 2024–2025 Healthcare IT Market Analysis | Gartner | https://www.gartner.com/en/industries/healthcare-life-sciences/insights

4 FHIR R4 Validation Specification | HL7 International | https://hl7.org/fhir/R4/validation.html

5 .NET 6 for Enterprise Healthcare Applications | Microsoft Developer Network (MSDN) | https://learn.microsoft.com/en-us/dotnet/architecture/healthcare/

6 FHIR for .NET Developers: A Practical Guide | Microsoft Learn | https://learn.microsoft.com/en-us/dotnet/healthcare/fhir/

7 Hl7.Fhir.Net SDK Official Documentation (Validation Module) | HL7 FHIR .NET Working Group | https://docs.fire.ly/fhir-net-api/validation.html

8 Hl7.Fhir.Validation Library API Reference | Firely Health | https://firely.github.io/fhir-net-api/api/Hl7.Fhir.Validation.html

9 Clinical Data Quality for FHIR Interoperability | Journal of the American Medical Informatics Association (JAMIA) | https://academic.oup.com/jamia/article/30/1/12/6946256

10 Firely Server Production Best Practices (Validation) | Firely Health | https://docs.fire.ly/projects/Firely-Server/en/latest/best-practices/validation.html

11 US Core Patient Resource Requirements | HL7 International | https://hl7.org/fhir/us/core/STU7.1/StructureDefinition-us-core-patient.html

12 Error Handling in FHIR Data Pipelines | HL7 FHIR Implementation Guide | https://hl7.org/fhir/R4/operationoutcome.html

6 Disclaimer

All source code in this article is open-sourced at my GitHub Portfolio (commercial use requires authorization).

If you’re building FHIR/interoperability solutions, seeking .NET/C# + Healthcare IT (FHIR/HL7) expertise for commercial partnerships, or hiring for remote-friendly roles in this space — feel free to connect with me on LinkedIn.

I’m open to technical collaborations, commercial project partnerships, and new career opportunities that align with FHIR/HL7 interoperability and .NET healthcare development.

Originally published on Medium.