Written and maintained by CASRAI Editorial Board
Last updated
Smile Digital Health (formerly Smile CDR) is an enterprise health data fabric and Clinical Data Repository (CDR) platform built natively on the HL7 Fast Healthcare Interoperability Resources (FHIR) standard. Smile Digital Health serves as the commercial steward and primary engineering maintainer of HAPI FHIR (ca.uhn.hapi.fhir)—the world’s most widely deployed open-source Java implementation of the HL7 FHIR specification, originally developed at the University Health Network (UHN) in Toronto under lead architect James Agnew and licensed under the permissive Apache License 2.0.
In academic medical centers, national health information exchanges, public health agencies, and payer interoperability hubs, HAPI FHIR and Smile CDR form the core middleware layer used to ingest legacy HL7 v2 and C-CDA data streams, validate resources against HL7 FHIR US Core Implementation Guides, execute Clinical Quality Language (CQL) digital quality measures, and expose ONC-certified SMART on FHIR (§ 170.315(g)(10)) and CMS Interoperability and Prior Authorization (CMS-0057-F) APIs.
Architecture: How Smile CDR Builds on Open-Source HAPI FHIR
The open-source HAPI FHIR project consists of two primary Java frameworks: (1) the HAPI FHIR Core Library (strongly typed Java data models, JSON/XML/RDF parsers, fluent RESTful client, and StructureDefinition profile validator across FHIR DSTU2, STU3, R4, R4B, and R5), and (2) the HAPI FHIR JPA Server (an extensible Java Persistence API / Hibernate persistence engine that stores indexed FHIR resources inside PostgreSQL, Oracle, SQL Server, or MySQL databases).
Smile CDR embeds the HAPI FHIR engine inside a production-hardened, modular enterprise runtime, adding seven operational capabilities required by health systems and health plans:
- Multi-Format Ingestion & Mapping Engine: Out-of-the-box listener modules that ingest HL7 v2 (ADT, ORU, ORM, VXU), HL7 C-CDA clinical documents, ASC X12 837/835 claims, and CSV feeds, transforming them into validated FHIR R4/R5 transaction bundles.
- Polyglot Persistence & Horizontal Partitioning: Supports both relational JPA storage (with multi-tenant partition IDs) and document-oriented MongoDB storage, along with Elasticsearch/OpenSearch indexing for full-text narrative search and terminology expansion.
- Enterprise Master Patient Index (EMPI / MDM): Built-in deterministic and probabilistic patient matching module that links fragmented source-system Patient records to a golden master record via FHIR
PersonorPatient/$matchoperations without destructive merges. - SMART on FHIR Outbound Security & Identity Broker: Native OAuth 2.0 and OpenID Connect (OIDC) authorization server supporting fine-grained SMART v1/v2 clinical scopes (
patient/Observation.rs), fine-grained consent directives, and federated enterprise IdP integration (Okta, Azure AD / Entra ID, Keycloak). - Hybrid Providers (Facade Pattern): Enables a Smile CDR endpoint to expose a real-time FHIR REST API by translating incoming FHIR queries on the fly into SQL/RPC calls against an existing legacy EHR or clinical trial database without duplicating storage.
- Clinical Reasoning & CQL Engine: Executes HL7 Clinical Quality Language (CQL) libraries, FHIR
Measure/$evaluate-measureoperations, and CDS Hooks services for real-time clinical decision support and NCQA Digital HEDIS / CMS eCQM reporting. - Certified Regulatory Compliance Modules: Pre-certified to the ONC Health IT Certification Program 45 CFR § 170.315(g)(10) standardized API criterion and pre-configured for CMS-9115-F and CMS-0057-F (Patient Access, Provider Access, Payer-to-Payer, and Prior Authorization APIs).
Using HAPI FHIR in Java: Parsing, Serializing, and Validating FHIR R4 Resources
In Java clinical informatics applications (Maven group ca.uhn.hapi.fhir, artifacts hapi-fhir-base, hapi-fhir-structures-r4, and hapi-fhir-validation), the central entry point is FhirContext. Because initializing FhirContext.forR4() scans the classpath to build reflection metadata for hundreds of FHIR resource classes, it is computationally expensive and must be instantiated once as a thread-safe singleton, whereas IParser and IGenericClient instances are lightweight and created per operation:
import ca.uhn.fhir.context.FhirContext;import ca.uhn.fhir.parser.IParser;import ca.uhn.fhir.validation.FhirValidator;import ca.uhn.fhir.validation.ValidationResult;import org.hl7.fhir.r4.model.CodeableConcept;import org.hl7.fhir.r4.model.Coding;import org.hl7.fhir.r4.model.Observation;import org.hl7.fhir.r4.model.Quantity;import org.hl7.fhir.r4.model.Reference;public class HapiFhirR4Example { // Thread-safe singleton: instantiate once per JVM lifecycle private static final FhirContext CTX = FhirContext.forR4(); public static String buildAndValidateObservation() { Observation obs = new Observation(); obs.setStatus(Observation.ObservationStatus.FINAL); obs.getCode().addCoding(new Coding() .setSystem("http://loinc.org") .setCode("8480-6") .setDisplay("Systolic blood pressure")); obs.setSubject(new Reference("Patient/example-patient-01")); obs.setValue(new Quantity() .setValue(122) .setUnit("mmHg") .setSystem("http://unitsofmeasure.org") .setCode("mm[Hg]")); // Validate against base R4 StructureDefinitions FhirValidator validator = CTX.newValidator(); ValidationResult result = validator.validateWithResult(obs); if (!result.isSuccessful()) { throw new IllegalStateException("FHIR Validation failed: " + result.getMessages()); } // Serialize to pretty-printed FHIR JSON IParser jsonParser = CTX.newJsonParser().setPrettyPrint(true); return jsonParser.encodeResourceToString(obs); }}Comparing Java and Python HL7 FHIR SDKs and Server Frameworks
While enterprise CDR backends and EHR interface engines predominantly run on the JVM, biomedical data science, machine learning cohort extraction, and cloud FHIR R4 analytics rely heavily on Python FHIR packages:
| Library / Platform | Language & License | Core Architecture & FHIR Versions | Primary Clinical & Research Use Case |
|---|---|---|---|
HAPI FHIR (ca.uhn.hapi.fhir) |
Java (Apache 2.0) | Full model classes, JSON/XML/RDF parsers, fluent REST client, NPM IG package validator, and JPA/Hibernate server (DSTU2–R5) | Enterprise FHIR servers, HL7 v2-to-FHIR interface gateways, and production EHR integration microservices |
| Smile CDR (Smile Digital Health) | Java / JavaScript (Commercial Enterprise) | Built on HAPI FHIR with MongoDB/partitioned SQL, EMPI, SMART OAuth2 broker, CQL engine, and ONC g(10) certification | Turnkey health system Clinical Data Repositories, HIEs, and CMS-0057-F payer interoperability platforms |
| LinuxForHealth FHIR Server (formerly IBM FHIR Server) | Java (Apache 2.0) | High-performance, cloud-native Java FHIR R4/R4B server engineered by IBM and contributed to the Linux Foundation | Containerized cloud FHIR persistence and high-throughput FHIR Bulk Data ($export / $import) pipelines |
fhir.resources (Python) |
Python (BSD-3-Clause) | Built on Pydantic v2 (Rust-backed validation core); provides strict type checking, JSON/YAML/dict serialization for R4, R4B, and R5 | Validating and constructing FHIR resources in Python ETL scripts, FastAPI clinical microservices, and LLM data pipelines |
SMART fhirclient & fhir-py (Python) |
Python (Apache 2.0 / MIT) | Lightweight OAuth2 SMART on FHIR launch handler (fhirclient) and async/sync FHIR search client (fhir-py) |
Jupyter notebook research cohort extraction, SMART on FHIR web apps, and querying FHIR R4 endpoints into pandas/Polars DataFrames |
Python HL7 FHIR Example Using fhir.resources (Pydantic v2)
In Python research pipelines, fhir.resources validates FHIR R4 JSON dictionaries directly into Pydantic objects and exports clean JSON strings:
from fhir.resources.R4B.observation import Observationfrom fhir.resources.R4B.quantity import Quantityobs = Observation( status="final", code={"coding": [{"system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood"}]}, subject={"reference": "Patient/research-subj-104"}, valueQuantity=Quantity(value=6.1, unit="%", system="http://unitsofmeasure.org", code="%"))fhir_json = obs.model_dump_json(indent=2)Frequently Asked Questions
How does Smile CDR build on the open-source HAPI FHIR library?
HAPI FHIR (ca.uhn.hapi.fhir) is the open-source Apache 2.0 Java reference implementation of HL7 FHIR created at University Health Network (UHN) and maintained by Smile Digital Health. Smile CDR wraps the core HAPI FHIR library and JPA Server engine in an enterprise clinical data platform, adding out-of-the-box HL7 v2 and C-CDA ingestion pipelines, MongoDB and horizontally partitioned relational storage, an Enterprise Master Patient Index (EMPI), SMART on FHIR OAuth 2.0/OIDC security brokers, and ONC § 170.315(g)(10) and CMS-0057-F payer/provider regulatory compliance.
How do you use HAPI FHIR in Java to parse and validate FHIR R4 resources?
In Java, developers instantiate a thread-safe FhirContext.forR4() singleton (which is expensive to create and must be reused across threads), obtain a JSON or XML parser via ctx.newJsonParser(), parse a raw JSON payload into strongly typed model classes (such as org.hl7.fhir.r4.model.Patient or Observation), and validate conformance against StructureDefinition profiles and HL7 US Core Implementation Guides using ctx.newValidator() configured with a validation support chain.
What Python and Java SDKs are available for HL7 FHIR development?
In Java, the two primary open-source HL7 FHIR ecosystems are HAPI FHIR (ca.uhn.hapi.fhir, providing both a client/model SDK and a JPA/Hibernate server) and the LinuxForHealth (formerly IBM) FHIR Server. In Python, biomedical data engineers use fhir.resources (a Pydantic v2-based library providing strict schema validation and serialization for FHIR R4, R4B, and R5), fhirclient (the official SMART on FHIR Python client), and fhir-py for asynchronous REST API queries.
