On this page:

4.6FHIRPath Expressions

 

Paths are defined using FHIRPath, which is an expression language defined by FHIR. In its simplest form, this can take the form of a single dotted path:

Patient.name.given

In the example above, the FHIRPath expression matches all of the patient's given names. If this path is used as the expression in a Custom Search Parameter, any values for the patient's given name(s) will be indexed by the search parameter.

Paths can also perform more advanced lookups. This page outlines expressions to satisfy various common needs, and includes example SearchParameters that use them.

4.6.1Testing FHIRPath Expressions

 

When developing a FHIRPath expresion, the _fhirpath parameter can be helpful. This parameter can be added to any FHIR REST URL where the response will be a resource or a Bundle resource containing a collection of resources (e.g. a FHIR Read or a FHIR Search). When it is present in the request URL, the parameter value will be parsed as a FHIRPath expression and then applied against the response resource.

For example, suppose you have a FHIR repository containing the following resource:

{
   "resourceType": "Patient",
   "id": "123",
   "extension": [{
     "url": "http://acme.com/eye-color",
      "valueCode":"hazel"
   }]
}

the following URL will fetch a resource with ID Patient/123 and then apply a FHIRPath expression against it. You can use this to test whether your expression returns the desired value from the resource in question. http://localhost:8000/Patient/123?_fhirpath=Patient.extension('http://acme.com/eye-color').value.as(code)

This will produce a result like the following if the expression is correct:

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "result",
    "part": [ {
      "name": "expression",
      "valueString": "Patient.extension('http://acme.com/eye-color').value.as(code)"
    }, {
      "name": "result",
      "valueCode": "hazel"
    } ]
  } ]
}

4.6.2Expression: Extension With Reference Value

 

This example indexes the value on a custom extension that is added to a resource. Note that the extension does not need to be declared anywhere (aside from in the SearchParameter resource) in order for this example to work.

Expression:

Patient.extension('http://acme.com/doctor').value.as(Reference)

Example resource that would be indexed by this expression:

{
  "resourceType": "Patient",
  "extension": [{
    "url": "http://acme.com/doctor",
    "valueReference": {
      "reference": "Practitioner/A"
    }
  }]
}

Example SearchParameter resource using this expression:

{
  "resourceType": "SearchParameter",
  "status": "active",
  "name": "doctor", 
  "url": "http://acme.com/doctor-search-parameter", 
  "code": "doctor",
  "base": [ "Patient" ],
  "type": "reference",
  "expression": "Patient.extension('http://acme.com/doctor').value.as(Reference)"
}

Example search URL using this parameter: http://localhost:8000/Patient?doctor=Practitioner/A

4.6.3Expression: Contained Resource

 

The following example indexes on a field that is found within a contained resource inside the resource that is being indexed.

Expression:

Observation.specimen.resolve().receivedTime

Example resource that would be indexed by this expression:

{
  "resourceType": "Observation",
  "id": "O1",
  "contained": [
    {
      "resourceType": "Specimen",
      "id": "FOO",
      "receivedTime": "2011-01-01"
    }
  ],
  "status": "final",
  "specimen": {
    "reference": "#FOO"
  }
}

Example SearchParameter resource using this expression:

{
  "resourceType": "SearchParameter",
  "status": "active",
  "name": "specimen-received", 
  "url": "http://acme.com/specimen-received-search-parameter", 
  "code": "specimen-received",
  "base": [ "Observation" ],
  "type": "date",
  "expression": "Observation.specimen.resolve().receivedTime"
}

Example search URL using this parameter: http://localhost:8000/Observation?specimen-received=2011-01-01

4.6.4Expression: Bundle (FHIR Message) Entry Resource

 

When storing Bundles directly (i.e. by POST-ing them to the /Bundle endpoint as opposed to processing them as FHIR transactions), this path can be used to index on a value within an individual resource found within the Bundle.

Expression:

Bundle.entry.resource.as(MessageHeader).id

Example resource that would be indexed by this expression:

{
  "resourceType": "Bundle",
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "id": "123"
      }
    }
  ]
}

Example SearchParameter resource using this expression:

{
  "resourceType": "SearchParameter",
  "status": "active",
  "name": "message-header-id", 
  "url": "http://acme.com/message-header-id-search-parameter", 
  "code": "message-header-id",
  "base": [ "Bundle" ],
  "type": "token",
  "expression": "Bundle.entry.resource.as(MessageHeader).id"
}

Example search URL using this parameter: http://localhost:8000/Bundle?message-header-id=123

4.6.5Expression: Bundle (FHIR Document) Entry Resource

 

This example shows a FHIR Document (a bundle with a Bundle.type of document where the first entry continas a Composition resource) with a custom search parameter indexing a field within the Composition. This example allows clients to search for documents with a given encounter reference.

Expression:

Bundle.entry[0].resource.as(Composition).encounter

Example resource that would be indexed by this expression:

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    {
      "resource": {
        "resourceType": "Composition",
        "encounter": {
          "reference": "Encounter/2"
        }
      }
    }
  ]
}

Example SearchParameter resource using this expression:

{
  "resourceType": "SearchParameter",
  "status": "active",
  "name": "document-encounter", 
  "url": "http://acme.com/document-encounter-search-parameter", 
  "code": "document-encounter",
  "base": [ "Bundle" ],
  "type": "reference",
  "expression": "Bundle.entry[0].resource.as(Composition).encounter"
}

Example search URL using this parameter: http://localhost:8000/Bundle?document-encounter=Encounter/2

4.6.6Expression: Multiple Paths

 

This example indexes multiple paths, meaning it can be used to provide one search parameter that will look for a value in multiple places within a resource.

Expression:

DiagnosticReport.performer | DiagnosticReport.resultsInterpreter

Example resource that would be indexed by this expression:

{
  "resourceType": "DiagnosticReport",
  "resultsInterpreter": {
    "reference": "Practitioner/A"
  }
}

Example SearchParameter resource using this expression:

{
  "resourceType": "SearchParameter",
  "status": "active",
  "name": "performer-or-interpreter", 
  "url": "http://acme.com/performer-or-interpreter-search-parameter", 
  "code": "performer-or-interpreter",
  "base": [ "DiagnosticReport" ],
  "type": "reference",
  "expression": "DiagnosticReport.performer | DiagnosticReport.resultsInterpreter"
}

Example search URL using this parameter: http://localhost:8000/DiagnosticReport?performer-or-interpreter=Practitioner/A