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)

The server is able to produce a stable RESTful URL for the Patient resource, but not for the Observation resource.

<Bundle xmlns="http://hl7.org/fhir" >
    <!-- Bundle.id is not different than any other Resource.id -->
    <id value="example-id3"/>
    
    <!-- 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 -->
    <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>
        <!-- 
          Since the server is unable to produce a RESTful URL for reading the Observation resource, it creates an ephemeral fullUrl
          for this resource.
          Note that the fullUrl MUST be populated, even if this resource is not referred by any other resource within the Bundle. (?)
        -->
        <fullUrl value="urn:uuid:e07ffa10-c043-4dd6-aa52-6ac273c82da9"/>
        <resource>
            <Observation>
                ...
                <subject>
                    <!--
                      The server supports read for the Patient resource, so an absolute URL can be used.
                      Note that a relative URL is invalid in this case, because it is deemed relative to the fullUrl of the Observation resource.
                      Since this fullUrl is not a RESTful URL, a relative URL cannot be resolved to an actual URL. -->
                    -->
                    <reference value="http://example-server.nl/Patient/patient-123" /> 
                </subject>
                ...
            </Observation>
        </resource>
        ...
    </entry>
</Bundle>

Invalid example: using contained resources

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" >
    ...
    <entry>
        <fullUrl value="urn:uuid:2290607c-79e8-47ed-a23e-b8c3d5f224b2"/>
        <resource>
            <Observation>
                ...
                <contained>
                    <Patient>
                        <id value="patient1"/>
                        ...
                    </Patient>
                </contained>
                ...
                <subject>
                    <!--
                      Wrong approach: 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 sends the Patient resource as a contained
                      resource within the Observation resource.
                      Resources should only be contained if they cannot have an independent existence outside of the resource
                      containing it. This is not the case in the current situation, so this approach is invalid!
                    -->
                    <reference value="#patient1" /> 
                </subject>
                ...
            </Observation>
        </resource>
        ...
    </entry>
</Bundle>