FHIRPath

FHIRPath uses a dot-notation syntax to traverse nested FHIR resources and elements, similar to XPath for XML documents.

• Navigate complex hierarchies: Patient.name.given
• Access list indices: Patient.name[0].family
• Use wildcards: Bundle.entry.resource.*
• Filter with predicates: Observation.component.where(code.coding.code = '8480-6')

This enables precise extraction of specific clinical data points from deeply nested FHIR structures without custom parsing code.

FHIRPath includes a comprehensive set of built-in functions for data manipulation and evaluation.

• String operations: startsWith(), contains(), replace(), substring()
• Aggregation: count(), sum(), avg(), min(), max()
• Logical operators: exists(), allTrue(), anyTrue(), all()
• Type conversion: toString(), toInteger(), toDecimal(), toBoolean()
• Date/time math: today(), now(), yearsBetween(), monthsBetween()

Example: Observation.valueQuantity.value > 140 evaluates a blood pressure threshold.

FHIRPath extends standard expression languages with healthcare-specific operators designed for clinical data types.

• as operator: Safe type casting, e.g., Observation.value as Quantity
• is operator: Type checking, e.g., Observation.value is CodeableConcept
• ~ equivalence: Compares coded concepts semantically, not just string equality
• $this keyword: References the current context node in nested expressions
• Extension access: Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').value

These operators handle the nuances of medical terminologies and FHIR's polymorphic data types.

FHIRPath is the primary language for defining constraints in FHIR profiles and implementation guides using the constraint element.

• Define co-occurrence rules: name.given.exists() or name.family.exists()
• Enforce value ranges: value >= 0 and value <= 100
• Validate cross-field logic: onsetDateTime.empty() or onsetAge.empty()
• Check terminology bindings: code.memberOf('http://hl7.org/fhir/ValueSet/observation-codes')

These invariants are evaluated by the FHIR Validator to ensure resource conformance against profiles like US Core.

FHIRPath expressions execute against a dynamic evaluation context that includes the focus resource, root resource, and environment variables.

• %context: Access the current focus node being evaluated
• %resource: Reference the root resource containing the focus
• %rootResource: Access the top-level resource in a Bundle
• %ucum: Access UCUM unit conversion services
• %terminologies: Access terminology service for code validation

This context model enables expressions that navigate both downward into nested elements and upward to parent structures, critical for complex clinical rules.

FHIRPath serves as the expression language for CDS Hooks card rules and prefetch templates, enabling dynamic clinical decision support.

• Define trigger conditions: Patient.birthDate < today() - 65 years
• Construct prefetch queries: Observation?patient={{context.patientId}}&code=4548-4
• Evaluate response cards: MedicationRequest.status = 'active'
• Link to SMART on FHIR apps for interactive decision support

This integration allows EHR systems to invoke context-aware clinical guidance at specific points in the clinician workflow.