--- description: Migrate Aidbox SearchParameters to standard FHIR SearchParameters for FHIRSchema validation engine compatibility. --- # Migrate from Aidbox SearchParameter to FHIR SearchParameter If you want to use the [FHIRSchema validation engine](../../../modules/profiling-and-validation/fhir-schema-validator/README.md), your custom Aidbox SearchParameters defined via Zen or Entities will not be available. Aidbox with FHIRSchema validation enabled is more aligned with the FHIR specification and only supports FHIR SearchParameters. In this case, use this migration guide. {% hint style="info" %} If you are using Zen project to define your SearchParameter resources, you can also follow this guide, but you will need to remove the SearchParameter definitions from your Zen project. {% endhint %} To migrate Aidbox SearchParameter you need to redefine it as regular [FHIR SearchParameters](https://hl7.org/fhir/R5/searchparameter.html) using REST API: ```json POST /fhir/SearchParameter content-type: application/json accept: application/json ``` To define FHIR SearchParameter you should know the meaning of some basic FHIR SearchParameter properties, required fields marked as \*:

Property	Description	Additional Notes
`base` *	The resource type(s) this search parameter applies to.	In Aidbox SearchParameter it was `reference` to Entity in `resource` property.
`url` *	Canonical identifier for this search parameter, represented as a URI (globally unique).	Didn't exists in Aidbox SearchParameter.
`expression` *	FHIRPath expression that extracts the values.	You need to manually convert Adibox `SearchParameter.expression` to F HIRPath expression.
`name` *	Computationally friendly name of the search parameter.	The same as in Adibox `SearchParameter.name`.
`status` *	`draft \| active \| retired \| unknown`. Binding to publication-status ValueSet.	Didn't exist in Aidbox SearchParameter. Use `active` status.
`type` *	`number \| date \| string \| token \| reference \| composite \| quantity \| uri \| special`. Binding to search-param-type ValueSet.	Transfer this value as it was in Adbox `SearchParameter.type`.

## Simple case Let's migrate custom Aidbox SearchParameter `Patient.city`: ```json GET /SearchParameter/Patient.city { "name": "city", "type": "token", "resource": { "id": "Patient", "resourceType": "Entity" }, "expression": [ [ "address", "city" ] ] } ``` ### Migration steps First step is to replace resource property to base property with target resource type: #### Aidbox target resource type ```json "resource": { "id": "Patient", "resourceType": "Entity" } ``` #### FHIR target resource type ```json "base": ["Patient"] ``` Than you need to rewrite expression property to FHIRPath format. Usually it may be transformed by joining vector elements with each other separated by `.` symbol and joining resource type in front of this construction like this: #### Aidbox expression ```json "expression": [ [ "address", "city" ] ] ``` #### FHIR expression ```json "expression": "Patient.address.city" ``` The final step is to add the missing `status` and `url` fields required by the FHIR SearchParameter specification. For the `status` property in the aidbox, you usually just set it to `active`. #### FHIR status and url ```json "status": "active" "url": "http://example.org/fhir/SearchParameter/patient-city" ``` Here is the migration request for `Patient.city` SearchParameter:

PUT /fhir/SearchParameter/patient-city
content-type: application/json
accept: application/json

{
  "resourceType": "SearchParameter",
  "name": "city",
  "url": "http://example.org/fhir/SearchParameter/patient-city",
  "status": "active",
  "description": "Search by city",
  "code": "city",
  "base": ["Patient"],
  "type": "token",
  "expression": "Patient.address.city"
}

## Complex expression cases For more complex cases, there is a need for more complex expression mapping. Here is a few examples: #### Aidbox expression with `or` If expression contains multiple arrays, it means `or` statement between multiple expressions: ```json "expression": [ ["address", "city"], ["address", "line"] ] ``` #### FHIR expression with `or` This is what it looks like in the FHIRPath format: ```json "expression": "Patient.address.city or Patient.address.line" ``` #### Aidbox expression with `where` When expression contains object, it means `where` statement. In this case it would extract records with element `telecom` which contains field `system` with value `email`: ```json "expression": [ ["telecom", {"system": "email"}] ] ``` #### FHIR expression with `where` This is what it looks like in the FHIRPath format: ```json "Patient.telecom.where(system = 'email')" ```