What is FHIR

FHIR (Fast Healthcare Interoperability Resources) is an HL7 standard for exchanging healthcare data electronically. FHIR defines a common format for healthcare information that enables different systems to share patient data, clinical records, and administrative information.

FHIR uses modern web technologies and RESTful APIs to make healthcare data exchange simpler and more consistent than previous HL7 standards.

Quick reference? For a concise definition and overview, see the FHIR glossary entry

Core Concepts

The Healthcare Interoperability Challenge

FHIR’s Solution: A Modern Approach

Who Uses FHIR?

Real-World Impact and Use Cases

FHIR Resources

FHIR organizes healthcare data into modular units called resources. A FHIR resource represents a single healthcare concept—such as a patient, observation, medication, or appointment.

Each FHIR resource has:

A defined structure with specific data elements
A unique identifier (resource ID)
Support for standard formats (JSON, XML)
RESTful API operations (create, read, update, delete)

Common FHIR resources include:

Patient: Demographics and patient identification
Observation: Clinical measurements and lab results
Medication: Drug information and prescriptions
Encounter: Patient visits and episodes of care
Practitioner: Healthcare provider information

Resources, Elements, and Data Types

Resource Structure and Anatomy

Common Data Types

Primitive Types

Complex Types

Elements and Cardinality

FHIR Data Formats

FHIR resources can be represented in multiple formats:

JSON: Most commonly used for modern APIs
XML: Supported for legacy system compatibility
RDF/Turtle: For semantic web applications

FHIR RESTful API

FHIR uses RESTful HTTP operations to interact with resources:

GET: Retrieve a resource or search for resources
POST: Create a new resource
PUT: Update an existing resource
DELETE: Remove a resource

FHIR API endpoints follow a consistent pattern:

[base]/[resourceType]/[id]

RESTful API Basics in FHIR Context

REST Principles Applied to Healthcare

FHIR HTTP Operations

Read

Search

Create

Update

Delete

URL Structure and Patterns

HTTP Status Codes in FHIR

How FHIR Works

Resource References

FHIR resources connect to each other through references. A reference links one FHIR resource to another FHIR resource, creating relationships in the healthcare data model.

Example: An Observation resource references the Patient resource it belongs to:

{
  "resourceType": "Observation",
  "id": "blood-pressure-001",
  "status": "final",
  "subject": {
    "reference": "Patient/example-patient-123",
    "display": "John Doe"
  },
  "effectiveDateTime": "2025-12-26T10:30:00Z",
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "85354-9",
        "display": "Blood pressure panel"
      }
    ]
  },
  "component": [
    {
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "8480-6",
            "display": "Systolic blood pressure"
          }
        ]
      },
      "valueQuantity": {
        "value": 120,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    },
    {
      "code": {
        "coding": [
          {
            "system": "http://loinc.org",
            "code": "8462-4",
            "display": "Diastolic blood pressure"
          }
        ]
      },
      "valueQuantity": {
        "value": 80,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    }
  ]
}

The subject field contains a reference to Patient/example-patient-123, establishing the relationship between the observation and the patient.

Your First FHIR Resource: Patient

The Patient Resource Structure

Required vs Optional Elements

Understanding the JSON Representation

Understanding the XML Representation

Common Patient Patterns

FHIR Profiles

FHIR profiles customize FHIR resources for specific use cases. A FHIR profile constrains or extends a base FHIR resource to meet particular implementation requirements.

FHIR profiles define:

Required vs optional elements
Terminology bindings (code systems)
Extensions for additional data
Cardinality constraints

FHIR Extensions

FHIR extensions add data elements not defined in the base FHIR specification. Extensions allow FHIR implementations to include region-specific, specialty-specific, or organization-specific data while maintaining FHIR compliance.

Example of a Patient resource with a race extension (used in US Core):

{
  "resourceType": "Patient",
  "id": "example",
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2106-3",
            "display": "White"
          }
        },
        {
          "url": "text",
          "valueString": "White"
        }
      ]
    }
  ],
  "name": [
    {
      "family": "Doe",
      "given": ["John"]
    }
  ]
}

FHIR Versions

Version History and Evolution

The current FHIR version is R5 (Release 5). Earlier FHIR versions include R4B, R4, STU3, and DSTU2.

FHIR R4 (Current Standard)

FHIR R4B (Bridge Release)

FHIR R5 (Latest Version)

FHIR R5 introduced:

Improved terminology services
Enhanced search capabilities
Additional resources for specialized domains
Better support for clinical reasoning

FHIR R4 remains the most widely adopted version in production systems.

Which Version Should You Use?

Normative vs Trial Use Content

FHIR vs Other HL7 Standards

FHIR vs HL7 v2

HL7 v2 uses pipe-delimited messages for healthcare data exchange. HL7 v2 has been the healthcare standard since the 1980s but requires complex parsing and lacks standard RESTful APIs.

FHIR provides:

Web-based APIs instead of message formats
JSON/XML instead of pipe-delimited text
Granular resources instead of monolithic messages
Modern tooling and developer experience

FHIR vs HL7 v3 / CDA

HL7 v3 and CDA (Clinical Document Architecture) use XML-based document models. These standards are comprehensive but complex to implement.

FHIR offers:

Simpler data models
Smaller, modular resources instead of large documents
RESTful API access
Easier implementation and testing

Common FHIR Use Cases

Clinical Data Exchange

FHIR enables healthcare providers to share patient information across different electronic health record (EHR) systems. FHIR APIs allow clinics, hospitals, and specialists to access the same patient data.

Patient Access to Health Data

FHIR supports patient-facing applications that retrieve health records through FHIR APIs. Patients can view their medical history, lab results, and medications in third-party apps.

Public Health Reporting

FHIR facilitates standardized reporting of healthcare data to public health agencies. FHIR resources can transmit immunization records, disease surveillance data, and quality metrics.

Research and Analytics

FHIR provides structured healthcare data for clinical research and population health analytics. FHIR resources can be aggregated and analyzed while maintaining data consistency.

FHIR Implementation

FHIR Servers

A FHIR server stores FHIR resources and exposes FHIR RESTful APIs. FHIR servers handle resource persistence, search operations, and validation.

Popular FHIR server implementations:

HAPI FHIR (Java)
Microsoft FHIR Server (.NET)
Google Cloud Healthcare API
IBM FHIR Server

FHIR Clients

A FHIR client consumes FHIR APIs to retrieve or submit healthcare data. FHIR client libraries exist for most programming languages (JavaScript, Python, Java, C#).

FHIR Validation

FHIR validation ensures resources conform to FHIR specifications and profiles. FHIR validators check resource structure, data types, terminology codes, and cardinality rules.

Validation Levels

Structural Validation: Ensures JSON/XML is well-formed and matches the FHIR resource schema
Cardinality Validation: Checks required fields are present and field counts match constraints (e.g., 0..1, 1.., 0..)
Data Type Validation: Verifies values match expected data types (string, integer, dateTime, etc.)
Terminology Validation: Validates codes against specified code systems and value sets
Profile Validation: Confirms resources meet profile-specific constraints and extensions

Validation Tools

HL7 FHIR Validator: Official Java-based validator from HL7
HAPI FHIR Validator: Part of the HAPI FHIR library
Firely .NET SDK Validator: .NET-based validation
Online Validators: Web-based tools for quick validation testing

Example validation error:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "diagnostics": "Patient.name: minimum required = 1, but only found 0",
      "location": ["Patient.name"]
    }
  ]
}

FHIR Search and Querying

FHIR provides powerful search capabilities for finding resources based on various parameters.

Common Search Parameters

All resources support these standard search parameters:

_id: Search by resource ID
_lastUpdated: Search by last modification time
_tag: Search by tagged metadata
_profile: Search by profile conformance

Resource-Specific Search Parameters

Each resource type defines specific search parameters:

# Find patients by name
GET /Patient?name=John

# Find patients by birthdate
GET /Patient?birthdate=1990-01-01

# Find observations for a specific patient
GET /Observation?subject=Patient/123

# Find recent lab results
GET /Observation?patient=123&category=laboratory&date=ge2025-01-01

# Complex search with multiple parameters
GET /Observation?patient=123&code=http://loinc.org|2339-0&_sort=-date&_count=10

Search Modifiers

:exact - Exact string match
:contains - Substring match
:missing - Check if parameter is missing
:not - Negation

# Find patients with names containing "john" (case-insensitive)
GET /Patient?name:contains=john

# Find observations without a performer
GET /Observation?performer:missing=true

Search Result Bundles

FHIR returns search results as a Bundle resource:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 47,
  "link": [
    {
      "relation": "self",
      "url": "https://fhir.example.org/Observation?patient=123"
    },
    {
      "relation": "next",
      "url": "https://fhir.example.org/Observation?patient=123&_page=2"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.example.org/Observation/obs-001",
      "resource": {
        "resourceType": "Observation",
        "id": "obs-001"
        // ... observation data
      }
    }
    // ... more entries
  ]
}

Practical Implementation Patterns

Creating Resources

# Create a new patient
POST https://fhir.example.org/Patient
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "name": [{
    "family": "Doe",
    "given": ["Jane"]
  }],
  "gender": "female",
  "birthDate": "1985-07-15"
}

# Response: 201 Created
Location: https://fhir.example.org/Patient/new-id-456

Updating Resources

# Update existing patient (full replacement)
PUT https://fhir.example.org/Patient/456
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "456",
  "name": [{
    "family": "Doe",
    "given": ["Jane", "Marie"]
  }],
  "gender": "female",
  "birthDate": "1985-07-15",
  "telecom": [{
    "system": "phone",
    "value": "555-1234"
  }]
}

Conditional Operations

# Create patient only if they don't already exist
POST https://fhir.example.org/Patient
If-None-Exist: identifier=http://hospital.org/mrn|12345

# Update patient if conditions match
PUT https://fhir.example.org/Patient?identifier=12345

Batch and Transaction Operations

FHIR supports batch processing of multiple operations:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "request": {
        "method": "POST",
        "url": "Patient"
      },
      "resource": {
        "resourceType": "Patient",
        "name": [{ "family": "Smith", "given": ["John"] }]
      }
    },
    {
      "request": {
        "method": "POST",
        "url": "Observation"
      },
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "subject": {
          "reference": "urn:uuid:patient-temp-id"
        }
      }
    }
  ]
}

Debugging and Troubleshooting

Common Issues

Invalid References: Ensure referenced resources exist
Missing Required Fields: Check profile requirements
Incorrect Data Types: Validate against FHIR data type specifications
Terminology Binding Errors: Use correct code systems and value sets
Profile Violations: Resources must conform to declared profiles

Debugging Tools

Browser DevTools: Inspect network requests and responses
Postman/Insomnia: Test FHIR API endpoints
FHIR Validators: Validate resources before submission
Server Logs: Check FHIR server logs for detailed errors
OperationOutcome Resources: Review error details returned by servers

Common Misconceptions About FHIR

”FHIR is Just Another HL7 Standard"

"FHIR Replaces All Other Standards"

"FHIR is Only for EHRs"

"You Must Implement All Resources"

"FHIR is Too Complex for Small Projects”

Key Terminology

FHIR Resource: A modular unit of healthcare data with a defined structure.

Resource Reference: A link from one FHIR resource to another FHIR resource.

FHIR Profile: A constraint or extension of a base FHIR resource for specific use cases.

FHIR Extension: Additional data elements not in the base FHIR specification.

RESTful API: HTTP-based API using standard operations (GET, POST, PUT, DELETE).

Resource ID: A unique identifier for a specific FHIR resource instance.

Base URL: The root endpoint for a FHIR server’s API (e.g., https://fhir.example.org).

Search Parameters: Query criteria for finding FHIR resources.

Bundle: A container resource that holds a collection of other resources.

OperationOutcome: A resource that provides information about the outcome of an operation or error details.

Cardinality: The allowed number of occurrences for a data element (e.g., 0..1, 1.., 0..).

Value Set: A collection of codes from one or more code systems for use in a specific context.

Best Practices

For Developers

Start with a Profile: Always implement against a specific FHIR profile (e.g., US Core) rather than base FHIR
Validate Early: Integrate validation into your development workflow
Use Libraries: Leverage FHIR client libraries instead of building from scratch
Handle Errors Gracefully: Check OperationOutcome resources for detailed error information
Cache Terminology: Download and cache frequently-used code systems and value sets
Version Awareness: Clearly specify which FHIR version you support (R4, R5, etc.)

For Architects

Choose the Right Profile: Select Implementation Guides that match your region and use case
Plan for Extensions: Design extension strategies for custom data requirements
Consider Performance: Implement pagination for large result sets
Security First: Use SMART on FHIR for authentication and authorization
Monitor Compliance: Regularly validate against profiles to catch drift

For Integration Teams

Map Data Carefully: Document mappings between legacy systems and FHIR resources
Test Across Versions: Ensure compatibility with different FHIR server implementations
Handle References: Implement strategies for resolving and maintaining resource references
Plan for Errors: Design retry logic and error handling for network issues
Document Assumptions: Clearly document which profiles, extensions, and constraints you support

Next Steps

Learning Path Recommendations

Resources for Continued Learning

Practice Environments

Glossary Terms

FHIR - Quick reference definition
HL7 - The standards organization
SMART on FHIR - Authorization framework

Official Resources

Last reviewed: December 26, 2025 FHIR version: R5 (with R4 examples) Content status: Canonical reference

Section: fhir Content Type: definition Audience: technical

Published: 09/04/2022 Modified: 29/12/2025 10 min read

Keywords: FHIR HL7 FHIR healthcare interoperability health data exchange FHIR resources FHIR implementation FHIR server FHIR client

Sources:

HL7 FHIR Specification (Accessed: 26/12/2025)
FHIR R5 Documentation (Accessed: 26/12/2025)