#334: Clarified distinction between context and prefetch.

Author: brynrhodes

docs/specification/1.0.md

@@ -162,9 +162,9 @@ curl
 
 ## Providing FHIR Resources to a CDS Service
 
-Each CDS Service will require specific FHIR resources in order to compute the recommendations the EHR requests. If real-world performance were no issue, an EHR could launch a CDS Service passing only context data, and the CDS Service could then request authorization for FHIR resources as they were needed, and then retrieve the resources from the EHR's FHIR server.  Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines a process to allow a CDS Service to request and obtain FHIR resources efficiently.
+Each CDS Service will require specific FHIR resources in order to compute the recommendations the EHR requests. If real-world performance were no issue, an EHR could launch a CDS Service passing only context data (such as the current user and patient ids), and the CDS Service could then request authorization for FHIR resources as they were needed, and then retrieve the resources from the EHR's FHIR server.  Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines a process to allow a CDS Service to request and obtain FHIR resources efficiently.
 
-Two optional methods are provided.  First, FHIR resources MAY be obtained by passing "prefetched" data from the EHR to the CDS Service in the service call.  FHIR resources requested in the CDS Service desciption are passed as key-value pairs, with each key matching a key described in the CDS Service description, and each value being a FHIR resource. If data are to be prefetched, the CDS Service registers a set of "prefetch templates" with the EHR, as described in the [Prefetch Template](#prefetch-template) section below.
+Two optional methods are provided.  First, FHIR resources MAY be obtained by passing "prefetched" data from the EHR to the CDS Service in the service call.  FHIR resources requested in the CDS Service description are passed as key-value pairs, with each key matching a key described in the CDS Service description, and each value being a FHIR resource. If data are to be prefetched, the CDS Service registers a set of "prefetch templates" with the EHR, as described in the [Prefetch Template](#prefetch-template) section below.
 
 The second method enables the CDS Service to retrieve FHIR resources for itself, but to do so more efficiently than if it were required to request and obtain its own authorization.  If the EHR decides to have the CDS Service fetch its own FHIR resources, the EHR obtains and passes directly to the CDS Service a bearer token issued for the CDS Service's use in executing FHIR API calls against the EHR FHIR server to obtain the required resources.  Some EHRs MAY pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required.  Each EHR SHOULD decide which approach, or combination, is preferred, based on performance considerations and assessment of attendant security and safety risks. For more detail, see the [FHIR Resource Access](#fhir-resource-access) section below.
 
@@ -202,7 +202,7 @@ An EHR MAY choose to honor some or all of the desired prefetch templates, and is
 - The EHR MAY compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of network calls to a minimum
 - The EHR MAY satisfy some of the desired prefetched templates via some internal service or even its own FHIR server.
 
-The EHR SHALL deny access if the requested resource is outside the user's authorized context.
+The EHR SHALL deny access if the requested resource is outside the user's authorized scope.
 
 Regardless of how the EHR satisfies the prefetch templates (if at all), the prefetched data given to the CDS Service MUST be equivalent to the data the CDS Service would receive if it were making its own call to the EHR FHIR server using the parameterized prefetch template.
 
@@ -625,15 +625,15 @@ Note that each hook (e.g. `medication-prescribe`) represents something the user
 
 #### What's the difference?
 
-A discrete user workflow or action within the EHR often naturally includes a set of contextual data. This context can contain both required and optional data and is specific to a hook. Additionally, the context data is relevant to most CDS Services subscribing to the hook.
+Any user workflow or action within an EHR will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as _context_ and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any EHR, this context can contain both required and optional data, depending on the capabilities of individual EHRs. However, the context information is intended to be relevant to most CDS Services subscribing to the hook.
 
-When the context data relates to a FHIR data type, it is important not to conflate context and prefetch. For instance, imagine a hook for opening a patient's chart. This hook should include the FHIR identifier of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR identifier of the patient is appropriate as CDS Services may not be interested in details about the patient resource but instead other data related to this patient. Or, a CDS Service may only need the full patient resource in certain scenarios. Therefore, including the full patient resource in context would be unnecessary. For CDS Services that want the full patient resource, they can request it to be prefetched or fetch it as needed from the FHIR server.
+Prefetch data, on the other hand, is defined by CDS Services as a way to allow the EHR to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, imagine a hook for opening a patient's chart. This hook should include the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR identifier of the patient is appropriate as CDS Services may not be interested in details about the patient resource but instead other data related to this patient. Or, a CDS Service may only need the full patient resource in certain scenarios. Therefore, including the full patient resource in context would be unnecessary. For CDS Services that want the full patient resource, they can request it to be prefetched or fetch it as needed from the FHIR server.
 
 Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the EHR (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered.
 
 Additionally, consider a PGX CDS Service and a Zika screening CDS Service, each of which is subscribed to the same hook. The context data specified by their shared hook should contain data relevant to both CDS Services; however, each service will have other specific data needs that will necessitate disparate prefetch requests. For instance, the PGX CDS Service likely is interested in genomics data whereas the Zika screening CDS Service will want Observations.
 
-In summary, context is data specific to a hook and universally relevant to all CDS Services subscribed to said hook. Prefetch data is unique to individual CDS Services and supplements the data from context.
+In summary, context is defined by the hook and typically relevant to all CDS Services subscribed to said hook. Prefetch data is defined by each CDS Service to support the specific behavior provided by the service.
 
 #### Prefetch tokens
 
@@ -736,9 +736,9 @@ Field | Optionality | Prefetch Token | Type | Description
 
 #### FHIR resources in context
 
-When potentially multiple FHIR resources value a single context field, these resources SHOULD be formatted as a FHIR Bundle. For example, multiple FHIR resources are necessary to describe all of the orders under review in the `order-review` hook's `orders` field. Hook definitions SHOULD prefer the use of FHIR Bundles over other bespoke data structures.
+When a context field may contain multiple FHIR resources, these resources SHOULD be formatted as a FHIR Bundle. For example, multiple FHIR resources are necessary to describe all of the orders under review in the `order-review` hook's `orders` field. Hook definitions SHOULD prefer the use of FHIR Bundles over other bespoke data structures.
 
-Often, context is populated with in-progress or in-memory data that may not yet be available from the FHIR server. For example, `medication-prescribe` and `order-review` define context fields containing FHIR resources that represent draft resources. In this case,  the EHR should only provide these draft resources and not the full set of orders available from its FHIR server. The CDS service MAY pre-fetch or query for FHIR resources with other statuses. 
+Often, context is populated with in-progress or in-memory data that may not yet be available from the FHIR server. For example, `medication-prescribe` and `order-review` define context fields containing FHIR resources that represent draft resources. In this case, the EHR should only provide these draft resources and not the full set of orders available from its FHIR server. The CDS service MAY pre-fetch or query for FHIR resources with other statuses. 
 
 All FHIR resources in context MUST be based on the same FHIR version.