Document prefetch token format and update examples (fixes #151)

docs/specification/1.0.md

@@ -77,7 +77,7 @@ curl "https://example.com/cds-services"
       "description": "An example of a CDS Service that returns a static set of cards",
       "id": "static-patient-greeter",
       "prefetch": {
-        "patientToGreet": "Patient/{{Patient.id}}"
+        "patientToGreet": "Patient/{{context.patientId}}"
       }
     },
     {
@@ -86,8 +86,8 @@ curl "https://example.com/cds-services"
       "description": "An example of a CDS Service that simply echos the medication being prescribed",
       "id": "medication-echo",
       "prefetch": {
-        "patient": "Patient/{{Patient.id}}",
-        "medications": "MedicationOrder?patient={{Patient.id}}"
+        "patient": "Patient/{{context.patientId}}",
+        "medications": "MedicationOrder?patient={{context.patientId}}"
       }
     }
   ]
@@ -173,12 +173,34 @@ Similarly, each EHR will decide what FHIR resources to authorize and to prefetch
 ### Prefetch Template
 
 The prefetch template is a dictionary of `read` and `search` requests to supply
-relevant data, where the following variables are defined:
+relevant data. In order to allow for prefetch templates that are dependent upon the particular CDS Service request, prefetch tokens or variables may be defined.
 
-|variable|meaning|
+Prefetch tokens MUST be delimited by `{{` and `}}`, MUST be named based upon the field they correspond to, and MUST have a primitive value.
+
+The CDS Hooks specification defines just one prefetch token:
+
+|Variable|Meaning|
 ---------|--------
-|`{{Patient.id}}`|The id of the patient in context for this activity (e.g. `123`)|
-|`{{User.id}}`|The type and id of the user for this session (e.g. `Practitioner/123`)|
+|`{{user}}`|The value of the `user` field from this CDS Service request (e.g. `Practitioner/123`)|
+
+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 instance, given a hook of `example-hook` with the following context in which the `patientId` and `medicationId` fields are both denoted as prefix tokens:
+
+```json
+"context": {
+  "patientId": "123",
+  "medicationId": "456",
+  "medication": {
+    "id": "456",
+    "code": {
+      ... // FHIR CodeableConcept
+    }
+  }
+}
+```
+
+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.
 
 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:
 
@@ -198,9 +220,9 @@ The CDS Service MUST NOT receive any prefetch template key that the EHR chooses
 ```json
 {
   "prefetch": {
-    "p": "Patient/{{Patient.id}}",
-    "a1c": "Observation?patient={{Patient.id}}&code=4548-4&_count=1&sort:desc=date",
-    "u": "Practitioner/{{User.id}}"
+    "p": "Patient/{{context.patientId}}",
+    "a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date",
+    "u": "Practitioner/{{user}}"
   }
 }
 ```
@@ -257,7 +279,7 @@ To reduce the implementation burden on EHRs that support CDS Services, CDS Hooks
 
 * _instance_ level [read](https://www.hl7.org/fhir/http.html#read) interactions (for resources with known ids such as `Patient` and `Practitioner`)
 * _type_ level [search](https://www.hl7.org/fhir/http.html#search) interactions
-* Patient references (e.g. `patient={{Patient}}`)
+* Patient references (e.g. `patient={{context.patientId}}`)
 * _token_ search parameters using equality (e.g. `code=4548-4`) and optionally the `:in` modifier (no other modifiers for token parameters)
 * _date_ search parameters on `date`, `dateTime`, `instant`, or `Period` types only, and using only the prefixes `eq`, `lt`, `gt`, `ge`, `le`
 * the `_count` parameter to limit the number of results returned
@@ -551,7 +573,7 @@ As another example, an extension defined on the discovery response could look li
       "hook": "patient-view",
       "id": "patientview",
       "prefetch": {
-        "patient": "Patient/{{Patient.id}}"
+        "patient": "Patient/{{context.patientId}}"
       },
       "description": "clinical decision support for patient view",
       "extension": {