SMART on FHIR: How It Works and How to Build Apps That Launch Inside EHRs
Learn how SMART on FHIR connects apps to EHRs using FHIR APIs and OAuth2. Covers launch flows, scopes, Epic and Cerner setup, SMART v2, and building your first app.
Healthcare data standards like FHIR need to evolve without disrupting existing systems. But how does FHIR manage updates and changes while keeping everything running smoothly?
Before we look at how versioning works in FHIR, it’s helpful to first understand a common idea from the software world called semantic versioning. If you’ve ever seen software versioning or a software version number like 1.2.3 or 4.0.1, you’re already familiar with the format. But do you know what those numbers actually represent?
What is semantic versioning?
Semantic versioning, often called SemVer, follows a simple format: MAJOR.MINOR.PATCH, or, in shorthand: X.Y.Z
Each of these segments tells us something about the type of changes made in a software release:
- MAJOR (X): These are big changes that may not work with previous versions. These include updates to APIs, logic, or structure that can break compatibility.
- MINOR (Y): This indicates new features are added without breaking anything that worked before. Here, functionality is improved while keeping compatibility.
- PATCH (Z): This is for bug fixes, small improvements, or security updates that fix problems without changing how the software behaves.
For example, let’s say your app starts at version 1.0.0.
- You fix a bug → new version is 1.0.1 (patch update).
- You add a new non-breaking feature → version becomes 1.1.0 (minor update).
- You redesign the app in a way that breaks old features → version jumps to 2.0.0 (major update).
If you want to understand FHIR better then do read our article “What is FHIR?”.
So, how does software versioning connect to how FHIR releases are named and managed?
How is versioning done in FHIR?
FHIR uses semantic versioning too. Each release of FHIR, whether it’s R4, R5, or the earlier trial versions, FHIR versions follows the same principles:
| Semantic Version | FHIR Example | Notes | |---|---|---| | MAJOR | 4.0.0 → 5.0.0 | Major changes, possibly breaking compatibility | | MINOR | 4.0.0 → 4.1.0 | New features, still backward-compatible | | PATCH | 4.0.0 → 4.0.1 | Bug fixes, small refinements |
Before the current versions like R4 and R5, FHIR had what were called DSTU releases, or Draft Standard for Trial Use.
These were early-stage versions that were not fully mature, but shared with implementers and developers for real-world feedback. They were part of FHIR’s iterative development approach.
What are the major releases in FHIR
FHIR R4, R5, or the upcoming R6, refer to major releases in FHIR. These versions often include changes that aren’t compatible with previous ones. Just like going from version 1.0.0 to 2.0.0 in semantic versioning, moving from FHIR R4 to R5 usually means systems built on R4 may need updates to keep working properly.
That’s why healthcare organizations and developers take FHIR major releases seriously. Moving to a new major version usually means making significant changes to the system to maintain compatibility.
To understand this better, visit the FHIR website, you’ll see this FHIR versioning model. FHIR R4 is officially version 4.0.1, while FHIR R5 is version 5.0.0. There’s also an intermediate release called R4B, which includes new features but avoids introducing major breaking changes. These version numbers reflect the nature of the changes in each release.
Also, when moving between major FHIR releases, like R4 to R5, the FHIR Mapping Language helps. It documents how resource structures differ between versions and can even automate the conversion between them, making updates easier to manage.
The FREE FHIR Fundamentals course is an excellent way to gain a deeper understanding of FHIR. It helps get a clear grasp of FHIR’s structure, ensuring you can handle integration, updates, and system compatibility effectively.
What do these FHIR versions mean for implementers?
If you build, integrate, or manage systems using FHIR, understanding how its versioning works is part of the job, as it affects how systems run and work together. Here is why:
- Compatibility: Moving from one FHIR version to another may mean refactoring how your systems interact with FHIR resources.
- Data Modeling: Even small changes to resource structures can affect storage, queries, or decision support rules.
- Interoperability: Not all systems move to the same FHIR version at the same time. You might have to support multiple versions in parallel.
FHIR is built to be a flexible standard, but it still needs to evolve. This is where versioning helps make those changes predictable, so people know what’s new, what’s different, and what needs attention.
Quick recap
FHIR evolves over time, and with that, the need to understand how versioning works in FHIR is important. Semantic versioning brings clarity and predictability to these changes. So, if you’re working with version 4.0.1, preparing for 5.0.0, or maintaining older systems, knowing how versioning works ensures your systems stay compatible and ready for future updates.
Related articles
View all
What is HL7? Understanding the Standard Behind Healthcare Data Exchange
This article details HL7's role in healthcare data exchange since 1987. It explores the standards family including legacy v2, CDA, and modern FHIR APIs highlighting their necessity for interoperability, regulatory compliance, and system integration.
What Is FHIR? The Complete Developer Guide [2026, R4]
The complete guide to FHIR (Fast Healthcare Interoperability Resources). Learn FHIR resources, R4, Profiles and Implementation Guides, SMART on FHIR, HL7 history, and how to start.
