FHIRPath Profile Validation: Real-World Examples

Discover how FHIRPath simplifies the task for business analysts by eliminating the need for hard-coded validations, learn when to opt for FHIRPath over other validation types, and enrich your knowledge with practical FHIRPath expression examples. This is a must-read for anyone learning more about working with FHIR.

What is FHIRPath?

FHIRPath is a path-based language, similar to XPath, that allows you to navigate a FHIR resource. It powers evaluation and data extraction from its fields to add business validations to profiles on a FHIR server.
In this article, we’ll take a look at the different types of functions you can perform to validate resources with FHIRPath. To bring you more value, we’ve decided to examine the functions not extensively covered by the official FHIR specification. We’ve also added real-life FHIRPath examples we’ve used in the development of distinct national medical systems. You’ll be able to learn about different FHIRPath use cases and examine various FHIRPath expression examples.

Importance of FHIRPath in Profile Validation

FHIRPath plays a critical role in validating FHIR profiles by providing a standardized way to enforce constraints and business logic across FHIR resources. Unlike other validation methods, FHIRPath enables developers to express complex validation rules that handle relationships between resource elements, conditional constraints, and collections.

FHIRPath is highly expressive, allowing for the creation of more sophisticated and accurate validation rules compared to traditional XML or JSON schema validations. Moreover, FHIRPath offers flexibility by supporting all FHIR resource types and is designed to work across platforms, making it adaptable for different implementations. It is efficient at querying and navigating complex, nested structures within FHIR resources, making validation both effective and scalable.

How to add FHIRPath validations

You can create resource validations through different functions, which are added to constraints. This makes writing validations significantly easier for business analysts, as they don’t have to be hard-coded. 

There are certain cases when it’s better to use FHIRPath than other types of validations, and vice versa. (Read more about different types of FHIR validations.)

For example, when there are a lot of different validations needed on different fields, it’s better to use slicing. However, when you need to perform only one single validation on different fields, it’s better to use FHIRPath.

To create a validation with FHIRPath, a constraint could be added either on the resource level or on the field level. Depending on the level, the validation will check and work with more or fewer fields in the resource. When dealing with collections of resources, such as a FHIR bundle, it’s crucial to ensure that each resource within the bundle adheres to the specified constraints.

Below is an example of an added constraint:

"resourceType": "StructureDefinition",
…
"constraint": [
   {
      "key": "123",
      "severity": "error",
      "human": "Only encounter which exists in the bundle should be referenced in Composition",
      "expression": "entry.resource.where(is(Encounter)).id = entry.resource.where(is(Composition)).encounter.reference.replace('Encounter/','')",
      "source": "http://hl7.org/fhir/StructureDefinition/Bundle"
   }
]

FHIRPath functions for resource validation

1. Function iif: add if-then-else validation to a profile

Use case: 

We use this function when we want to add if-then-else validation to a profile. 

Validation rule:

Human: “Only a medication request with MY_profile is accepted.”

FHIRPath Expression:

"iif(entry.resource.where(is(MedicationRequest)).exists(), entry.resource.where(is(MedicationRequest)).meta.select(profile)='http://example.com/fhir/StructureDefinition/My_profile', entry.resource.where(is(MedicationRequest)).exists().not())"

Current validation is done for the MedicationRequest resource type.

Validation: The iif operation has three parts, divided by a comma (,). If the first part is true, then we check that the second part is also true. If the second part is false, then we check that the third part is true.
Example: Below, we validate the resource MedicationRequest against the StructureDefinition that contains the iif expression in the constraint. The example is valid because the profile for resource MedicationRequest is http://example.com/fhir/StructureDefinition/my_bundle. The example would also be valid if there were zero MedicationRequest resources in the bundle.

{
   "resourceType": "Bundle",
   "id": "bundle_id",
   "type": "transaction",
   "meta": {
       "profile": [
           "http://example.com/fhir/StructureDefinition/my_bundle"
       ]
   },
   "timestamp": "2022-08-02T06:00:00+00:00",
   "entry": [
       {
           "resource": {
               "resourceType": "MedicationRequest",
               "id": "example_medreq",
               "meta": {
                   "profile": [
                       "http://example.com/fhir/StructureDefinition/MY_profile"
                   ]
               },
               "status": "active",
               "intent": "plan",
               "encounter": {
                   "reference": "Encounter/encounter_id"
               },
               "medicationReference": {
                   "reference": "Medication/medication_id"
               },
               "subject": {
                   "reference": "Patient/patient_id"
               }
           },
           "request": {
               "method": "POST",
               "url": "MedicationRequest"
           }
       }
   ]
}

Another use of the iif function is to set a validation for a period of time. 

Validation rule:

Human: “If onset[x] period.end is provided, it should be less than or equal to the current date.”

FHIRPath Expression:

"iif(onset is Period and onset.end.exists(), onset.end.toDate() <= today(), onset is Period.not() or onset.end.exists().not())"

Current validation is done for the AllergyIntolerance resource type.

Validation: The below examples are for the AllergyIntolerance resource. Here, if onset is present and is period, then we check that period.end is in the past. If it is in the past, then the function returns true. If onset does not exist or period.end does not exist, then the validation will also return true.

Both examples below are valid, because period.end is either later than today or does not exist.

Example 1: The example is true because onsetPeriod.end is less than today.

{
   "resourceType": "AllergyIntolerance",
   "id": "nkla",
   "meta": {
       "profile": [
           "http://example.com/fhir/StructureDefinition/my_profile"
       ]
   },
   "clinicalStatus": {
     "coding": [
       {
         "display": "Active"
       }
     ]
   },
   "onsetPeriod": {
       "start": "2022-08-02",
       "end": "2022-08-02"
   },
   "encounter": {
       "reference": "http://example.com/Encounter/example"
   },
   "code": {
     "coding": [
       {
         "display": "No Known Latex Allergy (situation)"
       }
     ]
   },
   "patient": {
     "reference": "http://example.com/Patient/example"
   },
   "recordedDate": "2022-08-02T15:37:31-06:00",
   "recorder": {
     "reference": "http://example.com/Practitioner/example"
   }
 }

Example 2:The second example is also valid because we do not have onsetPeriod at all.

{
 "resourceType": "AllergyIntolerance",
 "id": "nkla",
 "meta": {
     "profile": [
         "http://example.com/fhir/StructureDefinition/my_profile"
     ]
 },
 "clinicalStatus": {
   "coding": [
     {
       "display": "Active"
     }
   ]
 },
 "encounter": {
     "reference": "http://example.com/Encounter/example"
 },
 "code": {
   "coding": [
     {
       "display": "No Known Latex Allergy (situation)"
     }
   ]
 },
 "patient": {
   "reference": "http://example.com/Patient/example"
 },
 "recordedDate": "2022-08-02T15:37:31-06:00",
 "recorder": {
   "reference": "http://example.com/Practitioner/example"
 }
}

2. Function select(), where(): return a concrete field in the resource and validate it according to something

Use case

We use this validation when we need to return a concrete field in the resource and validate it according to something. 

Validation rule:

Human: “Meta profile Medication is not consistent with  http://example.com/fhir/StructureDefinition/my_profile.

Current validation is done for the Bundle resource type.

Expression:

"entry.resource.where(is(Medication)).meta.select(profile)='http://example.com/fhir/StructureDefinition/my_profile'"

Validation: With this function we validate that there should be resource Medication with profile http://example.com/fhir/StructureDefinition/my_profile in the Bundle. (This validation could also be done with slicing-type profiles. Read more about slicing and how it works.)

As you can see, this validation does the same as the validation above (iif), so it validates if a profile is “my profile.” So, we can see that the FHIRPath language is very flexible. The difference between these validations is that here the field with the profile is mandatory; with iif the field is optional.

Example:

{
   "resourceType": "Bundle",
   "id": "bundle_id",
   "type": "transaction",
   "meta": {
       "profile": [
           "http://example.com/fhir/StructureDefinition/my_bundle"
       ]
   },
   "timestamp": "2022-08-02T06:00:00+00:00",
   "entry": [
       {
           "resource": {
               "resourceType": "Medication",
               "id": "example_med",
               "meta": {
                   "profile": [
                       "http://example.com/fhir/StructureDefinition/my_profile"
                   ]
               },
               "status": "active",
               "code": {
                   "coding": [
                       {
                           "system": "http://hl7.org/fhir/sid/ndc",
                           "code": "0409-6531-02",
                           "display": "Vancomycin Hydrochloride (VANCOMYCIN HYDROCHLORIDE)"
                       }
                   ]
               },
               "ingredient": [
                   {
                       "itemCodeableConcept": {
                           "coding": [
                               {
                                   "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                                   "code": "66955",
                                   "display": "Vancomycin Hydrochloride"
                               }
                           ]
                       },
                       "isActive": true,
                       "strength": {
                           "numerator": {
                               "value": 500,
                               "system": "http://unitsofmeasure.org",
                               "code": "mg"
                           },
                           "denominator": {
                               "value": 10,
                               "system": "http://unitsofmeasure.org",
                               "code": "mL"
                           }
                       }
                   }
               ]
           },
           "request": {
               "method": "POST",
               "url": "Medication"
           }
       }
   ]
}

3. Function replace(): change any field in the resource or replace anything with an empty string

Use Case:

We use this validation when we need to change any field in the resource. We could also replace anything with an empty string.

Current validation is done for the Medication resource type.

Validation rule

Human: “The only encounter that exists in the bundle should be referenced in Composition.”

FHIRPath Expression:

 "entry.resource.where(is(Medication)).id = entry.resource.where(is(MedicationRequest)).medicationReference.reference.replace('Medication/','')"

Validation: Here we say that the id of the resource should be the same as the string after Medication/ in Bundle.entry.resource.medicationReference.reference. Literally, we remove Medication/ and check that id in the resource Medication is the same as id in Bundle.entry.resource.medicationReference.reference without Medication/.

Example:

{
   "resourceType": "Bundle",
   "id": "bundle_id",
   "type": "transaction",
   "meta": {
       "profile": [
           "http://example.com/fhir/StructureDefinition/my_bundle"
       ]
   },
   "timestamp": "2022-08-02T06:00:00+00:00",
   "entry": [
       {
           "resource": {
               "resourceType": "MedicationRequest",
               "id": "example_medreq",
               "meta": {
                   "profile": [
                       "http://example.com/fhir/StructureDefinition/MY_profile"
                   ]
               },
               "status": "active",
               "intent": "plan",
               "encounter": {
                   "reference": "Encounter/encounter_id"
               },
               "medicationReference": {
                   "reference": "Medication/medication_id"
               },
               "subject": {
                   "reference": "Patient/patient_id"
               }
           },
           "request": {
               "method": "POST",
               "url": "MedicationRequest"
           }
       },
       {
           "resource": {
               "resourceType": "Medication",
               "id": "medication_id",
               "meta": {
                   "profile": [
                       "http://example.com/fhir/StructureDefinition/my_profile"
                   ]
               },
               "status": "active",
               "code": {
                   "coding": [
                       {
                           "system": "http://hl7.org/fhir/sid/ndc",
                           "code": "0409-6531-02",
                           "display": "Vancomycin Hydrochloride (VANCOMYCIN HYDROCHLORIDE)"
                       }
                   ]
               }
           },
           "request": {
               "method": "POST",
               "url": "Medication"
           }
       }
   ]
}

4. Function: Regex in FHIRPath: validate the data a user could send to us

Use case:

We use this FHIRPath validation when we want to validate the data a user could send to us.

Validation rule:

Human: “Email must be valid.”

FHIRPath Expression:

"system != 'email' or value.matches('^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$')"

If we want to validate a phone number instead:

Validation rule:

Human: “Phone must be valid.”

One more expression with regex for the same example:

 "system != 'phone' or value.matches('^\\+\\d{7,15}$')"

Current validation is done for the Patient resource type.

In this example, we validate that the email is a real address that could exist. The same example would apply if we wanted to validate a phone number or another type of data a user sends to the server.

   {
       "resourceType": "Patient",
       "meta": {
           "profile": [
               "http://example.com/fhir/StructureDefinition/my_patient_prifile"
           ]
       },
       "active": true,
       "telecom": [
           {
               "system": "phone",
               "value": "+1234567890",
               "use": "mobile"
           },
           {
               "system": "email",
               "value": "[email protected]"
           }
       ],
       "gender": "male",
       "birthDate": "1993-10-02"
   }

Conclusion

We hope our practical FHIRPath validation examples will help you gain a better understanding of how to use FHIRPath to add validations. This guide is part of a series of articles aimed at making FHIR implementation more straightforward. 

Our team of business analysts and FHIR engineers is always open for consultations. Contact us about your project, and we’ll ensure that your FHIR adoption goes smoothly.

Post author

Sveta Vedmed

Business Analyst at Edenlab

More article about Featured

Let`s chat

We would be glad to share more details about our enterprise-level FHIR software solutions and other cases based on the HL7 FHIR standard.

    Your form has been submitted successfully

    We will contact your shortly

    Kodjin White Paper

    Please leave your email to get Kodjin White Paper

      By downloading files from this site you agree to the Policy

      The Kodjin White Paper has been successfully sent to your email

      We have sent a copy to your email

      Back to website content