FHIR CI-Build

This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions icon

5.6 Resource SearchParameter - Content

FHIR Infrastructure icon Work GroupMaturity Level: 5 Trial UseSecurity Category: Anonymous Compartments: No defined compartments

A search parameter that defines a named search item that can be used to search/filter on a resource.

5.6.1 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)
  • how the search parameter is to be understood by the server
  • where in the source resource the parameter matches

5.6.2 Boundaries and Relationships

5.6.3 Background and Context

Implementers should be familiar with the background and concepts described in Search on the RESTful API before working with this resource.

There is a registry of all Search Parameters.

5.6.4 References to this Resource

5.6.5 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SearchParameter TU DomainResource Search parameter for a resource
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Rule: If an expression is present, there SHALL be a processingMode
+ Rule: Search parameters can only have chain names when the search parameter type is 'reference'
+ Rule: Search parameters comparator can only be used on type 'number', 'date', 'quantity' or 'special'.

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
... url ΣC 1..1 uri Canonical identifier for this search parameter, represented as a URI (globally unique)
+ Warning: URL should not contain | or # - these characters make processing canonical references problematic
... identifier Σ 0..* Identifier Additional identifier for the search parameter (business identifier)

... version Σ 0..1 string Business version of the search parameter
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: Version Algorithm (Extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this search parameter (computer friendly)
... title ΣT 0..1 string Name for this search parameter (human friendly)
... derivedFrom 0..1 canonical(SearchParameter) Original definition for the search parameter
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (Required)
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher ΣT 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher

... description ΣT 1..1 markdown Natural language description of the search parameter
... useContext Σ 0..* UsageContext The context that the content is intended to support

... jurisdiction ΣXD 0..* CodeableConcept Intended jurisdiction for search parameter (if applicable)
Binding: Jurisdiction ValueSet (Extensible)

... purpose T 0..1 markdown Why this search parameter is defined
... copyright T 0..1 markdown Use and/or publishing restrictions
... copyrightLabel T 0..1 string Copyright holder and year(s)
... code Σ 1..1 code Recommended name for parameter in search url
... base Σ 1..* code The resource type(s) this search parameter applies to
Binding: Version Independent Resource Types (All) (Required)
Additional BindingsPurpose
All Resource Types UI Binding


... type ΣC 1..1 code number | date | string | token | reference | composite | quantity | uri | special
Binding: SearchParamType (Required)
... expression C 0..1 string FHIRPath expression that extracts the values
... processingMode C 0..1 code normal | phonetic | other
Binding: Search Processing Mode Type (Required)
... constraint 0..1 string FHIRPath expression that constraints the usage of this SearchParamete
... target 0..* code Types of resource (if a resource reference)
Binding: Version Independent Resource Types (All) (Required)
Additional BindingsPurpose
All Resource Types UI Binding


... multipleOr 0..1 boolean Allow multiple values per parameter (or)
... multipleAnd 0..1 boolean Allow multiple parameters (and)
... comparator C 0..* code eq | ne | gt | lt | ge | le | sa | eb | ap
Binding: Search Comparator (Required)

... modifier 0..* code missing | exact | contains | not | text | in | not-in | below | above | type | identifier | of-type | code-text | text-advanced | iterate
Binding: Search Modifier Code (Required)

... chain C 0..* string Chained names supported

... component 0..* BackboneElement For Composite resources to define the parts

.... definition 1..1 canonical(SearchParameter) Defines how the part works
.... expression 1..1 string Subexpression relative to main expression

doco Documentation for this format icon

See the Extensions for this resource

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) , the spreadsheet version & the dependency analysis

5.6.5.1 Terminology Bindings

Path ValueSet Type Documentation
SearchParameter.versionAlgorithm[x] VersionAlgorithm Extensible

Indicates the mechanism used to compare versions to determine which is more current.
SearchParameter.status PublicationStatus Required

The lifecycle status of an artifact.
SearchParameter.jurisdiction JurisdictionValueSet Extensible

This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used.

Note: The codes for countries and country subdivisions are taken from ISO 3166 icon while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) icon.
SearchParameter.base VersionIndependentResourceTypesAll Required

Current and past FHIR resource types (deleted or renamed), including abstract types
  All Resource Types ui
SearchParameter.type SearchParamType Required

Data types allowed to be used for search parameters.
SearchParameter.processingMode SearchProcessingModeType Required

How a search parameter relates to the set of elements returned by evaluating its expression query.
SearchParameter.target VersionIndependentResourceTypesAll Required

Current and past FHIR resource types (deleted or renamed), including abstract types
  All Resource Types ui
SearchParameter.comparator SearchComparator Required

What Search Comparator Codes are supported in search.
SearchParameter.modifier SearchModifierCode Required

A supported modifier for a search parameter.

5.6.5.2 Constraints

UniqueKeyLevelLocationDescriptionExpression
img cnl-0Warning (base)Name should be usable as an identifier for the module by machine processing applications such as code generationname.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
img spd-1Rule (base)If an expression is present, there SHALL be a processingModeexpression.empty() or processingMode.exists()
img cnl-1Warning SearchParameter.urlURL should not contain | or # - these characters make processing canonical references problematicexists() implies matches('^[^|# ]+$')
img spd-2Rule (base)Search parameters can only have chain names when the search parameter type is 'reference'chain.empty() or type = 'reference'
img spd-3Rule (base)Search parameters comparator can only be used on type 'number', 'date', 'quantity' or 'special'.comparator.empty() or (type in ('number' | 'date' | 'quantity' | 'special'))

5.6.6 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

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

5.6.7 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name Type Description Expression In Common
base token The resource type(s) this search parameter applies to SearchParameter.base
code token Code used in URL SearchParameter.code
component reference Defines how the part works SearchParameter.component.definition
(SearchParameter)
context token A use context assigned to the search parameter (SearchParameter.useContext.value.ofType(CodeableConcept)) 30 Resources
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)) 30 Resources
context-type token A type of use context assigned to the search parameter SearchParameter.useContext.code 30 Resources
context-type-quantity composite A use context type and quantity- or range-based value assigned to the search parameter On SearchParameter.useContext:
  context-type: code
  context-quantity: value.ofType(Quantity) | value.ofType(Range)		 30 Resources
context-type-value composite A use context type and value assigned to the search parameter On SearchParameter.useContext:
  context-type: code
  context: value.ofType(CodeableConcept)		 30 Resources
date date The search parameter publication date SearchParameter.date 31 Resources
derived-from reference Original definition for the search parameter SearchParameter.derivedFrom
(SearchParameter)
description string The description of the search parameter SearchParameter.description 29 Resources
identifier N token External identifier for the search parameter SearchParameter.identifier 35 Resources
jurisdiction token Intended jurisdiction for the search parameter SearchParameter.jurisdiction 27 Resources
name string Computationally friendly name of the search parameter SearchParameter.name 28 Resources
publisher string Name of the publisher of the search parameter SearchParameter.publisher 31 Resources
status token The current status of the search parameter SearchParameter.status 35 Resources
target token Types of resource (if a resource reference) SearchParameter.target
type token number | date | string | token | reference | composite | quantity | uri | special SearchParameter.type
url uri The uri that identifies the search parameter SearchParameter.url 34 Resources
version token The business version of the search parameter SearchParameter.version 32 Resources