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

YAML

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)

JSON

POST /fhir/SearchParameter
Content-Type: application/json
Accept: application/json

{
  "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:

YAML

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'

JSON

POST /fhir/Patient
content-type: application/json
accept: application/json

{
    "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.

Property	FHIR datatype	Description
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