Uploaded image for project: 'FHIR Specification Feedback'
  1. FHIR Specification Feedback
  2. FHIR-27897

Clarify token search syntax

    XMLWordPrintableJSON

    Details

    • Type: Change Request
    • Status: Applied (View Workflow)
    • Priority: Medium
    • Resolution: Persuasive with Modification
    • Specification:
      US Core (FHIR)
    • Raised in Version:
      3.1.0
    • Work Group:
      Cross-Group Projects
    • Related Page(s):
      Profiles and Extensions
    • Related Section(s):
      2.1.1.11
    • Grouping:
    • Resolution Description:
      Hide

      1. Change the headings for the Quick Start to:

      "Below is an overview of the required set of Server RESTful FHIR interactions - for example, search and read operations - for this profile. See the Conformance requirements for a complete list of supported RESTful interactions for this IG."

      • The syntax used to describe the interactions is described [here](general-guidance#search-syntax).

      2. change the syntax from:

      `{[system]}}code`

      to :

      `

      {system|}[code]`


      3. clarify *optional for client to supply* in Search Syntax:

      ### Search Syntax

      For searching a resource, interactions on profile pages are defined with the following syntax:

      *`GET [base]/[Resource-type]?[parameter1]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]{&[parameter2]{:m1|m2|...}={c1|c2|...}[value1{,value2,...}]&...}`*

      - GET is the HTTP verb used for fetching a resource
      - Variables surrounded by "[]" are mandatory for the client to supply, and will be replaced by the string literal identified.
      - Variables surrounded by "{}" are optional for the client to supply, and will be replaced by the string literal identified.
      - base: The Service Root URL (e.g. “<https://fhir-open-api-dstu2.smarthealthit.org>”)
      - Resource-type: The name of a resource type (e.g. “Patient”)
      - parameter: the search parameters as defined for the particular interaction (e.g."?patient=Patient/123")
      - value: the search parameter value for a particular search
      - note for values of type `token` [(how to search by token)], the syntax `{system|}

      [code]` means that the system value is optional for the client to supply

      • {:m1|m2|...}: The list of supported search parameter modifiers
      • {c1|c2|...}: The list of supported search parameter comparators
        - {,value2,...}: Optional multiple 'OR' Values
        - {&parameter2={:m1|m2|...}={c1|c2|...}

        [value1

        {,value2,...}

        &...}: Optional multiple 'AND' search parameters

      In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

      `GET [base]/[Resource-type]?name=value&...`

      For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name “code” for search on the LOINC code. For more information see the [FHIR RESTful Search API]

      Note that the patient may be implicit in the context in some implementations (e.g. using SMART). Then the patient parameter can be omitted:

      `GET [base]/[Resource-type]{?other-parameters}`

      pre-applied

      Show
      1. Change the headings for the Quick Start to: "Below is an overview of the required set of Server RESTful FHIR interactions - for example, search and read operations - for this profile. See the Conformance requirements for a complete list of supported RESTful interactions for this IG." The syntax used to describe the interactions is described [here] (general-guidance#search-syntax). 2. change the syntax from: `{ [system] }}code` to : ` {system|} [code] ` 3. clarify * optional for client to supply * in Search Syntax: ### Search Syntax For searching a resource, interactions on profile pages are defined with the following syntax: * `GET [base] / [Resource-type] ? [parameter1] {:m1|m2|...}={c1|c2|...} [value1{,value2,...}] {& [parameter2] {:m1|m2|...}={c1|c2|...} [value1{,value2,...}] &...}` * - GET is the HTTP verb used for fetching a resource - Variables surrounded by "[]" are mandatory for the client to supply, and will be replaced by the string literal identified. - Variables surrounded by "{}" are optional for the client to supply, and will be replaced by the string literal identified. - base: The Service Root URL (e.g. “< https://fhir-open-api-dstu2.smarthealthit.org >”) - Resource-type: The name of a resource type (e.g. “Patient”) - parameter: the search parameters as defined for the particular interaction (e.g."?patient=Patient/123") - value: the search parameter value for a particular search - note for values of type `token` [(how to search by token)] , the syntax `{system|} [code] ` means that the system value is optional for the client to supply {:m1|m2|...}: The list of supported search parameter modifiers {c1|c2|...}: The list of supported search parameter comparators - {,value2,...}: Optional multiple 'OR' Values - {&parameter2={:m1|m2|...}={c1|c2|...} [value1 {,value2,...} &...}: Optional multiple 'AND' search parameters In the simplest case, a search is executed by performing a GET operation in the RESTful framework: `GET [base] / [Resource-type] ?name=value&...` For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. The search parameter names are defined for each resource. For example, the Observation resource the name “code” for search on the LOINC code. For more information see the [FHIR RESTful Search API] Note that the patient may be implicit in the context in some implementations (e.g. using SMART). Then the patient parameter can be omitted: `GET [base] / [Resource-type] {?other-parameters}` pre-applied
    • Resolution Vote:
      Eric Haas/Jean Duteau: 5-0-2
    • Change Category:
      Clarification
    • Change Impact:
      Non-substantive

      Description

      Discussed for zulip https://chat.fhir.org/#narrow/stream/179175-argonaut/topic/token.20search.3F

      1) Need clarify in search syntax page: https://build.fhir.org/ig/HL7/US-Core-R4/general-guidance.html#search-syntax that curly bracket {} means optional.

      2) Update all Quick Start pages containing similar token syntax (example taken from 3.3.1.4.1)

      code={[system]}|[code],{[system]}|[code],...
      GET [base]/Observation?patient=[reference]&code={[system]}|[code]{,{[system]}|[code],...}
      

      To:

      code={system|}[code],{system|}[code],...
      GET [base]/Observation?patient=[reference]&code={system|}[code]{,{system|}[code],...}
       

      3) Clarify that while using such search syntax, server SHALL support both code, and code + system search syntax. Client SHOULD be able to query with either syntax.

        Attachments

          Activity

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            yunwwang Yunwei Wang
            Watchers:
            4 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:
              Vote Date: