FHIR:Vissue-MM-2759 Search result examples

Example: read support for all resources

The server offers read support for all resources that it has; each resource has a stable Resource.id and is accessible through a stable RESTful URL.

<Bundle xmlns="http://hl7.org/fhir" >
    <!-- Bundle.id is not different than any other Resource.id -->
    <id value="example-id1"/>

    <!-- Bundle.type should be set to 'searchset' -->
    <type value="searchset"/>

    <!-- Bundle.total is set to the number of matches for the request -->
    <total value="1"/>
    
    <!-- The "self link" shows the search request as how it was understood by the server -->
    <link>
        <relation value="self"/>
        <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/>
    </link>

    <entry>
        <!-- The Observation resource is accessible through a RESTful URL, which is used for the fullUrl -->
        <fullUrl value="https://example-server.nl/fhir/Observation/observation-123"/>

        <resource>
            <Observation>

                <!-- The Resource.id MUST be populated when it is accessible using a RESTful URL. -->
                <id value="observation-123" />
                ...
                <subject>
                    <!-- The Patient resource resides on the same server and can be referenced using a relative URL.
                         An absolute URL could be used in this case as well. -->
                    <reference value="Patient/patient-123" />
                </subject>
            </Observation>
        </resource>
        <search>
            <!-- Resources that match the search request have mode set to 'match' -->
            <mode value="match"/>
        </search>
    </entry>
</Bundle>

Example 2: server only supports search

The server supports doesn't support the read operation, for example because it's a FHIR facade that is unable to link a stable id to a certain entry in the underlying database. For this reason, it only supports searching for data.

<Bundle xmlns="http://hl7.org/fhir">
    <!-- Bundle.id is not different than any other Resource.id -->
    <id value="example-id2"/>

    <!-- Bundle.type should be set to 'searchset' -->
    <type value="searchset"/>

    <!-- Bundle.total is still set to the number of _matches_, even though more resources are included in the Bundle. -->
    <total value="1"/>

    <!-- The "self link" reflects the search as it was understood by the server -->
    <link>
        <relation value="self"/>
        <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/>
    </link>

    <!--
      The server is unable to offer a stable RESTful URL to the Patient resource, but it needs to satisfy the requirement
      that all resources are resolvable. Therefore, it includes the referenced Patient resource in the searchset Bundle.
    -->
    <entry>
        <!-- 
          Since the server is unable to produce a RESTful URL for reading the resource, so it uses an ephemeral fullUrl so that other 
          resources in the Bundle can refer to it.
        -->
        <fullUrl value="urn:uuid:69aefd96-b37d-4323-866b-762536c03375">
        <resource>
            <Patient>
                ....
            </Patient>
        </resource>
        <search>
            <!-- When resources are additionally included in the searchset Bundle while there's no direct match, .search.mode should be set to 'include'. -->
            <mode value="include" />
        </search>
    </entry>

    <entry>
        <!-- 
          Note that the fullUrl MUST be populated, even if this resource is not referred by any other resource within the Bundle. (?)
          Since the server is unable to produce a RESTful URL for reading the Observation resource, it creates an ephemeral fullUrl
          for this resource as well.
        -->
        <fullUrl value="urn:uuid:799c5790-f2aa-4045-8c19-a0d54773a059"/>
        <resource>
            <Observation>
                ...
                <subject>
                    <!-- The server doesn't support read for the Patient resource, so it's included in the Bundle using an ephemeral fullUrl. -->
                    <reference value="urn:uuid:69aefd96-b37d-4323-866b-762536c03375" /> 
                </subject>
                ...
            </Observation>
        </resource>
        <search>
            <mode value="match"/> <!-- Resources that match the search request have mode set to 'match' -->
        </search>
    </entry>
</Bundle>

Example 3: read support for some resources (hypothetical)

<Bundle xmlns="http://hl7.org/fhir" >
    <id value="example-id3"/> <!-- Bundle.id is not different than any other Resource.id -->
    <type value="searchset"/> <!-- Bundle.type should be set to 'searchset' -->
    <total value="1"/> <!-- Bundle.total is still set to the number of _matches_, even though more resources are included -->
    <link>
        <relation value="self"/>
        <url value="https://example-server.nl/fhir/Observation?code=http://loinc.org|85354-9"/> <!-- The "self link" reflects the search as it was understood by the server -->
    </link>
    <entry>
        <fullUrl value="urn:uuid:799c5790-f2aa-4045-8c19-a0d54773a059"/> <!-- The server doesn't support read, so the fullUrl is an ephemeral identifier that only has value within the Bundle -->
        <resource>
            <Observation>
                <!-- <id value="799c5790-f2aa-4045-8c19-a0d54773a059" /> it is recommended NOT to use the ephemeral id as Resource.id, but the opinions on this topic are divided -->
                ...
                <subject>
                    <reference value="http://example-server.nl/Patient/patient-123" /> <!-- The server supports read for the Patient resource, so an absolute URL could be used -->
                    <!-- <reference value="Patient/patient-123" /> However, a relative URL is invalid because it is relative to the fullUrl of the Observation resource.
                                                                   Since this fullUrl is not a RESTful URL, the relative URL cannot be resolved to an actual URL. -->
                </subject>
            </Observation>
        </resource>
        <search>
            <mode value="match"/> <!-- Resources that match the search request have mode set to 'match' -->
        </search>
    </entry>
</Bundle>