STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

5.7 Resource SearchParameter - Content

FHIR Infrastructure Work GroupMaturity Level: 1Compartments: Not linked to any defined compartments

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

5.7.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 refer to the search parameter from a client
  • how the search parameter is to be understood by the server
  • where in the source resource the parameter matches

5.7.2 Boundaries and Relationships

5.7.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.

5.7.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SearchParameter IDomainResourceSearch Parameter for a resource
If an xpath is present, there SHALL be an xpathUsage
... url Σ1..1uriAbsolute URL used to reference this search parameter
... name Σ1..1stringInformal name for this search parameter
... status ?!Σ0..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimePublication Date(/time)
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy this search parameter is defined
... code Σ1..1codeCode used in URL
... base Σ1..1codeThe resource type this search parameter applies to
ResourceType (Required)
... type Σ1..1codenumber | date | string | token | reference | composite | quantity | uri
SearchParamType (Required)
... description Σ1..1markdownDocumentation for search parameter
... expression I0..1stringFluentPath expression that extracts the values
... xpath I0..1stringXPath that extracts the values
... xpathUsage I0..1codenormal | phonetic | nearby | distance | other
XPathUsageType (Required)
... target 0..*codeTypes of resource (if a resource reference)
ResourceType (Required)
... component 0..*Reference(SearchParameter)For Composite resources to define the parts

doco Documentation for this format

UML Diagram (Legend)

SearchParameter (DomainResource)An absolute URL that is used to identify this search parameter when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this search parameter is (or will be) publishedurl : uri [1..1]A free text natural language name identifying the search parametername : string [1..1]The status of this search parameter definition (this element modifies the meaning of other elements)status : code [0..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »A flag to indicate that this search parameter definition is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The date (and optionally time) when the search parameter definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the search parameter changesdate : dateTime [0..1]The name of the individual or organization that published the search parameterpublisher : string [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of search parametersuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »The Scope and Usage that this search parameter was created to meetrequirements : markdown [0..1]The code used in the URL or the parameter name in a parameters resource for this search parametercode : code [1..1]The base resource type that this search parameter refers tobase : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »The type of value a search parameter refers to, and how the content is interpretedtype : code [1..1] « Data types allowed to be used for search parameters. (Strength=Required)SearchParamType! »A description of the search parameters and how it useddescription : markdown [1..1]A FluentPath expression that returns a set of elements for the search parameterexpression : string [0..1]An XPath expression that returns a set of elements for the search parameterxpath : string [0..1]How the search parameter relates to the set of elements returned by evaluating the xpath queryxpathUsage : code [0..1] « How a search parameter relates to the set of elements returned by evaluating its xpath query. (Strength=Required)XPathUsageType! »Types of resource (if a resource is referenced)target : code [0..*] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »Used to define the parts of a composite search parametercomponent : Reference [0..*] « SearchParameter »ContactThe name of an individual to contact regarding the search parametername : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]Contacts to assist a user in finding and communicating with the publishercontact[0..*]

XML Template

<SearchParameter xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Absolute URL used to reference this search parameter -->
 <name value="[string]"/><!-- 1..1 Informal name for this search parameter -->
 <status value="[code]"/><!-- 0..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Publication Date(/time) -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why this search parameter is defined -->
 <code value="[code]"/><!-- 1..1 Code used in URL -->
 <base value="[code]"/><!-- 1..1 The resource type this search parameter applies to -->
 <type value="[code]"/><!-- 1..1 number | date | string | token | reference | composite | quantity | uri -->
 <description value="[markdown]"/><!-- 1..1 Documentation for  search parameter -->
 <expression value="[string]"/><!-- ?? 0..1 FluentPath expression that extracts the values -->
 <xpath value="[string]"/><!-- ?? 0..1 XPath that extracts the values -->
 <xpathUsage value="[code]"/><!-- ?? 0..1 normal | phonetic | nearby | distance | other -->
 <target value="[code]"/><!-- 0..* Types of resource (if a resource reference) -->
 <component><!-- 0..* Reference(SearchParameter) For Composite resources to define the parts --></component>
</SearchParameter>

JSON Template

{doco
  "resourceType" : "SearchParameter",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Absolute URL used to reference this search parameter
  "name" : "<string>", // R!  Informal name for this search parameter
  "status" : "<code>", // draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Publication Date(/time)
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why this search parameter is defined
  "code" : "<code>", // R!  Code used in URL
  "base" : "<code>", // R!  The resource type this search parameter applies to
  "type" : "<code>", // R!  number | date | string | token | reference | composite | quantity | uri
  "description" : "<markdown>", // R!  Documentation for  search parameter
  "expression" : "<string>", // C? FluentPath expression that extracts the values
  "xpath" : "<string>", // C? XPath that extracts the values
  "xpathUsage" : "<code>", // C? normal | phonetic | nearby | distance | other
  "target" : ["<code>"], // Types of resource (if a resource reference)
  "component" : [{ Reference(SearchParameter) }] // For Composite resources to define the parts
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:SearchParameter;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:SearchParameter.url [ uri ]; # 1..1 Absolute URL used to reference this search parameter
  fhir:SearchParameter.name [ string ]; # 1..1 Informal name for this search parameter
  fhir:SearchParameter.status [ code ]; # 0..1 draft | active | retired
  fhir:SearchParameter.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:SearchParameter.date [ dateTime ]; # 0..1 Publication Date(/time)
  fhir:SearchParameter.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual)
  fhir:SearchParameter.contact [ # 0..* Contact details of the publisher
    fhir:SearchParameter.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:SearchParameter.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:SearchParameter.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:SearchParameter.requirements [ markdown ]; # 0..1 Why this search parameter is defined
  fhir:SearchParameter.code [ code ]; # 1..1 Code used in URL
  fhir:SearchParameter.base [ code ]; # 1..1 The resource type this search parameter applies to
  fhir:SearchParameter.type [ code ]; # 1..1 number | date | string | token | reference | composite | quantity | uri
  fhir:SearchParameter.description [ markdown ]; # 1..1 Documentation for  search parameter
  fhir:SearchParameter.expression [ string ]; # 0..1 FluentPath expression that extracts the values
  fhir:SearchParameter.xpath [ string ]; # 0..1 XPath that extracts the values
  fhir:SearchParameter.xpathUsage [ code ]; # 0..1 normal | phonetic | nearby | distance | other
  fhir:SearchParameter.target [ code ], ... ; # 0..* Types of resource (if a resource reference)
  fhir:SearchParameter.component [ Reference(SearchParameter) ], ... ; # 0..* For Composite resources to define the parts
]

Changes since DSTU2

SearchParameter
SearchParameter.useContext added
SearchParameter.requirements Type changed from string to markdown
SearchParameter.description Type changed from string to markdown
SearchParameter.expression added
SearchParameter.component added

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. SearchParameter IDomainResourceSearch Parameter for a resource
If an xpath is present, there SHALL be an xpathUsage
... url Σ1..1uriAbsolute URL used to reference this search parameter
... name Σ1..1stringInformal name for this search parameter
... status ?!Σ0..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimePublication Date(/time)
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy this search parameter is defined
... code Σ1..1codeCode used in URL
... base Σ1..1codeThe resource type this search parameter applies to
ResourceType (Required)
... type Σ1..1codenumber | date | string | token | reference | composite | quantity | uri
SearchParamType (Required)
... description Σ1..1markdownDocumentation for search parameter
... expression I0..1stringFluentPath expression that extracts the values
... xpath I0..1stringXPath that extracts the values
... xpathUsage I0..1codenormal | phonetic | nearby | distance | other
XPathUsageType (Required)
... target 0..*codeTypes of resource (if a resource reference)
ResourceType (Required)
... component 0..*Reference(SearchParameter)For Composite resources to define the parts

doco Documentation for this format

UML Diagram (Legend)

SearchParameter (DomainResource)An absolute URL that is used to identify this search parameter when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this search parameter is (or will be) publishedurl : uri [1..1]A free text natural language name identifying the search parametername : string [1..1]The status of this search parameter definition (this element modifies the meaning of other elements)status : code [0..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »A flag to indicate that this search parameter definition is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The date (and optionally time) when the search parameter definition was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the search parameter changesdate : dateTime [0..1]The name of the individual or organization that published the search parameterpublisher : string [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching of search parametersuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »The Scope and Usage that this search parameter was created to meetrequirements : markdown [0..1]The code used in the URL or the parameter name in a parameters resource for this search parametercode : code [1..1]The base resource type that this search parameter refers tobase : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »The type of value a search parameter refers to, and how the content is interpretedtype : code [1..1] « Data types allowed to be used for search parameters. (Strength=Required)SearchParamType! »A description of the search parameters and how it useddescription : markdown [1..1]A FluentPath expression that returns a set of elements for the search parameterexpression : string [0..1]An XPath expression that returns a set of elements for the search parameterxpath : string [0..1]How the search parameter relates to the set of elements returned by evaluating the xpath queryxpathUsage : code [0..1] « How a search parameter relates to the set of elements returned by evaluating its xpath query. (Strength=Required)XPathUsageType! »Types of resource (if a resource is referenced)target : code [0..*] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »Used to define the parts of a composite search parametercomponent : Reference [0..*] « SearchParameter »ContactThe name of an individual to contact regarding the search parametername : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]Contacts to assist a user in finding and communicating with the publishercontact[0..*]

XML Template

<SearchParameter xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Absolute URL used to reference this search parameter -->
 <name value="[string]"/><!-- 1..1 Informal name for this search parameter -->
 <status value="[code]"/><!-- 0..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Publication Date(/time) -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why this search parameter is defined -->
 <code value="[code]"/><!-- 1..1 Code used in URL -->
 <base value="[code]"/><!-- 1..1 The resource type this search parameter applies to -->
 <type value="[code]"/><!-- 1..1 number | date | string | token | reference | composite | quantity | uri -->
 <description value="[markdown]"/><!-- 1..1 Documentation for  search parameter -->
 <expression value="[string]"/><!-- ?? 0..1 FluentPath expression that extracts the values -->
 <xpath value="[string]"/><!-- ?? 0..1 XPath that extracts the values -->
 <xpathUsage value="[code]"/><!-- ?? 0..1 normal | phonetic | nearby | distance | other -->
 <target value="[code]"/><!-- 0..* Types of resource (if a resource reference) -->
 <component><!-- 0..* Reference(SearchParameter) For Composite resources to define the parts --></component>
</SearchParameter>

JSON Template

{doco
  "resourceType" : "SearchParameter",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R!  Absolute URL used to reference this search parameter
  "name" : "<string>", // R!  Informal name for this search parameter
  "status" : "<code>", // draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Publication Date(/time)
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why this search parameter is defined
  "code" : "<code>", // R!  Code used in URL
  "base" : "<code>", // R!  The resource type this search parameter applies to
  "type" : "<code>", // R!  number | date | string | token | reference | composite | quantity | uri
  "description" : "<markdown>", // R!  Documentation for  search parameter
  "expression" : "<string>", // C? FluentPath expression that extracts the values
  "xpath" : "<string>", // C? XPath that extracts the values
  "xpathUsage" : "<code>", // C? normal | phonetic | nearby | distance | other
  "target" : ["<code>"], // Types of resource (if a resource reference)
  "component" : [{ Reference(SearchParameter) }] // For Composite resources to define the parts
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:SearchParameter;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:SearchParameter.url [ uri ]; # 1..1 Absolute URL used to reference this search parameter
  fhir:SearchParameter.name [ string ]; # 1..1 Informal name for this search parameter
  fhir:SearchParameter.status [ code ]; # 0..1 draft | active | retired
  fhir:SearchParameter.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage
  fhir:SearchParameter.date [ dateTime ]; # 0..1 Publication Date(/time)
  fhir:SearchParameter.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual)
  fhir:SearchParameter.contact [ # 0..* Contact details of the publisher
    fhir:SearchParameter.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:SearchParameter.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:SearchParameter.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:SearchParameter.requirements [ markdown ]; # 0..1 Why this search parameter is defined
  fhir:SearchParameter.code [ code ]; # 1..1 Code used in URL
  fhir:SearchParameter.base [ code ]; # 1..1 The resource type this search parameter applies to
  fhir:SearchParameter.type [ code ]; # 1..1 number | date | string | token | reference | composite | quantity | uri
  fhir:SearchParameter.description [ markdown ]; # 1..1 Documentation for  search parameter
  fhir:SearchParameter.expression [ string ]; # 0..1 FluentPath expression that extracts the values
  fhir:SearchParameter.xpath [ string ]; # 0..1 XPath that extracts the values
  fhir:SearchParameter.xpathUsage [ code ]; # 0..1 normal | phonetic | nearby | distance | other
  fhir:SearchParameter.target [ code ], ... ; # 0..* Types of resource (if a resource reference)
  fhir:SearchParameter.component [ Reference(SearchParameter) ], ... ; # 0..* For Composite resources to define the parts
]

Changes since DSTU2

SearchParameter
SearchParameter.useContext added
SearchParameter.requirements Type changed from string to markdown
SearchParameter.description Type changed from string to markdown
SearchParameter.expression added
SearchParameter.component added

See the Full Difference for further information

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

5.7.4.1 Terminology Bindings

PathDefinitionTypeReference
SearchParameter.status The lifecycle status of a Value Set or Concept Map.RequiredConformanceResourceStatus
SearchParameter.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.ExtensibleContext of Use ValueSet
SearchParameter.base
SearchParameter.target 		One of the resource types defined as part of FHIR.Requiredhttp://hl7.org/fhir/valueset/resource-typesResourceType
SearchParameter.type Data types allowed to be used for search parameters.RequiredSearchParamType
SearchParameter.xpathUsage How a search parameter relates to the set of elements returned by evaluating its xpath query.RequiredXPathUsageType

5.7.4.2 Constraints

  • spd-1: If an xpath is present, there SHALL be an xpathUsage (expression : xpath.empty() or xpathUsage.exists())

5.7.5 SearchParameters on Extensions

The SearchParameter resource may be used to define searches on extensions. Depending on the context of the extension (as defined in the StructureDefinition), this may require multiple instances of the SearchParameter.xpath element like so:

  • If the extension's context is scoped by a single resource, SearchParameter.base must be set to that resource, and there may be one or more xpath elements corresponding to the elements specified in the extension's context, e.g. "f:Patient/f:name/f:extension[@url='extension url']"
  • If the extension's context specifies multiple resources, SearchParameter.base must be set to "DomainResource".
  • You may use a single xpath element with the full url of the Extension to indicate that the SearchParameter would search in all elements of the given SearchParameter.base resource for the given extension.

5.7.6 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionPaths
basetokenThe resource type this search parameter applies toSearchParameter.base
codetokenCode used in URLSearchParameter.code
componentreferenceFor Composite resources to define the partsSearchParameter.component
(SearchParameter)
contexttokenA use context assigned to the search parameterSearchParameter.useContext
descriptionstringDocumentation for search parameterSearchParameter.description
namestringInformal name for this search parameterSearchParameter.name
targettokenTypes of resource (if a resource reference)SearchParameter.target
typetokennumber | date | string | token | reference | composite | quantity | uriSearchParameter.type
urluriAbsolute URL used to reference this search parameterSearchParameter.url