Custom Search Parameters

Configure Aidbox

To begin using custom search parameters, enable the FHIR Schema validator engine in Aidbox.

Setup Aidbox with FHIR Schema validation engine

Create a custom search parameter via FHIR API

Let's define a custom search parameter that allows searching Patient resources by a specific extension and its value.

Request

POST /fhir/SearchParameter
Content-Type: text/yaml
Accept: text/yaml

resourceType: SearchParameter
id: patient-occupation
url: http://example.org/fhir/SearchParameter/patient-occupation
version:  '1.0.0'
name: occupation
status: active
description: Search patients by occupation
code: occupation
base:
- Patient
type: string
expression: Patient.extension.where(url='http://example.org/fhir/StructureDefinition/occupation').value.as(string)

Response

Status: 200
description: Search patients by occupation
expression: Patient.extension.where(url='http://example.org/fhir/StructureDefinition/occupation').value.as(string)
name: occupation
type: string
resourceType: SearchParameter
status: active
id: patient-occupation
url: http://example.org/fhir/SearchParameter/patient-occupation
code: occupation
base: 
- Patient
version: 1.0.0

Test Search Parameter:

Create Patient resource with required extension:

POST /fhir/Patient
content-type: text/yaml
accept: text/yaml

resourceType: Patient
id: example-patient
extension:
- url: http://example.org/fhir/StructureDefinition/occupation
  valueString: Engineer
name:
- family: Doe
  given:
  - John
gender: male
birthDate: '1980-01-01'

Search for Patient by occupation:

GET /fhir/Patient?occupation=Engineer

Response:

Status: 200
resourceType: Bundle
type: searchset
meta:
  versionId: '0'
total: 1
link:
  - relation: first
    url: https://example.aidbox.app/fhir/Patient?occupation=Engineer&page=1
  - relation: self
    url: https://example.aidbox.app/fhir/Patient?occupation=Engineer&page=1
entry:
  - resource:
      name:
        - given:
            - John
          family: Doe
      gender: male
      birthDate: '1980-01-01'
      extension:
        - url: http://example.org/fhir/StructureDefinition/occupation
          valueString: Engineer
      id: >-
        example-patient
      resourceType: Patient
      meta:
        lastUpdated: '2024-06-07T10:21:29.110510Z'
        versionId: '6'
        extension:
          - url: https://fhir.aidbox.app/fhir/StructureDefinition/created-at
            valueInstant: '2024-06-07T10:21:29.110510Z'
    search:
      mode: match
    fullUrl: https://example.aidbox.app/Patient/example-patient
    link:
      - relation: self
        url: https://example.aidbox.app/Patient/example-patient

SearchParamter resource structure

This table contains properties required by the FHIR specification and properties that Aidbox interprets.

PropertyFHIR datatypeDescription

url

uri

Search parameter unique canonical url

version

string

Search parameter version

name

string

Search parameter name, used to perform actual search queries

status

code

draft | active | retired | unknown

description

markdown

Natural language description of the search parameter

code

code

Recommended name for parameter in search url (Aidbox ignores it, and use .name instead)

base

code[]

The resource type(s) this search parameter applies to

type

code

number | date | string | token | reference | composite | quantity | uri | special

expression

string

FHIRPath expression that extracts the values

component

BackboneElement

For Composite resources to define the parts

Last updated