fhirpath

name

fhirpath

description

Expert guidance for writing FHIRPath expressions - a path-based navigation and extraction language for FHIR data. Use this skill when writing FHIRPath expressions, navigating FHIR resource trees, filtering collections, performing date/time arithmetic, using FHIRPath functions, writing FHIR invariants, or understanding FHIRPath operators. Trigger keywords include "FHIRPath", "fhirpath", "path expression", "FHIR navigation", "where()", "select()", "exists()", "ofType()", "resolve()", "FHIR invariant", "collection filtering", "FHIRPath function".

FHIRPath

FHIRPath is a path-based navigation and extraction language for hierarchical data models, used extensively in FHIR and CQL. All operations return collections.

Path Navigation

Patient.name.given              // Navigate to given names
Patient.name[0].given           // First name's given (0-based indexing)
Patient.name.first().given      // Equivalent using first()
Observation.value.ofType(Quantity).unit  // Filter by type then navigate

Prefix with type name to restrict context: Patient.name.given only works on Patient resources.

Literals

Type	Examples
Boolean	true, false
Integer	42, -5
Decimal	3.14159
String	'hello', 'urn:oid:1.2.3' (single quotes, use \' to escape)
Date	@2024-01-15, @2024-01, @2024 (partial dates allowed)
DateTime	@2024-01-15T14:30:00Z, @2024-01-15T14:30:00+10:00, @2024T
Time	@T14:30:00, @T14:30
Quantity	10 'mg', 4 days, 100 '[degF]' (UCUM units in quotes)

Collections

• All values are collections (even single items)
• Empty collection: { }
• Collections are ordered, non-unique, 0-indexed
• Empty propagates through most operations

Key Functions

Existence

name.exists()                           // true if any names
name.exists(use = 'official')           // true if any official names
name.all(given.exists())                // true if all names have given
telecom.where(system='phone').empty()   // true if no phone telecoms
name.count()                            // number of names

Filtering and Projection

name.where(use = 'official')                    // Filter by criteria
entry.select(resource as Patient)               // Project/transform
name.select(given.first() + ' ' + family)       // Combine fields
telecom.distinct()                              // Remove duplicates
item.repeat(item)                               // Recursive traversal (unique)
expansion.repeat(contains)                      // Navigate tree structures

Subsetting

name[0]           // First item (0-based)
name.first()      // First item
name.last()       // Last item
name.tail()       // All but first
name.skip(2)      // Skip first 2
name.take(3)      // Take first 3
name.single()     // Error if not exactly one

Combining

name.given | name.family     // Union (removes duplicates)
a.union(b)                   // Same as |
a.combine(b)                 // Merge without removing duplicates
a.intersect(b)               // Items in both
a.exclude(b)                 // Items in a but not b

Type Operations

value is Quantity                    // Type check (returns Boolean)
value as Quantity                    // Cast (empty if wrong type)
entry.resource.ofType(Patient)       // Filter collection by type

String Functions

'hello'.length()                     // 5
'hello'.substring(1, 3)              // 'ell'
'hello'.startsWith('he')             // true
'hello'.endsWith('lo')               // true
'hello'.contains('ell')              // true (different from contains operator)
'hello'.indexOf('l')                 // 2
'HELLO'.lower()                      // 'hello'
'hello'.upper()                      // 'HELLO'
'a-b-c'.replace('-', '_')            // 'a_b_c'
'abc'.matches('[a-z]+')              // true (partial match)
'abc'.matchesFull('[a-z]+')          // true (full match)
'a,b,c'.split(',')                   // {'a', 'b', 'c'}
('a' | 'b' | 'c').join(',')          // 'a,b,c'
'  hello  '.trim()                   // 'hello'

Math Functions (STU)

(-5).abs()              // 5
1.5.ceiling()           // 2
1.5.floor()             // 1
1.5.round()             // 2
1.5.truncate()          // 1
2.power(3)              // 8.0
9.sqrt()                // 3.0
2.718.ln()              // ~1.0
100.log(10)             // 2.0
0.exp()                 // 1.0

Conversion

'42'.toInteger()              // 42
42.toString()                 // '42'
'3.14'.toDecimal()            // 3.14
'true'.toBoolean()            // true (also 't', 'yes', 'y', '1')
'2024-01-15'.toDate()         // @2024-01-15
'10:30:00'.toTime()           // @T10:30:00
'5 mg'.toQuantity()           // 5 'mg'
value.convertsToInteger()     // true if conversion would succeed

Date/Time Component Extraction (STU)

@2024-03-15.yearOf()                          // 2024
@2024-03-15.monthOf()                         // 3
@2024-03-15.dayOf()                           // 15
@2024-03-15T10:30:45.123.hourOf()             // 10
@2024-03-15T10:30:45.123.minuteOf()           // 30
@2024-03-15T10:30:45.123.secondOf()           // 45
@2024-03-15T10:30:45.123.millisecondOf()      // 123
@2024-03-15T10:30:00+10:00.timezoneOffsetOf() // 10.0
@2024-03-15T10:30:00.dateOf()                 // @2024-03-15
@2024-03-15T10:30:00.timeOf()                 // @T10:30:00

Utility

now()                                 // Current DateTime
today()                               // Current Date
timeOfDay()                           // Current Time
iif(condition, true-result, else)     // Conditional (short-circuit)
coalesce(a, b, c)                     // First non-empty (STU)
trace('label', projection)            // Debug logging
defineVariable('name', expr)          // Define variable for later use (STU)

Aggregates (STU)

(1 | 2 | 3).sum()                     // 6
(1 | 2 | 3).min()                     // 1
(1 | 2 | 3).max()                     // 3
(1 | 2 | 3).avg()                     // 2.0
values.aggregate($this + $total, 0)   // Custom aggregation

Operators

Equality

a = b       // Equal (empty if either empty)
a ~ b       // Equivalent (false if precisions differ, case-insensitive for strings)
a != b      // Not equal
a !~ b      // Not equivalent

Comparison

a > b       // Greater than
a < b       // Less than
a >= b      // Greater or equal
a <= b      // Less or equal

Comparison with different date/time precisions returns empty: @2024-01 > @2024-01-15 → { }

Boolean

a and b     // Three-valued AND
a or b      // Three-valued OR
a xor b     // Exclusive OR
a implies b // Implication
not()       // Negation (function, not operator)

Three-valued logic: true and { } → { }, false and { } → false

Math

5 + 3       // Addition (also string concatenation)
5 - 3       // Subtraction
5 * 3       // Multiplication
5 / 3       // Division (always Decimal)
5 div 3     // Integer division
5 mod 3     // Modulo
'a' & 'b'   // String concat (empty → empty string)

Collections

item in collection       // Membership
collection contains item // Containership (converse of in)
a | b                    // Union

Precedence (high to low)

1. . (path), [] (indexer)
2. Unary +, -
3. *, /, div, mod
4. +, -, &
5. is, as
6. |
7. >, <, >=, <=
8. =, ~, !=, !~
9. in, contains
10. and
11. xor, or
12. implies

Date/Time Arithmetic

Add/subtract time-valued quantities from dates/times:

@2024-01-15 + 1 month       // @2024-02-15
@2024-01-31 + 1 month       // @2024-02-29 (last day of month)
@2024-03-15 - 10 days       // @2024-03-05
now() - 1 year              // One year ago

Calendar duration keywords: year(s), month(s), week(s), day(s), hour(s), minute(s), second(s), millisecond(s)

UCUM definite durations ('a', 'mo', 'd') are NOT equivalent for arithmetic above seconds.

Environment Variables

%ucum        // UCUM URL (http://unitsofmeasure.org)
%context     // Original evaluation context
%`custom`    // Custom variables (backtick-delimited)

Singleton Evaluation

When a function expects a single item but receives a collection:

• Single item → use it
• Single item convertible to Boolean → use as Boolean
• Empty → return empty
• Multiple items → ERROR

Common Patterns

Safe navigation with existence checks

name.where(use = 'official').exists() implies name.where(use = 'official').given.exists()

Conditional logic

iif(gender = 'male', 'M', iif(gender = 'female', 'F', 'U'))

Fallback values

coalesce(name.where(use='official'), name.where(use='usual'), name.first())

Reference resolution (FHIR-specific)

subject.resolve().ofType(Patient).birthDate
generalPractitioner.all(resolve() is Practitioner)

Working with CodeableConcept

code.coding.where(system = 'http://snomed.info/sct').code
code.coding.exists(system = 'http://loinc.org' and code = '12345-6')

Recursive navigation

Questionnaire.repeat(item)            // All nested items
ValueSet.expansion.repeat(contains)   // All expansion concepts

Type-safe polymorphic access

Observation.value.ofType(Quantity).value > 100
(Observation.value as Quantity).value > 100

FHIR Invariants

FHIRPath is used to define constraints in FHIR profiles:

// Name must have family or given
name.family.exists() or name.given.exists()

// If dosage exists, it must have timing or asNeeded
dosage.exists() implies (dosage.timing.exists() or dosage.asNeeded.exists())

// All references must be resolvable as Practitioner
performer.all(resolve() is Practitioner)

Pitfalls

1. Multiple items in singleton context: Patient.name.given + ' ' + Patient.name.family fails if multiple names
2. Equality with empty: { } = { } returns { }, not true
3. Date precision: @2024 = @2024-01 returns { } (unknown)
4. String contains vs collection contains: .contains('x') is string function; contains x is operator
5. Case sensitivity: FHIRPath keywords are case-sensitive; type names depend on model
6. Indexing: Collections are 0-based (first element is [0])