HL7 FHIR R4 Without the Pain — A Practical Guide for Healthtech Teams
Most teams approach FHIR as a compliance hurdle and end up with brittle integrations. Approached as a data model, it becomes the most flexible asset in the platform. Here’s how we think about it.
Most healthtech engineering teams encounter HL7 FHIR R4 the same way: a hospital partner says “we need FHIR R4 export,” the team Googles “FHIR R4 spec,” and three weeks later they've built a custom JSON shape that looks like FHIR but won't actually round-trip with any compliant EHR.
That's the path of pain. Here's the path we've taken across multiple deployments — including ArogyaTrack — that turns FHIR from a compliance checkbox into a structural advantage.
1. Pick your resources before you pick your features
FHIR has 145+ resource types. You don't need most of them. For the typical patient-facing platform, the “hot 12” cover 95% of cases:
- Patient, Practitioner, Encounter
- Observation, DiagnosticReport, ImagingStudy
- Condition, AllergyIntolerance, Procedure
- MedicationRequest, MedicationStatement
- DocumentReference (for the unstructured PDF lake everyone has)
Get those 12 right, with proper extensions for the regional gaps (ABHA in India, NHS identifier in the UK, MRN in the US), and you can interoperate with most major EHRs.
2. Treat FHIR as the database shape, not the API shape
The most common mistake: teams treat FHIR as something they only emit at export time, backed by a normalized SQL schema that doesn't map cleanly to FHIR. Every export becomes a translation layer with edge cases. Every translation layer breaks at scale.
The cleaner pattern: store FHIR-shaped resources natively (document store, JSONB column, or proper FHIR server like HAPI). Index the fields you query. Translate intoyour application layer, not out of it. This means clinical data stays canonical and your app screens are just projections.
3. Versioning is real and matters
FHIR R4 is the dominant standard, but R5 is shipping with breaking changes. Build your resource layer with a version field from day one. We use a thin adapter that maps R4 to our internal canonical model, so when R5 hits a partner, we map R5 there too without rewriting business logic.
4. Validate aggressively, fail loudly
Use a real FHIR validator (HAPI's structure definitions, or the official Inferno test kit) in CI. Reject invalid resources at write time, not export time. We catch ~60% of integration bugs at this layer alone.
5. Don't skip Provenance and Consent
The two resources teams skip first are the two regulators care about most. Provenance tells you where a record came from and who wrote it. Consent tells you who's allowed to see it. Add them on day one — retrofitting is painful and you can't pass an audit without them.
FHIR isn't a feature. It's the data model your platform should have had from the start. Treat it that way and the “FHIR export” ticket disappears — it ships for free.
What we ship in our healthcare deployments
- FHIR R4-native storage with the “hot 12” resources first-class
- HAPI-validated input and output, blocking writes on schema violations
- Provenance + Consent on every resource from day one
- OAuth2 / SMART-on-FHIR for partner authorization
- Audit-ready logs of every read and write, exportable on subject access requests
If your team is staring down a FHIR R4 integration deadline and the work feels like it could spiral, this is exactly what our healthcare engineering practice handles. Get in touch and we'll do a 30-minute audit of where your data model is right now.