The Fork in the Road

In early 2024, while designing the data layer for LivoRx, we sat in front of a whiteboard and drew two columns. On the left: a custom relational schema — fast to build, full control, no external dependencies. On the right: FHIR R5 — verbose, opinionated, with tooling that was still maturing at the time of the R5 release in March 2023. We chose the right column. Not because it was the easy path — it wasn't — but because we understood that in healthcare, the cost of getting the data model wrong is not measured in refactors. It is measured in years of integration work, failed compliance audits, and systems that cannot talk to each other.

Two years in, that decision has shaped every feature we've shipped. This is the honest account of why we made it, what it cost us, and what it gave us in return.

8 FHIR R5 resource types in production
135+ API endpoints exposing FHIR-structured data
R5 HL7 final spec, published February 2023
ABDM Compliant via FHIR interoperability layer

What FHIR R5 Actually Is

FHIR — Fast Healthcare Interoperability Resources — is HL7's standard for representing and exchanging clinical and administrative health data. It defines a set of typed resources (think: strongly-typed JSON objects with well-known field names, terminologies, and relationships), a RESTful API surface, and a set of operations for searching, subscribing, and bundling data across systems.

R5 is the fifth major version, finalized in February 2023 after a four-year development cycle. The headline improvements over R4 matter more in practice than the version number suggests:

  • Subscriptions redesigned — R5 ships a topic-based subscription model that replaces the fragile R4 criteria-based approach, making real-time result delivery tractable without polling hacks.
  • Observation.value polymorphism cleaned up — R5 resolves ambiguity in how lab values, coded observations, and component observations relate, which directly affects how we model diagnostic results.
  • Package management and canonical resources — Implementation guides can now be versioned, published, and referenced as packages, which matters for ABDM conformance profiles.
  • Provenance and audit trail enhancements — R5's Provenance resource has richer agent typing, which we use for PHI audit trails (relevant to TECH-07).
  • Cross-version extensions formalized — Backporting data to R4 consumers became a defined operation rather than a bespoke translation layer.

Why Not R4?

R4 is the most widely deployed FHIR version today. Most EHR vendor APIs speak R4. We evaluated it seriously. The decision against R4 came down to two factors: the subscription model in R4 was genuinely unfit for real-time lab result delivery, and starting on R4 would mean a migration to R5 within two years anyway — migration being far more painful in production than in greenfield. We chose to absorb the tooling immaturity of R5 early rather than the migration cost of R4 later.

The Eight Resources We Actually Use

FHIR R5 defines over 150 resource types. In two years of production, we have found that eight carry the weight of the platform. Understanding how they fit together explains why FHIR was the right choice — each resource is a contract, not just a schema, and that contract is what makes third-party integrations possible without renegotiation.

Patient

Demographics, identifiers, contacts, and consent anchors. Every FHIR resource in our system is subject-referenced to a Patient. ABDM Health ID links live here as an identifier slice.

Encounter

The telehealth visit itself — status lifecycle (planned → in-progress → finished), participant references, duration, and the class code that distinguishes virtual from in-person. The backbone of our patient timeline.

Observation

Lab values, vitals, and any measurable clinical finding. A TSH result is an Observation with a LOINC code, a value[x] of type Quantity, and a reference range. The polymorphic value type is where R5 improved substantially over R4.

DiagnosticReport

Groups related Observations into a reportable result — a full lipid panel, a thyroid panel, a CBC. Our lab-to-insight pipeline ingests HL7 v2 ORU^R01 messages and maps them to DiagnosticReport + Observation pairs.

MedicationRequest

Prescriptions and medication orders with RxNorm coding. The 80-pair drug interaction matrix and 9 allergen class checks run against MedicationRequest resources before any prescription is finalized.

Condition

Active diagnoses and problem list entries with ICD-10-CM coding. Referenced by Encounter for visit context and surfaced in the patient health timeline alongside labs and prescriptions.

ServiceRequest

Lab orders and referrals. When a physician orders a CBC during a visit, a ServiceRequest with a LOINC panel code is created. This is the order that initiates the lab-to-insight pipeline.

Bundle

The export envelope. Our FHIR R5 Bundle export (TECH-08) packages all eight resource types into a standards-compliant patient record that can be ingested by any FHIR-capable system — no adapter required.

What FHIR Made Directly Possible

Drug Safety at the Data Layer

When we built the drug interaction check (MD-08, MD-09), we didn't build it on top of a proprietary medication table. We built it on MedicationRequest resources with canonical RxNorm codes. The consequence: any medication entered by any provider, in any part of the platform, participates in the same interaction check. There is no "medication entered in the old system" that bypasses the safety layer. The RxNorm code is the medication. That uniformity is only possible because FHIR gives us a typed, coded medication model that every part of the codebase speaks.

Lab Results Without Custom Parsers

HL7 v2 ORU^R01 messages — the format most labs still transmit results in — map directly to FHIR DiagnosticReport and Observation with well-defined transformations. The LOINC code in the OBX segment becomes the Observation.code.coding[0].code. The result value becomes Observation.value[x]. The reference range becomes Observation.referenceRange[0]. We wrote this transformation once. Every lab we integrate with, regardless of which LIS they run, follows the same path.

ABDM Compliance Without a Separate Layer

India's Ayushman Bharat Digital Mission defines its data exchange format as a FHIR implementation guide. Because we are already on FHIR R5, ABDM compliance meant implementing a conformance profile — not a data migration. Our Patient resources gained an ABHA identifier slice. Our Encounter resources gained the required class and serviceType codings. What would have been a six-month integration project for a custom-schema platform took us six weeks.

"Interoperability is not a feature you add. It is a property of the data model you choose at the start. We chose FHIR R5 so that interoperability would be the default, not the exception."

The FHIR Bundle Export

TECH-08 — our patient record export — produces a valid FHIR R5 Bundle containing Patient, Encounter, Observation, DiagnosticReport, MedicationRequest, Condition, ServiceRequest, and Provenance resources. A patient can export their full health record in a format that any FHIR R5 server can ingest. No proprietary format. No conversion step. No vendor lock-in. This is only possible because the data was FHIR-native from day one — not because we wrote an export converter after the fact.

The Trade-offs We Accepted

FHIR is not free. The costs are real and worth naming honestly.

  • Verbosity. A FHIR Bundle for a single telehealth encounter with two diagnoses, three lab results, and one prescription can be 15–20 KB of JSON. A custom schema representation of the same data might be 2 KB. We pay this cost on every export and every integration call. We decided the cost was worth the interoperability guarantee.
  • Tooling immaturity at R5 launch. In 2024, R5 validation libraries, reference implementations, and conformance test suites were less complete than their R4 equivalents. We wrote several validation utilities ourselves that we expected to already exist. They do now — R5 tooling has matured significantly in 18 months — but the early months required more custom work than anticipated.
  • Couchbase + FHIR mental model. FHIR resources are document-oriented, which maps naturally to Couchbase's document storage. But FHIR's reference model (resources linked by logical ID across resource types) requires careful index design to avoid N+1 query patterns when building the patient timeline. We solved this with compound indexes on resource type and subject reference, but the design took iteration.

One Thing We'd Do Differently

We started with a monolithic FHIR repository — all resource types in a single Couchbase collection with a resourceType discriminator field. As the platform grew, query performance on large patient timelines required retroactively partitioning into per-resource-type collections. We would design that partition from day one if starting again. The FHIR data model is correct; the storage topology needed more upfront thought.

What Comes Next

HL7 is actively developing FHIR R6, with a focus on clinical decision support hooks, subscription performance at scale, and tighter integration with SMART on FHIR authorization flows. We are tracking two R6 capabilities closely:

  • CDS Hooks integration — real-time clinical decision support triggered at the point of order entry, which will extend our drug interaction checking from a pre-prescription check to an ambient, encounter-time signal.
  • Subscription Topics at scale — R6 refinements to the topic-based subscription model will allow us to push lab result notifications without the lightweight polling fallback we currently maintain for high-latency lab partners.

The investment in FHIR R5 compounds over time. Every new integration we build starts from a shared contract, not a blank page. Every new standard that targets FHIR finds us already at the table. That is what it means for interoperability to be a feature rather than an afterthought — you don't plan for it every time a new requirement arrives. You already have it.

  • HL7 International. FHIR R5 — HL7 FHIR Release 5. Published February 2023. hl7.org/fhir/R5
  • Office of the National Coordinator for Health IT (ONC). 21st Century Cures Act: Interoperability, Information Blocking, and the ONC Health IT Certification Program Final Rule. Federal Register, 2020.
  • National Health Authority, India. Ayushman Bharat Digital Mission — FHIR Implementation Guide. NHA, 2022.
  • Lehne, M., Sass, J., Essenwanger, A., Schepers, J., & Thun, S. Why digital medicine depends on interoperability. npj Digital Medicine, 2(1), 1–3, 2019.
  • HIMSS. Interoperability in Healthcare. HIMSS Thought Leadership, 2023.
  • Mandel, J. C., Kreda, D. A., Mandl, K. D., Kohane, I. S., & Ramoni, R. B. SMART on FHIR: a standards-based, interoperable apps platform for electronic health records. Journal of the American Medical Informatics Association, 23(5), 899–908, 2016.
  • Bates, D. W., & Landman, A. Innovating without evidence: the perils of clinical AI that learns on the fly. Nature Digital Medicine, 4(1), 2021.
  • Regenstrief Institute. LOINC — Logical Observation Identifiers Names and Codes. regenstrief.org/item/loinc, 2024.