---
type: "resource"
title: "SearchParameter"
resource: "SearchParameter"
---
# SearchParameter
## Introduction
## Scope and Usage
A `SearchParameter` resource specifies a search parameter that may be used on the RESTful API to search or filter on a resource. The SearchParameter resource declares:
- how to typically refer to the search parameter from a client ([SearchParameter.code](searchparameter-definitions#SearchParameter.code))
- how the search parameter is to be understood by the server
- where in the source resource the parameter matches
## Boundaries and Relationships
- Search Parameters are referred to by [CapabilityStatement](capabilitystatement) resources via the canonical URL for a search parameter ([CapabilityStatement.rest.resource.searchParam.definition](capabilitystatement-definitions#CapabilityStatement.rest.resource.searchParam.definition))
- Search Parameters can appear in an [Implementation Guide](implementationguide) to specify how resources can be found
## Background and Context
Implementers should be familiar with the background and concepts described in [Search](search) on the RESTful API before working with this resource.
There is a [registry of all Search Parameters](searchparameter-registry).
## Notes
## Naming Conventions for Search Parameters
HL7-defined search parameters follow these naming conventions:
- Use lowercase letters with hyphens for multi-word parameters (kebab-case)
- Prefer shorter, more common terms when possible
- Be consistent across resources when the same concept is searched (e.g., `authored` for authoring dates)
- Avoid abbreviations unless widely understood
- Use singular forms unless the concept is inherently plural
- Use of a prefix underscore character (`_`) compliant with the rules of the [Style Guide](http#styleguide)
## Notes
- If the extension's context specifies multiple resources, they are represented with multiple elements in the `SearchParameter.base` array
- An expression like `Resource.descendents.extension('extension-url').value` is possible, but this is a low performance option for a server to evaluate, and search parameter expressions are performance sensitive
## Use of FHIRPath in Expressions
- An expression like `Resource.descendents().extension('extension-url').value` is possible, but this is a low performance option for a server to evaluate, and search parameter expressions are performance sensitive
- While SearchParameter.expression allows for the full use of FHIRPath, including resolve() in a search parameter definition makes it difficult to support for transactional servers. For that reason, this specification does not define parameters that link across resource instance boundaries.
This specification does use search parameters with resolve() to narrow types (e.g., Observation.subject.resolve() is Patient). We recommend that other specifications follow the same practice - chaining is the mechanism defined to search across resource boundaries.
> Balloter feedback requested: We are seeking input on approaches to managing the balance between expressiveness and performance impact on servers from the use of various FHIRPath features in search parameter expressions.
## SearchParameters on Extensions
The SearchParameter resource may be used to define searches on extensions. A simple definition defines the code, the base resource the extension can be found in, and a type, and an expression. Assume that the extension is `http://example.org/fhir/StructureDefinition/extension-thumb-length` which has a value that is a quantity, and that is used on patient, then an appropriate SearchParameter would be:
"code" : "thumb-length",
"base" : \["Patient"\],
"type" : "quantity",
"expression" : "Patient.extension('http://example.org/fhir/StructureDefinition/extension-thumb-length').value"
Servers MAY attempt to process expressions that just select the extension without the `.value`, but this is not required and may be discouraged or deprecated in the future.
Extensions may have multiple types with different search behaviors, so the type can be specifically selected:
"code" : "thumb-length-code",
"base" : \["Patient"\],
"type" : "token",
"expression" : "Patient.extension('http://example.org/fhir/StructureDefinition/extension-thumb-length').value.ofType(CodeableConcept)"
This example would select coded thumb lengths and index them only for the `thumb-length-code` search parameter. When an extension can have multiple types with incompatible search behavior, the search parameters have to do this. Note that is type casting the extension directly (e.g. `Patient.extension('...').ofType(CodeableConcept)`) will lead to an empty index, since the extension is not a CodeableConcept itself.
When extensions can be used in multiple places, these places are enumerated in the expression:
Patient.extension('http://example.org/fhir/StructureDefinition/extension-thumb-length').value
| Patient.contact.extension('http://example.org/fhir/StructureDefinition/extension-thumb-length').value
| Practitioner.extension('http://example.org/fhir/StructureDefinition/extension-thumb-length').value
#### Search Parameter Aliases
To support evolution toward consistent naming conventions while maintaining backward compatibility, `SearchParameter` resources MAY define one or more `aliasCode` values. These aliases represent suggested alternative codes that can be used to reference the search parameter in addition to the primary `code` value.
**Usage Guidelines:**
- Aliases should be used primarily for backward compatibility when standardizing parameter names
- Servers that declare support for a SearchParameter SHOULD accept all defined aliases in addition to the primary code
- New implementations SHOULD use the primary code rather than aliases
- Aliases are displayed in the SearchParameter registry and resource search parameter tables
**Example:** A search parameter previously named `authoredon` might be updated to use `authored` as the primary code (for consistency with other resources) while retaining `authoredon` as an alias for backward compatibility.
## Deriving Search Parameters
When one SearchParameter has a `derivedFrom` referencing another SearchParameter, the following rules SHOULD be followed. Note that these rules are asserted as SHOULD rather than SHALL only because they were introduced after the resource became normative. Systems that fail to follow these rules are likely to result in unsafe interoperability.
A derived SearchParameter:
- SHOULD have the same `experimental` as the original SearchParameter
- SHOULD have the same `type` as the original SearchParameter
- SHOULD have the same `processingMode` as the original SearchParameter
- SHOULD NOT have values for `multipleOr` or `multipleAnd` that contradict a value stated in the original SearchParameter. I.e. If the base does not declare these, the derived SearchParameter can. However, if the base does declare them, the derived SearchParameter SHOULD have the same values.
- SHOULD have a `target` that is equivalent to or a subset of the original SearchParameter `target`
- SHOULD have `comparator` and `modifier` values that are the same as or a superset of those defined in the base.
- SHOULD have the same number of components listed in the same order, where the `definition` must be the same or a derived SearchParameter, and the `expression` must be the same.
- MAY add values for `chain` but SHOULD NOT remove or re-order values already listed in the base.
> Request for ballot feedback: We would like the 'SHOULD' assertions above to become 'SHALL' assertions. We are invoking our usual implementer outreach process to find out whether anyone else objects, but please file tickets for any rules you do not believe can be enforced that way.
## StructureDefinition
### Elements (Simplified)
- **[SearchParameter](/searchparameter-definitions#SearchParameter)** [0..*]: - Search parameter for a resource
- **[SearchParameter.url](/searchparameter-definitions#SearchParameter.url)** [1..1]: [uri](/uri) Canonical identifier for this search parameter, represented as a URI (globally unique)
- **[SearchParameter.identifier](/searchparameter-definitions#SearchParameter.identifier)** [0..*]: [Identifier](/Identifier) Additional identifier for the search parameter (business identifier)
- **[SearchParameter.version](/searchparameter-definitions#SearchParameter.version)** [0..1]: [string](/string) Business version of the search parameter
- **[SearchParameter.versionAlgorithm[x]](/searchparameter-definitions#SearchParameter.versionAlgorithm%5Bx%5D)** [0..1]: [string](/string), [Coding](/Coding) extensible:[version-algorithm](/valueset-version-algorithm) How to compare versions
- **[SearchParameter.name](/searchparameter-definitions#SearchParameter.name)** [1..1]: [string](/string) Name for this search parameter (computer friendly)
- **[SearchParameter.title](/searchparameter-definitions#SearchParameter.title)** [0..1]: [string](/string) Name for this search parameter (human friendly)
- **[SearchParameter.derivedFrom](/searchparameter-definitions#SearchParameter.derivedFrom)** [0..1]: [canonical](/canonical) Original definition for the search parameter
- **[SearchParameter.status](/searchparameter-definitions#SearchParameter.status)** [1..1]: [code](/code) required:[publication-status](/valueset-publication-status) draft | active | retired | unknown
- **[SearchParameter.experimental](/searchparameter-definitions#SearchParameter.experimental)** [0..1]: [boolean](/boolean) For testing only - never for real usage
- **[SearchParameter.date](/searchparameter-definitions#SearchParameter.date)** [0..1]: [dateTime](/dateTime) Date last changed
- **[SearchParameter.publisher](/searchparameter-definitions#SearchParameter.publisher)** [0..1]: [string](/string) Name of the publisher/steward (organization or individual)
- **[SearchParameter.contact](/searchparameter-definitions#SearchParameter.contact)** [0..*]: [ContactDetail](/ContactDetail) Contact details for the publisher
- **[SearchParameter.description](/searchparameter-definitions#SearchParameter.description)** [1..1]: [markdown](/markdown) Natural language description of the search parameter
- **[SearchParameter.useContext](/searchparameter-definitions#SearchParameter.useContext)** [0..*]: [UsageContext](/UsageContext) The context that the content is intended to support
- **[SearchParameter.jurisdiction](/searchparameter-definitions#SearchParameter.jurisdiction)** [0..*]: [CodeableConcept](/CodeableConcept) extensible:[jurisdiction](/valueset-jurisdiction) Jurisdiction of the authority that maintains the search parameter (if applicable)
- **[SearchParameter.purpose](/searchparameter-definitions#SearchParameter.purpose)** [0..1]: [markdown](/markdown) Why this search parameter is defined
- **[SearchParameter.copyright](/searchparameter-definitions#SearchParameter.copyright)** [0..1]: [markdown](/markdown) Notice about intellectual property ownership, can include restrictions on use
- **[SearchParameter.copyrightLabel](/searchparameter-definitions#SearchParameter.copyrightLabel)** [0..1]: [string](/string) Copyright holder and year(s)
- **[SearchParameter.code](/searchparameter-definitions#SearchParameter.code)** [1..1]: [code](/code) Recommended name for parameter in search url
- **[SearchParameter.aliasCode](/searchparameter-definitions#SearchParameter.aliasCode)** [0..*]: [code](/code) Additional recommended names for parameter in search url
- **[SearchParameter.base](/searchparameter-definitions#SearchParameter.base)** [1..*]: [code](/code) required:[version-independent-all-resource-types](/valueset-version-independent-all-resource-types) The resource type(s) this search parameter applies to
- **[SearchParameter.type](/searchparameter-definitions#SearchParameter.type)** [1..1]: [code](/code) required:[search-param-type](/valueset-search-param-type) number | date | string | token | reference | composite | quantity | uri | special | resource
- **[SearchParameter.expression](/searchparameter-definitions#SearchParameter.expression)** [0..1]: [string](/string) FHIRPath expression that extracts the values
- **[SearchParameter.processingMode](/searchparameter-definitions#SearchParameter.processingMode)** [0..1]: [code](/code) required:[search-processingmode](/valueset-search-processingmode) normal | phonetic | other
- **[SearchParameter.constraint](/searchparameter-definitions#SearchParameter.constraint)** [0..1]: [string](/string) FHIRPath expression that constraints the usage of this SearchParameter
- **[SearchParameter.target](/searchparameter-definitions#SearchParameter.target)** [0..*]: [code](/code) required:[version-independent-all-resource-types](/valueset-version-independent-all-resource-types) Types of resource (if a resource reference)
- **[SearchParameter.multipleOr](/searchparameter-definitions#SearchParameter.multipleOr)** [0..1]: [boolean](/boolean) Allow multiple values per parameter (or)
- **[SearchParameter.multipleAnd](/searchparameter-definitions#SearchParameter.multipleAnd)** [0..1]: [boolean](/boolean) Allow multiple parameters (and)
- **[SearchParameter.comparator](/searchparameter-definitions#SearchParameter.comparator)** [0..*]: [code](/code) required:[search-comparator](/valueset-search-comparator) eq | ne | gt | lt | ge | le | sa | eb | ap
- **[SearchParameter.modifier](/searchparameter-definitions#SearchParameter.modifier)** [0..*]: [code](/code) required:[search-modifier-all-codes](/valueset-search-modifier-all-codes) missing | exact | contains | not | text | in | not-in | below | above | type | identifier | of-type | code-text | text-advanced | iterate
- **[SearchParameter.chain](/searchparameter-definitions#SearchParameter.chain)** [0..*]: [string](/string) Chained names supported
- **[SearchParameter.component](/searchparameter-definitions#SearchParameter.component)** [0..*]: [BackboneElement](/BackboneElement) For Composite resources to define the parts
- **[SearchParameter.component.definition](/searchparameter-definitions#SearchParameter.component.definition)** [1..1]: [canonical](/canonical) Defines how the part works
- **[SearchParameter.component.expression](/searchparameter-definitions#SearchParameter.component.expression)** [1..1]: [string](/string) Sub-expression relative to main expression
## Mappings
- [SearchParameter Mappings](/searchparameter-mappings) — 13 mapping entries
## Implementation Guide
### implementationguide-SearchParameter-core.xml
```xml
```
## Resource Packs
### list-SearchParameter-packs.xml
```xml
-
```
## Search Parameters
- [base](/searchparameter-search#base) — **token** — The resource type(s) this search parameter applies to — `SearchParameter.base`
- [code](/searchparameter-search#code) — **token** — Code used in URL — `SearchParameter.code`
- [component](/searchparameter-search#component) — **reference** — Defines how the part works — `SearchParameter.component.definition`
- [context](/searchparameter-search#context) — **token** — A use context assigned to the search parameter — `(SearchParameter.useContext.value.ofType(CodeableConcept))`
- [context-quantity](/searchparameter-search#context-quantity) — **quantity** — A quantity- or range-valued use context assigned to the search parameter — `(SearchParameter.useContext.value.ofType(Quantity)) | (SearchParameter.useContext.value.ofType(Range))`
- [context-type](/searchparameter-search#context-type) — **token** — A type of use context assigned to the search parameter — `SearchParameter.useContext.code`
- [context-type-quantity](/searchparameter-search#context-type-quantity) — **composite** — A use context type and quantity- or range-based value assigned to the search parameter — `SearchParameter.useContext`
- [context-type-value](/searchparameter-search#context-type-value) — **composite** — A use context type and value assigned to the search parameter — `SearchParameter.useContext`
- [date](/searchparameter-search#date) — **date** — The search parameter publication date — `SearchParameter.date`
- [derived-from](/searchparameter-search#derived-from) — **reference** — Original definition for the search parameter — `SearchParameter.derivedFrom`
- [description](/searchparameter-search#description) — **string** — The description of the search parameter — `SearchParameter.description`
- [identifier](/searchparameter-search#identifier) — **token** — External identifier for the search parameter — `SearchParameter.identifier`
- [identifier](/searchparameter-search#identifier) — **token** — External identifier for the search parameter — `SearchParameter.identifier`
- [jurisdiction](/searchparameter-search#jurisdiction) — **token** — Jurisdiction of the authority that maintains the the search parameter — `SearchParameter.jurisdiction`
- [name](/searchparameter-search#name) — **string** — Computationally friendly name of the search parameter — `SearchParameter.name`
- [publisher](/searchparameter-search#publisher) — **string** — Name of the publisher of the search parameter — `SearchParameter.publisher`
- [status](/searchparameter-search#status) — **token** — The current status of the search parameter — `SearchParameter.status`
- [target](/searchparameter-search#target) — **token** — Types of resource (if a resource reference) — `SearchParameter.target`
- [type](/searchparameter-search#type) — **token** — number | date | string | token | reference | composite | quantity | uri | special — `SearchParameter.type`
- [url](/searchparameter-search#url) — **uri** — The uri that identifies the search parameter — `SearchParameter.url`
- [version](/searchparameter-search#version) — **token** — The business version of the search parameter — `SearchParameter.version`
- [experimental](/searchparameter-search#experimental) — **token** — Whether the SearchParameter is experimental — `SearchParameter.experimental`
[Full Search Parameters](/searchparameter-search)
## Examples
- [example](/searchparameter-example-example) — searchparameter-example — General example
- [example-constraint](/searchparameter-example-example-constraint) — searchparameter-example-constraint — Search parameter for constraint example
- [example-extension](/searchparameter-example-example-extension) — searchparameter-example-extension — Search parameter for an extension example
- [example-reference](/searchparameter-example-example-reference) — searchparameter-example-reference — Search parameter for a reference example
- [filter](/searchparameter-example-filter) — searchparameter-filter — Formal Definition for _filter parameter
- [searchparameter-example](/searchparameter-example-searchparameter-example) — searchparameter-example
- [searchparameter-example-constraint](/searchparameter-example-searchparameter-example-constraint) — searchparameter-example-constraint
- [searchparameter-example-extension](/searchparameter-example-searchparameter-example-extension) — searchparameter-example-extension
- [searchparameter-example-reference](/searchparameter-example-searchparameter-example-reference) — searchparameter-example-reference
- [searchparameter-examples-header](/searchparameter-example-searchparameter-examples-header) — searchparameter-examples-header
[Full Examples](/searchparameter-examples)
## Mapping Exceptions
### searchparameter-fivews-mapping-exceptions.xml
### Unmapped Elements
- **FiveWs.what** — Not relevant for this resource
- **FiveWs.author** — Not relevant for this resource
- **FiveWs.actor** — Not relevant for this resource
- **FiveWs.cause** — Not relevant for this resource
- **FiveWs.where** — Not relevant for this resource
- **FiveWs.context** — Not relevant for this resource
- **FiveWs.init** — Not relevant for this resource
- **FiveWs.source** — Not relevant for this resource
- **FiveWs.who** — Not relevant for this resource
- **FiveWs.grade** — Not relevant for this resource
- **FiveWs.planned** — Not relevant for this resource
- **FiveWs.done** — Not relevant for this resource
- **FiveWs.subject** — Not relevant for this resource