FHIR Guide

What is FHIR?

FHIR is designed around reusable building blocks called resources. Instead of treating a complete healthcare record as one large document or one vendor-specific structure, an implementation can represent concepts such as a patient, encounter, observation, diagnosis or medication as individual resources and connect them through references.

That modular model matters because healthcare interoperability rarely happens between two identical systems. FHIR provides a shared structure that EHRs, applications, APIs, analytics platforms and interoperability services can use to exchange data with less dependence on proprietary formats.

How FHIR works

A real FHIR implementation is more than JSON over an API. Four layers work together: resources define the data model, APIs define interactions, profiles and implementation guides add use-case-specific rules, and terminology gives coded clinical data shared meaning.

FHIR resources: the building blocks of healthcare data exchange

HL7 FHIR R5 defines 157 resources. Implementations rarely use all of them. Teams select resources that match the information and workflow they need to exchange, then apply the profiles and implementation guides required by their environment.

{
  "resourceType": "Patient",
  "id": "example-001",
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Taylor",
      "given": ["Alex"]
    }
  ]
}

This is a simplified educational example. Production resources must follow the FHIR version, profiles, terminology and implementation rules that apply to the target workflow.

FHIR REST API: a consistent interaction model

The FHIR specification defines a RESTful API where resources are managed by type and servers declare which resources and interactions they support through a CapabilityStatement. Common interactions include reading a resource, searching by supported parameters, creating new resources and updating existing ones.

FHIR does not mean every server exposes every interaction. Your integration should inspect the server's capability statement and the applicable implementation guide before assuming which resources, search parameters or operations are available.

FHIR R4 vs R5 vs R6: which version should you use?

The newest FHIR material is not automatically the correct target for every implementation. Version choice depends on the systems you connect to, the implementation guides you must follow and the requirements of your market or use case.

Profiles and Implementation Guides make FHIR specific

Base FHIR is intentionally broad. A profile narrows a resource for a specific context by defining constraints such as required elements, cardinality, terminology bindings and extensions. An Implementation Guide, or IG, groups profiles with terminology, capability expectations, examples and supporting rules for a particular interoperability problem.

US Core is a practical example

For U.S. implementations, the US Core Implementation Guide is a major reference point. The current published version is US Core 9.0.0 (STU9), and it is based on FHIR R4. That is an important reminder that ecosystem requirements can remain on an earlier FHIR release even when a newer core specification exists.

FHIR validation: checking more than JSON syntax

FHIR validation is about whether a resource follows the rules that apply to it, not simply whether the JSON parses. HL7 describes validation across structure, cardinality, value domains and other constraints. When a profile applies, the resource also needs to satisfy those profile-specific rules.

FHIR also defines a $validate operation. When supported by a FHIR server, it can validate submitted content and return an OperationOutcome that describes issues found during validation.

FHIR security: the API is only one layer

The core FHIR REST API defines how resources can be exchanged, but it does not by itself solve authentication, authorization, audit and privacy requirements. HL7's security guidance recommends established web security mechanisms and specifically points implementers toward OAuth and SMART App Launch where appropriate.

A production design should consider transport security, client and user authentication, authorization scopes, consent requirements, audit events, provenance, data minimization and the policies that apply to the environment.

A practical FHIR implementation checklist

FHIR projects become easier to manage when versioning, profiles and validation are decided before interface development starts. Use this sequence as a planning framework rather than beginning with individual JSON examples.

1. 01
   Define the exchange use case.

   Identify the data, actors, workflow and downstream outcome before choosing resources.

2. 02
   Confirm the FHIR version.

   Match the systems, implementation guides and jurisdiction you actually need to support.

3. 03
   Identify resources and profiles.

   Map source data to the correct resource types and profile constraints.

4. 04
   Resolve terminology requirements.

   Understand required code systems, value sets and units before transformation logic is finalized.

5. 05
   Transform and normalize source data.

   Convert legacy or proprietary structures into the FHIR representation required by the target workflow.

6. 06
   Validate early.

   Check base FHIR rules and profile-specific constraints before data moves downstream.

7. 07
   Test API behavior.

   Confirm capabilities, supported searches, operations, error handling and authentication patterns.

8. 08
   Monitor production variation.

   Real source systems change. Keep transformation, validation and data-quality checks visible over time.

Common FHIR implementation mistakes

FHIR frequently asked questions

Official FHIR sources used for this guide

FHIR changes through a formal standards-development process. For implementation decisions, always verify requirements against the official specification and the implementation guides that apply to your project.

Last reviewed: September 29, 2026.