Moved prefetch token section from hooks documentation to prefetch templates section.

Author: brynrhodes

docs/specification/1.0.md

@@ -297,6 +297,69 @@ 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).
 
+#### Prefetch tokens
+
+Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be `Condition?patient=123`. In order to express this as a prefetch template, the CDS Service must express the FHIR identifier of the patient as a token so that the EHR can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be `context.name-of-the-field`. For example, given a context like:
+
+```json
+"context" : {
+  "patientId": "123"
+}
+```
+
+The token name would be `{{context.patientId}}`. Again using our above conditions example, the complete prefetch template would be `Condition?patient={{context.patientId}}`.
+
+Only the first level fields in context may be considered for tokens. Hook creators MUST document which fields in the context are supported as tokens. If a context field can be tokenized, the value of the context field MUST be a JSON primitive data type that can placed into a FHIR query (i.e. a string, a number, or a boolean).
+
+For example, given the following context that contains amongst other things, a Patient FHIR resource:
+
+```json
+"context" : {
+  "encounterId": "456",
+  "patient": {
+    "resourceType": "Patient",
+    "id": "123",
+    "active": true,
+    "name": [
+      {
+        "use": "official",
+        "family": "Watts",
+        "given": [
+          "Wade"
+        ]
+      }
+    ],
+    "gender": "male",
+    "birthDate": "2024-08-12"
+  }
+}
+```
+
+Only the `encounterId` field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The Patient.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the Patient.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new `patientId` field:
+
+```json
+"context" : {
+  "patientId": "123",
+  "encounterId": "456",
+  "patient": {
+    "resourceType": "Patient",
+    "id": "123",
+    "active": true,
+    "name": [
+      {
+        "use": "official",
+        "family": "Watts",
+        "given": [
+          "Wade"
+        ]
+      }
+    ],
+    "gender": "male",
+    "birthDate": "2024-08-12"
+  }
+}
+```
+
 #### Prefetch query restrictions
 
 To reduce the implementation burden on EHRs that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. Valid prefetch templates SHOULD only make use of:
@@ -715,77 +778,14 @@ Prefetch data, on the other hand, is defined by CDS Services as a way to allow t
 }
 ```
 
-See the section on [prefetch tokens](#prefetch-tokens) below for more information on how contextual information can be used to parameterize prefetch templates.
+See the section on [prefetch tokens](#prefetch-tokens) for more information on how contextual information can be used to parameterize prefetch templates.
 
 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 specified in the hook definition to guide developers on the information available at the point in the workflow when the hook is triggered. Prefetch data is defined by each CDS Service because it is specific to the information that service needs in order to process.
 
-#### Prefetch tokens
-
-Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be `Condition?patient=123`. In order to express this as a prefetch template, the CDS Service must express the FHIR identifier of the patient as a token so that the EHR can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be `context.name-of-the-field`. For example, given a context like:
-
-```json
-"context" : {
-  "patientId": "123"
-}
-```
-
-The token name would be `{{context.patientId}}`. Again using our above conditions example, the complete prefetch template would be `Condition?patient={{context.patientId}}`.
-
-Only the first level fields in context may be considered for tokens. Hook creators MUST document which fields in the context are supported as tokens. If a context field can be tokenized, the value of the context field MUST be a JSON primitive data type that can placed into a FHIR query (i.e. a string, a number, or a boolean).
-
-For example, given the following context that contains amongst other things, a Patient FHIR resource:
-
-```json
-"context" : {
-  "encounterId": "456",
-  "patient": {
-    "resourceType": "Patient",
-    "id": "123",
-    "active": true,
-    "name": [
-      {
-        "use": "official",
-        "family": "Watts",
-        "given": [
-          "Wade"
-        ]
-      }
-    ],
-    "gender": "male",
-    "birthDate": "2024-08-12"
-  }
-}
-```
-
-Only the `encounterId` field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The Patient.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the Patient.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new `patientId` field:
-
-```json
-"context" : {
-  "patientId": "123",
-  "encounterId": "456",
-  "patient": {
-    "resourceType": "Patient",
-    "id": "123",
-    "active": true,
-    "name": [
-      {
-        "use": "official",
-        "family": "Watts",
-        "given": [
-          "Wade"
-        ]
-      }
-    ],
-    "gender": "male",
-    "birthDate": "2024-08-12"
-  }
-}
-```
-
 ### Hook Definition Format
 
 Hooks are defined in the following format.