FHIRPath Function: duration

{:.stu}

Returns the number of whole calendar periods at the specified precision between the given input value and the value argument. If the input value is after the value argument, the result is negative. The result of this operation is always an integer; any fractional periods are dropped. {:.stu}

For input and value types of date values, the precision argument must be one of: year, month, week, or day. {:.stu}

For input and value types of datetime values, the precision argument must be one of: year, month, week, day, hour, minute, second, or millisecond. {:.stu}

For input and value types of time values, the precision argument must be one of: hour, minute, second, or millisecond. {:.stu}

If the input value or value argument are of less precision than the specified precision, the result is empty. {:.stu}

When computing the duration between DateTime values with different timezone offsets, implementations should normalize the timezone when a precision of hour, minute, second, or millisecond is requested. {:.stu}

If either the input or value argument is empty, the result is empty. {:.stu}

The following examples illustrate the behavior of the duration function: {:.stu}

@2025-01-02.duration(@2025-01-07, 'week') // 0 - hasn't passed 7 days duration
@2025-01-01.duration(@2025-09-01, 'year') // 0 - baby is 9 months old
@2024-12-01.duration(@2025-09-01, 'year') // 0 - baby is 10 months old

{:.stu}

Summary

• Category: Date and Time Interval Functions
• Section: 5.11.1
• Return Type: Integer
• Empty Input Result: empty
• Errors on Multiple Input: true

Description

Returns the number of whole calendar periods at the specified precision between the given input value and the value argument. If the input value is after the value argument, the result is negative. The result of this operation is always an integer; any fractional periods are dropped.

Arguments

• value: Date | DateTime | Time - The value to compare with the input
• precision: identifier - The precision for the duration calculation

Type Mapping

• n/a

Example

@2025-01-02.duration(@2025-01-07, 'week') // 0 - hasn't passed 7 days duration
@2025-01-01.duration(@2025-09-01, 'year') // 0 - baby is 9 months old
@2024-12-01.duration(@2025-09-01, 'year') // 0 - baby is 10 months old