#313: Additional clarification for prefetch templates.

Author: brynrhodes

docs/specification/1.0.md

@@ -193,30 +193,29 @@ Similarly, each EHR will decide what FHIR resources to authorize and to prefetch
 
 ### Prefetch Template
 
-A _prefetch template_ is a `read` or `search` request that describes relevant data needed by the CDS Service. To allow for prefetch templates that are dependent upon the particular CDS Service request, prefetch templates may include references to context using _prefetch tokens_. A prefetch token is an identifier in a prefetch template that is replaced by a value from the hook context to construct the FHIR URL used to request the prefetch data. 
+A _prefetch template_ is a `read` or `search` request that describes relevant data needed by the CDS Service. For example, the following is a prefetch template for hemoglobin A1c observations:
 
-The `prefetch` field of a CDS Service description defines the set of prefetch templates for that service, providing a _prefetch key_ for each one that is used to provide the prefetch data in the CDS request.
+```
+Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date
+```
 
-Prefetch tokens MUST be delimited by `{{` and `}}`, MUST be named based upon the field they correspond to, and MUST have a primitive value.
+To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using _prefetch tokens_. In the above example, `{{context.patientId}}` is a prefetch token. A prefetch token is a placeholder in a prefetch template that is replaced by a value from the hook's context to construct the FHIR URL used to request the prefetch data. 
 
-Individual hooks specify which of their `context` fields can be used as prefetch tokens. Only root-level fields with a primitive value within the `context` object are eligible to be used as prefetch tokens.
+Prefetch tokens MUST be delimited by `{{` and `}}`, and MUST contain only the qualified path to a hook context field.
 
-For instance, given a hook of `example-hook` with the following context in which the `patientId` and `medicationId` fields are both denoted as prefix tokens:
+Individual hooks specify which of their `context` fields can be used as prefetch tokens. Only root-level fields with a primitive value within the `context` object are eligible to be used as prefetch tokens. For example, `{{context.medication.id}}` is not a valid prefetch token because it attempts to access the `id` field of the `medication` field.
+
+The `prefetch` field of a CDS Service description defines the set of prefetch templates for that service, providing a _prefetch key_ for each one that is used to identify the prefetch data in the CDS request. For example:
 
 ```json
-"context": {
-  "patientId": "123",
-  "medicationId": "456",
-  "medication": {
-    "id": "456",
-    "code": {
-      ... // FHIR CodeableConcept
-    }
+{
+  "prefetch": {
+    "hemoglobin-a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date"
   }
 }
 ```
 
-The prefetch tokens defined by this `example-hook` would be `{{context.patientId}}` and `{{context.medicationId}}`. Note that the `context.medication.id` field is not eligible to be a prefetch token as it is not a root-level field of the `context` object.
+In this `prefetch`, `hemoglobin-a1c` is the prefetch key for this prefetch template. For a complete worked example, see [below](#example-prefetch-templates).
 
 An EHR MAY choose to honor some or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example:
 
@@ -232,7 +231,7 @@ Regardless of how the EHR satisfies the prefetch templates (if at all), the pref
 
 > Note that this means that CDS services will receive only the information they have requested and are authorized to receive. Prefetch data for other services registered to the same hook MUST NOT be provided.
 
-The resulting response, which MUST be rendered in a single page — no "next page" links allowed — is passed along to the CDS Service using the `prefetch` parameter (see below for a complete example).
+The resulting response, which MUST be rendered in a single page — no "next page" links allowed — is passed along to the CDS Service using the `prefetch` parameter (see [below](#example-prefetch-templates) for a complete example).
 
 > Note that the reason prefetch results are not allowed to include next page links is that if the prefetched data contains just a single page of data, the CDS Service has no means to retrieve the subsequent pages of data. Consider, for example, a CDS Hooks implementation that does not expose a FHIR server.
 
@@ -261,7 +260,7 @@ goal is to know, at call time:
 | `hemoglobin-a1c` | Most recent Hemoglobin A1c reading for this patient. |
 | `user` | Information on the current user (Practitioner).
 
-#### Example prefetch response
+#### Example prefetch data
 
 ```json
 {
@@ -293,7 +292,7 @@ goal is to know, at call time:
 }
 ```
 
-The response is augmented to include two prefetch values, where the dictionary
+The CDS Hooks request is augmented to include two prefetch values, where the dictionary
 keys match the request keys (`patient` and `hemoglobin-a1c` in this case).
 
 Note that the missing `user` key indicates that either the EHR has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving this Practitioner data from the FHIR server (if required).