Introduction to FHIR
FHIR (Fast Healthcare Interoperability Resources) is HL7's next-generation healthcare data exchange standard. Built on modern web technologies, FHIR combines the best aspects of previous HL7 standards while leveraging RESTful APIs, JSON/XML data formats, and OAuth2 security to enable seamless healthcare interoperability.
Unlike HL7 v2's event-driven messaging or HL7 v3's complex RIM-based XML, FHIR uses a resource-oriented approach with familiar REST patterns that web developers already understand. This makes FHIR significantly easier to implement while providing powerful capabilities for modern healthcare applications.
Why FHIR?
FHIR addresses key limitations of previous standards: developer-friendly formats (JSON/XML), standard REST APIs, granular data access, robust security (OAuth2/SMART), extensive ecosystem support, and regulatory mandates (21st Century Cures Act, USCDI, TEFCA).
HL7 FHIR R4 Specification
Official FHIR R4 specification with complete resource definitions
View FHIR R4 SpecFHIR Fundamentals
Stable HL7 R4 documentation for browsing resources and core specification pages.
FHIR R4 ResourcesResource Modeling Best Practices
FHIR uses standard HTTP methods (GET, POST, PUT, DELETE, PATCH) to perform CRUD (Create, Read, Update, Delete) operations on resources. This RESTful approach makes FHIR APIs familiar to web developers and compatible with existing web infrastructure.
HTTP Methods in FHIR
FHIR REST API operations
| Method | Operation | Example URL | Success Response |
|---|---|---|---|
| GET | Read a resource by ID | GET /Patient/123 | 200 OK + Patient resource |
| GET | Search for resources | GET /Patient?name=smith | 200 OK + Bundle (searchset) |
| POST | Create a new resource | POST /Patient | 201 Created + new resource with ID |
| PUT | Update/replace entire resource | PUT /Patient/123 | 200 OK + updated resource |
| PATCH | Partial update (specific fields) | PATCH /Patient/123 | 200 OK + updated resource |
| DELETE | Delete a resource | DELETE /Patient/123 | 204 No Content |
GET: Read and Search Operations
GET is used to retrieve resources. You can read a specific resource by ID or search for resources using query parameters.
FHIR GET Examples
Examples of GET operations for reading and searching resources
Request
GETANNOTATIONS
Response
POST: Create Resources
POST creates new resources. The server assigns a unique logical ID and returns the created resource with a 201 Created status.
FHIR POST Example
Creating a new Observation resource
Request
POSTANNOTATIONS
Response
PUT: Update/Replace Resources
PUT replaces the entire resource at a specific URL. All fields are replaced, even if not included in the request. Use PATCH for partial updates.
FHIR PUT Example
Updating an existing Patient resource
Request
PUTANNOTATIONS
Response
DELETE: Remove Resources
DELETE removes a resource from the server. The server returns 204 No Content on success. Note: Many FHIR servers implement soft-delete (marking as inactive) rather than hard-delete for audit purposes.
Delete Considerations
FHIR servers may not physically delete resources for audit and legal compliance. Instead, they may mark resources as inactive or return 405 Method Not Allowed if deletion is not permitted.
HTTP Status Codes
Common FHIR HTTP status codes
| Status Code | Meaning | When Returned |
|---|---|---|
| 200 OK | Success | GET, PUT, PATCH operations succeed |
| 201 Created | Resource created | POST creates new resource |
| 204 No Content | Success, no body | DELETE succeeds |
| 400 Bad Request | Invalid request | Malformed syntax or invalid content |
| 401 Unauthorized | Authentication required | No valid credentials provided |
| 403 Forbidden | Authorization denied | Insufficient permissions |
| 404 Not Found | Resource not found | Requested resource ID does not exist |
| 409 Conflict | Version conflict | Resource was modified since read |
| 422 Unprocessable Entity | Validation failure | Resource fails FHIR validation |
FHIR Resources: Building Blocks
Resources are the fundamental building blocks of FHIR. Each resource is a modular data structure representing a specific clinical or administrative concept, such as a Patient, Observation, MedicationRequest, or Encounter.
Resource Structure
All FHIR resources share a common structure with standardized elements:
- resourceType: Identifies the type of resource (e.g., "Patient", "Observation")
- id: Logical ID assigned by the server (unique within the resource type)
- meta: Versioning, profiles, tags, and security labels
- implicitRules: Rules applied to this resource content
- language: Base language of the resource content
- text: Human-readable narrative summary (for display)
- contained: Contained (inline) resources
- extension: Additional data not part of base definition
- modifierExtension: Extensions that modify understanding
Common Clinical Resources
Essential FHIR R4 resources
| Resource | Purpose | Key Elements |
|---|---|---|
| Patient | Patient demographics and administrative data | name, gender, birthDate, address, telecom, identifier |
| Encounter | Healthcare visits and interactions | status, class, subject, period, participant, location |
| Observation | Clinical measurements and test results | status, code, value[x], subject, effectiveDateTime, referenceRange |
| Condition | Diagnoses, problems, and health concerns | clinicalStatus, verificationStatus, category, code, subject, onsetDateTime |
| MedicationRequest | Medication orders and prescriptions | status, intent, medication[x], subject, dosage, dispenseRequest |
| DiagnosticReport | Lab and imaging reports | status, category, code, subject, result, conclusion, presentedForm |
| Practitioner | Healthcare provider information | name, telecom, address, qualification, identifier |
| Organization | Healthcare organizations and facilities | name, type, address, telecom, endpoint |
Patient Resource Example
The Patient resource contains comprehensive demographic and administrative information about a person receiving healthcare services:
Patient Resource (US Core Profile)
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Observation Resource Example
The Observation resource captures clinical measurements, laboratory results, and other assessments:
Observation Resource (Vital Signs)
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
MedicationRequest Resource Example
The MedicationRequest resource represents medication orders and prescriptions:
MedicationRequest Resource
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Practitioner Resource Example
The Practitioner resource contains information about healthcare providers:
Practitioner Resource (AU Profile)
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Resource References
Resources reference each other using the "reference" element. For example, Observation.subject references Patient, and Encounter.patient references Patient. References use the format "ResourceType/id" (e.g., "Patient/123").
Bundle Resource: Batch Processing
The Bundle resource packages multiple resources together for various purposes: batch transactions, search results, document exchange, and message history. Bundles enable efficient processing of multiple resources in a single API call.
Bundle Types
FHIR Bundle types and use cases
| Type | Purpose | Use Case | Atomic |
|---|---|---|---|
| document | Clinical document exchange | Discharge summaries, consult notes | No |
| message | Event-driven notification | ADT notifications, alerts | No |
| transaction | Multiple operations with all-or-nothing semantics | Create patient + encounter + observation together | Yes (entire bundle fails if any entry fails) |
| batch | Multiple independent operations | Bulk data import, independent updates | No (each entry processed independently) |
| searchset | Search results | GET /Patient?name=smith results | N/A (read-only) |
| history | Resource version history | Tracking changes over time | N/A (read-only) |
Transaction Bundle
Transaction bundles execute multiple operations with all-or-nothing semantics. If any entry fails, the entire transaction is rolled back and no changes are persisted. This ensures data consistency across related resources.
Transaction Bundle: Create Patient + Encounter + Observation
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Transaction Bundle Rules
All entries in a transaction bundle must succeed or all fail. Use urn:uuid: placeholders for resources that reference each other within the same bundle. The server resolves these references after assigning real IDs.
Batch Bundle
Batch bundles process each entry independently. Individual entry failures do not affect other entries. Use batch bundles for bulk operations where atomicity is not required.
Batch vs Transaction
Use transaction bundles when operations are interdependent (e.g., creating a patient and related encounter). Use batch bundles for independent operations (e.g., updating multiple unrelated patients).
Searchset Bundle
Searchset bundles contain the results of a FHIR search operation. They include matching resources, pagination links, and the total count of matches.
Searchset Bundle: Patient Search Results
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Bundle Entry Structure
Each bundle entry contains:
- fullUrl: Canonical URL or urn:uuid for the entry
- resource: The actual FHIR resource (for most bundle types)
- request: HTTP method and URL for transaction/batch operations
- response: Status code and location for transaction/batch results
- search: Search mode ("match", "include", "outcome") for searchset bundles
JSON and XML Data Representation
FHIR supports two data formats: JSON (primary, recommended) and XML. Both formats represent the same information with different syntax. JSON is preferred for its simplicity, smaller payload size, and native JavaScript support.
FHIR JSON Format
FHIR JSON uses standard JSON types with specific conventions:
- Media type: application/fhir+json
- Primitive values: JSON primitives (string, number, boolean, null)
- Objects: FHIR elements as JSON objects
- Arrays: Repeating elements as JSON arrays
- null values: Omitted or explicitly null (both valid)
Primitive Types in JSON
FHIR primitive types mapped to JSON
| FHIR Type | JSON Representation | Example |
|---|---|---|
| string | JSON string | "John Smith" |
| integer | JSON number | 42 |
| decimal | JSON number | 3.14159 |
| boolean | JSON boolean | true |
| date | JSON string (ISO 8601) | "2024-01-15" |
| dateTime | JSON string (ISO 8601) | "2024-01-15T10:30:00Z" |
| instant | JSON string (ISO 8601) | "2024-01-15T10:30:00.123Z" |
| code | JSON string | "M" |
| uri | JSON string | "http://loinc.org" |
FHIR XML Format
FHIR XML provides an alternative representation for systems requiring XML:
- Media type: application/fhir+xml
- Root element: <{resourceType}> with FHIR namespace
- Elements: XML elements matching FHIR element names
- Attributes: Used for id, extension URLs, and type information
- Primitive values: Text content of elements
<Patient xmlns="http://hl7.org/fhir">
<id value="example-patient-123"/>
<meta>
<versionId value="1"/>
<lastUpdated value="2024-01-15T10:30:00Z"/>
</meta>
<identifier>
<use value="usual"/>
<type>
<coding>
<system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
<code value="MR"/>
<display value="Medical Record Number"/>
</coding>
</type>
<system value="http://hospital.example.org/mrn"/>
<value value="MRN123456"/>
</identifier>
<active value="true"/>
<name>
<use value="official"/>
<family value="Smith"/>
<given value="John"/>
<given value="Michael"/>
</name>
<gender value="male"/>
<birthDate value="1980-01-15"/>
<address>
<use value="home"/>
<line value="123 Main Street"/>
<city value="Springfield"/>
<state value="IL"/>
<postalCode value="62701"/>
<country value="USA"/>
</address>
</Patient>JSON vs XML Comparison
FHIR JSON vs XML characteristics
| Characteristic | JSON | XML |
|---|---|---|
| Payload Size | Smaller (~30% less) | Larger (verbose tags) |
| Parsing Speed | Faster (native in JS) | Slower (DOM parsing) |
| Readability | High (concise) | Moderate (verbose) |
| Schema Validation | JSON Schema | XML Schema (XSD) |
| Developer Preference | Preferred (modern) | Legacy systems |
| Browser Support | Native JSON.parse() | DOMParser required |
Format Negotiation
Clients can request a specific format using the Accept header: "Accept: application/fhir+json" or "Accept: application/fhir+xml". Servers should respect the client's preference when possible.
Comparison: HL7 v2 vs v3 vs FHIR
Understanding the evolution from HL7 v2 through v3 to FHIR helps contextualize why FHIR has become the preferred standard for modern healthcare interoperability.
Standards Comparison Matrix
HL7 v2 vs HL7 v3 vs FHIR comprehensive comparison
| Feature | HL7 v2 | HL7 v3 | FHIR |
|---|---|---|---|
| Data Format | Pipe-delimited text (|, ^, ~, \, &) | XML (RMIM-based, verbose) | JSON (primary) or XML (web-friendly) |
| Transport Protocol | MLLP over TCP (port 2575) | Various (SOAP, HTTP, MLLP) | HTTP/HTTPS REST (standard web protocols) |
| Message Structure | Segments (MSH, PID, PV1, OBX, etc.) | RIM-based XML messages | Resources (Patient, Observation, etc.) |
| API Style | Event-driven messaging (ADT^A01, ORU^R01) | Complex interaction patterns | RESTful CRUD operations (GET, POST, PUT, DELETE) |
| Learning Curve | Moderate (delimiter handling, segment knowledge) | Steep (RIM complexity, XML verbosity) | Gentle (familiar REST/JSON patterns) |
| Extensibility | Z-segments (custom segments) | Complex extension mechanisms | Extensions with URLs, Profiles, Implementation Guides |
| Search Capability | None (point-to-point messaging) | Limited | Rich URL-based search parameters |
| Security | Transport-level (TLS), no standard auth | WS-Security, variable implementation | OAuth2, SMART on FHIR, HTTPS, granular scopes |
| Versioning | Multiple versions (2.3, 2.4, 2.5, 2.7, 2.8, 2.9) | Multiple releases | R4 (current), R4B, R5 (evolving) |
| Developer Ecosystem | Mature, interface engines (Mirth, Rhapsody) | Limited adoption | Large, growing (HAPI, Firely, SDKs, app stores) |
Standards Evolution Timeline
HL7 standards evolution and architecture
Loading diagram...
Key Differences Explained
Data Format
HL7 v2 uses pipe-delimited text with special characters (|, ^, ~, \, &) that require careful escaping. HL7 v3 uses verbose XML based on the Reference Information Model (RIM). FHIR uses JSON (primary) or XML with a simpler, more intuitive structure.
HL7 v2: Pipe-delimited format
A traditional HL7 v2 message uses segments (MSH, PID, OBR, OBX) and pipe-delimiters for data structure.
Click on a segment above to highlight its fields
Hover or click any field value for detailed explanation
FHIR: JSON format (same data)
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
Transport Protocol
HL7 v2 traditionally uses MLLP (Minimal Lower Layer Protocol) over TCP, requiring dedicated interface engines. FHIR uses standard HTTP/HTTPS, enabling direct integration with web applications, mobile apps, and cloud services without middleware.
API Paradigm
HL7 v2 is event-driven (send ADT^A01 when patient admits). FHIR is resource-oriented with RESTful CRUD operations. This makes FHIR more flexible for modern use cases like patient apps, data analytics, and real-time dashboards.
Extensibility
HL7 v2 uses Z-segments for custom data. FHIR uses Extensions with canonical URLs, Profiles for implementation-specific constraints, and Implementation Guides for standardized extensions. This provides better governance and discoverability.
Security
HL7 v2 relies on transport-level security (TLS) with no standard authentication. FHIR integrates OAuth2 and SMART on FHIR for granular, scope-based authorization, enabling secure third-party app integration.
Why FHIR Won
FHIR succeeded where HL7 v3 struggled by prioritizing implementability over theoretical perfection. FHIR's REST/JSON approach leverages existing web development skills, has a gentler learning curve, and enables innovative use cases like patient-facing apps and real-time data exchange.
FHIR in the Australian Context
In Australia, FHIR implementation is guided by the Australian Digital Health Agency (ADHA) and HL7 Australia through the Sparked FHIR Accelerator program. Understanding the Australian healthcare context is essential for local FHIR implementations.
Australian Digital Health Agency (ADHA)
ADHA is the cornerstone of Australia's digital health transformation, responsible for managing My Health Record and driving national interoperability initiatives.
- Operate and secure the My Health Record system
- Implement the Sharing by Default initiative
- Lead the National Healthcare Interoperability Plan
- Partner with Sparked FHIR Accelerator program
- Develop digital health standards and frameworks
Sparked FHIR Accelerator
Launched in August 2023, Sparked is Australia's first FHIR Accelerator, led by CSIRO's Australian eHealth Research Centre in partnership with ADHA, DHDA, and HL7 Australia.
2027 Interoperability Target
The Australian Government has set 2027 as a target year for widespread adoption of national FHIR standards and interoperable health information exchange.
Australian Core Data for Interoperability (AUCDI)
AUCDI defines standardised data groups and elements that form a common language for systems to exchange semantically accurate health data. AU Core is the FHIR Implementation Guide that implements AUCDI requirements.
Australian Healthcare Identifiers
Australia uses a national Healthcare Identifiers (HI) Service to uniquely identify individuals, healthcare providers, and organisations:
Australian healthcare identifier types
| Identifier | Name | Format | Scope |
|---|---|---|---|
| IHI | Individual Healthcare Identifier | 16 digits (e.g., 8003608000327161) | All individuals enrolled in Australian healthcare |
| HPI-I | Healthcare Provider Identifier – Individual | 16 digits (e.g., 8003619900015717) | Individual healthcare providers (doctors, nurses, etc.) |
| HPI-O | Healthcare Provider Identifier – Organisation | 16 digits (e.g., 8003621566789012) | Healthcare organisations (clinics, hospitals, labs) |
| Medicare Number | Medicare Card Number | 10 digits + position number | Australian Medicare beneficiaries |
| DVA Number | Department of Veterans' Affairs Number | Letter + 6-8 digits + check digit | Australian veterans and dependents |
AU Base Patient Profile Example
Australian Patient resources include specific extensions for Indigenous status and use Australian healthcare identifiers:
AU Base Patient Resource with IHI
Structured JSON example rendered with depth controls for easier inspection.
Click on an annotation to highlight it in the JSON
HI Service Integration
Australian FHIR implementations must integrate with the HI Service to validate Healthcare Identifiers (IHI, HPI-I, HPI-O) before including them in FHIR resources.
HL7 Australia FHIR Implementation Guides
Official Australian FHIR profiles and IGs
View HL7 Australia IGsSparked FHIR Accelerator
Australian FHIR Community Process and governance model behind Sparked standards work.
View Sparked ProcessNational Digital Health Strategy
ADHA strategy page describing national digital health priorities relevant to FHIR adoption in Australia.
View StrategyHL7 v2 → FHIR Migration Patterns
Migrating from HL7 v2 to FHIR is a significant undertaking that requires careful planning, risk mitigation, and a phased approach. Most organizations adopt a hybrid architecture during transition, maintaining HL7 v2 interfaces while gradually building FHIR capabilities.
FHIR Façade Pattern
The FHIR Façade pattern provides a FHIR REST API front-end that translates requests to legacy HL7 v2 backend systems. This enables FHIR consumers to access data without requiring immediate backend modernization.
- Front-end: FHIR REST API (API Gateway + Lambda)
- Translation layer: Converts FHIR resources to HL7 v2 messages
- Backend: Existing HL7 v2 interface engine (Mirth, Rhapsody, etc.)
- Cache: Optional FHIR resource cache (DynamoDB) for performance
- Benefits: Zero backend changes, rapid FHIR enablement
FHIR Façade architecture pattern
Loading diagram...
Hybrid Architecture (Coexistence)
Hybrid architecture enables HL7 v2 and FHIR systems to coexist during migration, allowing gradual transition without disrupting existing integrations.
- Maintain existing HL7 v2 interfaces for legacy consumers
- Deploy FHIR APIs for new applications and partners
- Implement bi-directional sync between HL7 v2 and FHIR stores
- Use event-driven architecture for real-time updates
- Plan for eventual HL7 v2 decommissioning
Staged Migration Approach (4 Phases)
Four-phase HL7 v2 to FHIR migration roadmap
| Phase | Description | Duration | Risk Level |
|---|---|---|---|
| Phase 1: FHIR Façade (Read-Only) | Deploy FHIR API that reads from HL7 v2 backend. No write operations. | 2-4 months | Low (no backend changes) |
| Phase 2: Write Operations Enabled | Add FHIR POST/PUT/PATCH with translation to HL7 v2. Implement validation. | 3-6 months | Medium (write path testing required) |
| Phase 3: Bi-Directional Sync | Implement event-driven sync between HL7 v2 and native FHIR store. | 4-8 months | Medium-High (data consistency critical) |
| Phase 4: FHIR Native + HL7 v2 Retirement | Migrate all consumers to FHIR. Decommission HL7 v2 interfaces. | 6-12 months | High (full cutover planning required) |
Four-phase migration roadmap
Loading diagram...
Risk Mitigation Strategies
- Parallel Operations: Run HL7 v2 and FHIR systems concurrently during migration
- Data Validation: Implement continuous validation between HL7 v2 and FHIR data stores
- Rollback Plan: Maintain ability to revert to HL7 v2-only if issues arise
- Consumer Testing: Engage all interface consumers early in testing cycle
- Monitoring: Deploy comprehensive monitoring for data consistency and API performance
- Phased Rollout: Migrate consumers in batches, not all at once
- Backup Strategy: Ensure robust backup and recovery for both systems
Critical Success Factors
Migration success depends on: executive sponsorship, dedicated migration team, comprehensive testing, consumer engagement, and realistic timelines. Budget 12-24 months for full migration depending on interface complexity.
AWS Services for Migration
- AWS HealthLake: Managed FHIR R4 store with HL7 v2 transformation
- AWS B2B Data Interchange: Managed EDI/HL7 translation service
- AWS Lambda: Serverless FHIR façade translation logic
- Amazon API Gateway: FHIR REST API front-end
- Amazon DynamoDB: FHIR resource caching layer
- AWS Migration Hub: Track migration progress across services
FHIR Facade Architecture Pattern
Specific architecture explanation of a facade layer that exposes legacy systems through FHIR APIs.
Facade ArchitectureSummary & Key Takeaways
FHIR represents a paradigm shift in healthcare interoperability, combining the clinical rigor of HL7 standards with modern web technologies that developers already know and love.
Core Concepts Recap
- RESTful APIs: Standard HTTP methods (GET, POST, PUT, DELETE, PATCH) for all operations
- Resources: Modular data structures (Patient, Observation, Encounter, etc.) as building blocks
- Bundles: Package multiple resources for transactions, search results, and document exchange
- JSON/XML: Modern, developer-friendly data formats with JSON as the primary choice
- Security: OAuth2 and SMART on FHIR for granular, standards-based authorization
FHIR Advantages Over HL7 v2/v3
- Developer-friendly: REST/JSON patterns familiar to web developers
- Granular access: Read/write individual resources instead of entire messages
- Rich search: URL-based query parameters for flexible data retrieval
- Extensibility: Extensions, profiles, and implementation guides for customization
- Ecosystem: Growing library of tools, SDKs, and reference implementations
- Regulatory support: Mandated by 21st Century Cures Act, USCDI, and TEFCA
Australian Implementation Considerations
- Align with AUCDI data requirements
- Conform to AU Core Implementation Guide profiles
- Integrate with HI Service for identifier validation
- Support Indigenous status and Australian address formats
- Plan for My Health Record integration and Sharing by Default
Next Steps
After mastering FHIR fundamentals, explore SMART on FHIR for authentication/authorization, FHIR Bulk Data for analytics, and implementation guides like AU Core for production deployments in Australia.
Knowledge Check
Test your understanding with this quiz. You need to answer all questions correctly to mark this section as complete.