---
type: "fhirpath-function"
title: "FHIRPath Function: difference"
function: "difference"
category: "Date and Time Interval Functions"
section: "5.11.2"
source: "fhirpath/functions.json"
---
# FHIRPath Function: difference
{:.stu}

Returns the number of boundaries crossed for the specified `precision` between the input value and the `value` arguments. If the input value is after the `value` argument, the result is negative. The result of this operation is always an integer; any fractional boundaries 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}

For calculations involving weeks, Sunday is considered to be the first day of the week for the purposes of determining the number of boundaries crossed.
{:.stu}

When computing the difference 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 difference function:
{:.stu}

```fhirpath
@2025-01-02.difference(@2025-01-07, 'week') // 1 - crossed a week boundary (Sunday)
@2025-01-01.difference(@2025-09-01, 'year') // 0 - baby is 9 months old, but born this year
@2024-12-01.difference(@2025-09-01, 'year') // 1 - baby is 10 months old, but born last year
```
{:.stu}
## Summary
- **Category**: Date and Time Interval Functions
- **Section**: `5.11.2`
- **Return Type**: `Integer`
- **Empty Input Result**: `empty`
- **Errors on Multiple Input**: `true`
## Description
Returns the number of boundaries crossed for the specified precision between the input value and the value arguments. If the input value is after the value argument, the result is negative. The result of this operation is always an integer; any fractional boundaries are dropped.
## Arguments
- `value`: `Date | DateTime | Time` - The value to compare with the input
- `precision`: `identifier` - The precision for the difference calculation
## Type Mapping
- n/a
## Example
```fhirpath
@2025-01-02.difference(@2025-01-07, 'week') // 1 - crossed a week boundary (Sunday)
@2025-01-01.difference(@2025-09-01, 'year') // 0 - baby is 9 months old, but born this year
@2024-12-01.difference(@2025-09-01, 'year') // 1 - baby is 10 months old, but born last year
```