Merge branch 'master' into iss195-hook-maturity-model

Author: kpshek

docs/specification/1.0.md

@@ -5,7 +5,7 @@
 
 ## Overview
 
-The CDS Hooks specification describes the RESTful APIs and interactions between EHRs and CDS Services. All data exchanged through the RESTful APIs MUST BE sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in [RFC2818](https://tools.ietf.org/html/rfc2818).
+The CDS Hooks specification describes the RESTful APIs and interactions between EHRs and CDS Services. All data exchanged through the RESTful APIs MUST be sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in [RFC2818](https://tools.ietf.org/html/rfc2818).
 
 ### Conformance Language
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119).
@@ -46,7 +46,7 @@ Field | Description
 ----- | ---------
 `services` | *array*. An array of **CDS Services**
 
-Each CDS Service is described by the following attributes.
+Each CDS Service SHALL be described by the following attributes.
 
 Field | Optionality | Type | Description
 ----- | ----- | ----- | ---------
@@ -103,11 +103,11 @@ curl "https://example.com/cds-services"
 
 ### HTTP Request
 
-An EHR calls a CDS Service by `POST`ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as `{baseUrl}/cds-services/{service.id}`. The request includes a JSON `POST` body with the following input fields:
+An EHR SHALL call a CDS Service by `POST`ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as `{baseUrl}/cds-services/{service.id}`. The request SHALL include a JSON `POST` body with the following input fields:
 
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
-`hook` | REQUIRED | *string* | The hook that triggered this CDS Service call<br />(todo: link to hook documentation)
+`hook` | REQUIRED | *string* | The hook that triggered this CDS Service call. See [Hooks](../hooks/index.md).
 <nobr>`hookInstance`</nobr> | REQUIRED | *string* | A UUID for this particular hook call (see more information below)
 `fhirServer` | OPTIONAL | *URL* | The base URL EHR's [FHIR](https://www.hl7.org/fhir/) server. If fhirAuthorization is provided, this field is REQUIRED.  The scheme should be `https`
 `fhirAuthorization` | OPTIONAL | *object* | A structure holding an [OAuth 2.0][OAuth 2.0] bearer access token granting the CDS Service access to FHIR resources, along with supplemental information relating to the token. See the [FHIR Resource Access](#fhir-resource-access) section for more information.
@@ -207,12 +207,13 @@ An EHR MAY choose to honor some or all of the desired prefetch templates, and is
 
 - The EHR may have some of the desired prefetched data already in memory, thereby removing the need for any network call
 - 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 may deny access because the requested resource is outside the user's authorized context.
+- The EHR may satisfy some of the desired prefetched templates via some internal service or even its own FHIR server.
 
-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.
+The EHR SHALL deny access if the requested resource is outside the user's authorized context.
 
-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).
+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.
+
+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 CDS Service MUST NOT receive any prefetch template key that the EHR chooses not to satisfy; in which case the prefetch template key SHOULD NOT be sent. Similarly, if the EHR encounters an error while prefetching any data, the prefetch template key SHOULD NOT be sent to the CDS Service. If the EHR has no data to populate a template prefetch key, the prefetch template key MUST have a value of __null__. It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to manually retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code.
 
@@ -290,9 +291,9 @@ To reduce the implementation burden on EHRs that support CDS Services, CDS Hooks
 
 The CDS Service is able to use the EHR's FHIR server to obtain any FHIR resources it requires beyond those provided by the EHR as prefetched data. This is similar to the approach used by SMART on FHIR wherein the SMART app requests and ultimately obtains an access token from the EHR's Authorization server using the SMART launch workflow, as described in [SMART App Authorization Guide](http://docs.smarthealthit.org/authorization/).
 
-Like SMART on FHIR, CDS Hooks requires that clients present a valid access token to the FHIR server with each API call. Thus, a CDS Service must be able to obtain an access token before communicating with the EHR's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow must accommodate the automated, low-latency delivery of an access token to the CDS service.
+Like SMART on FHIR, CDS Hooks requires that clients present a valid access token to the FHIR server with each API call. Thus, a CDS Service MUST be able to obtain an access token before communicating with the EHR's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow MUST accommodate the automated, low-latency delivery of an access token to the CDS service.
 
-With CDS Hooks, if the EHR wants to provide the CDS Service direct access to FHIR resources, the EHR creates an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with [OAuth 2.0's][OAuth 2.0] bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The EHR remains in control of creating an access token that is associated with the specific CDS Service, user, and context of the invocation.  As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the EHR MUST BE limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL BE scoped to:
+With CDS Hooks, if the EHR wants to provide the CDS Service direct access to FHIR resources, the EHR creates an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with [OAuth 2.0's][OAuth 2.0] bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The EHR remains in control of creating an access token that is associated with the specific CDS Service, user, and context of the invocation.  As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the EHR MUST be limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL be scoped to:
 
 - The CDS Service being invoked
 - The current user
@@ -311,7 +312,7 @@ Field | Optionality | Type | Description
 
 The scopes granted to the CDS Service via the `scope` field are defined by the [SMART on FHIR specification](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/).
 
-The `expires_in` value is established by the authorization server and SHOULD BE very short lived, as the access token must be treated as a transient value by the CDS Service.
+The `expires_in` value is established by the authorization server and SHOULD BE very short lived, as the access token MUST be treated as a transient value by the CDS Service.
 
 Below is an example `fhirAuthorization` parameter:
 
@@ -352,10 +353,10 @@ Each **Card** is described by the following attributes.
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
 `summary` | REQUIRED | *string* | One-sentence, <140-character summary message for display to the user inside of this card.
-`detail` | OPTIONAL | *string* | Optional detailed information to display; if provided MUST BE represented in [(GitHub Flavored) Markdown](https://github.github.com/gfm/). (For non-urgent cards, the EHR MAY hide these details until the user clicks a link like "view more details...".)
+`detail` | OPTIONAL | *string* | Optional detailed information to display; if provided MUST be represented in [(GitHub Flavored) Markdown](https://github.github.com/gfm/). (For non-urgent cards, the EHR MAY hide these details until the user clicks a link like "view more details...".)
 `indicator` | REQUIRED | *string* | Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: `info`, `warning`, `critical`. The EHR MAY use this field to help make UI display decisions such as sort order or coloring.
 `source` | REQUIRED | *object* | Grouping structure for the **Source** of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents.
-<nobr>`suggestions`</nobr> | OPTIONAL | *array* of **Suggestions** | Allows a service to suggest a set of changes in the context of the current activity (e.g.  changing the dose of the medication currently being prescribed, for the `medication-prescribe` activity). If used, the user MUST BE allowed to choose no more than one suggestion.
+<nobr>`suggestions`</nobr> | OPTIONAL | *array* of **Suggestions** | Allows a service to suggest a set of changes in the context of the current activity (e.g.  changing the dose of the medication currently being prescribed, for the `medication-prescribe` activity). If used, the user MUST be allowed to choose no more than one suggestion.
 `links` | OPTIONAL | *array* of **Links** | Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision.
 
 #### Source
@@ -463,7 +464,7 @@ CDS Hooks defines a security model that addresses these risks by assuring that t
 
 Prior to enabling EHRs to request decision support from any CDS Service, the EHR vendor and/or provider organization is expected to perform due diligence on the CDS Service provider.  Each EHR vendor/provider is individually responsible for determining the suitability, safety and integrity of the CDS Services it uses, based on the organization's own risk-management strategy.  Each EHR vendor/provider SHOULD maintain a "white list" (and/or "black list") of the CDS Services it has vetted, and the Card links that have been deemed safe to display from within the EHR context. Each provider organization is expected to work with its EHR vendor to choose what CDS Services to allow and to negotiate the conditions under which the CDS Services may be called.
 
-Once a CDS Service provider is selected, the EHR vendor/provider negotiates the terms under which service will be provided.  This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, data elements that will be made available through an access token passed by the EHR, and steps the CDS Service must take to protect patient data and access tokens.  To enable the EHR authorization server to authorize CDS Service access to FHIR resources, the CDS Service is registered as a client to the EHR authorization server.  These business arrangements are documented in the service agreement.
+Once a CDS Service provider is selected, the EHR vendor/provider negotiates the terms under which service will be provided.  This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, data elements that will be made available through an access token passed by the EHR, and steps the CDS Service MUST take to protect patient data and access tokens.  To enable the EHR authorization server to authorize CDS Service access to FHIR resources, the CDS Service is registered as a client to the EHR authorization server.  These business arrangements are documented in the service agreement.
 
 Every interaction between an EHR and a CDS Service is initiated by the EHR sending a service request to a CDS Service endpoint protected using the [Transport Layer Security protocol](https://tools.ietf.org/html/rfc5246).   Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the EHR and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured.
 
@@ -504,7 +505,7 @@ jti | REQUIRED | *string* | A nonce string value that uniquely identifies this a
 
 CDS Services SHOULD whitelist the `iss`, `jku` and `sub` fields to only the EHRs they trust.
 
-Per [rfc7519](https://tools.ietf.org/html/rfc7519#section-4.1.3), the `aud` value is either a string or an array of strings. For CDS Hooks, this value MUST BE the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of `https://cds.example.org`. When the EHR invokes the CDS Service discovery endpoint, the aud value is either `"https://cds.example.org/cds-services"` or `["https://cds.example.org/cds-services"]`. Similarly, when the EHR invokes a particular CDS Service (say, `some-service`), the aud value is either `"https://cds.example.org/cds-services/some-service"` or `["https://cds.example.org/cds-services/some-service"]`.
+Per [rfc7519](https://tools.ietf.org/html/rfc7519#section-4.1.3), the `aud` value is either a string or an array of strings. For CDS Hooks, this value MUST be the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of `https://cds.example.org`. When the EHR invokes the CDS Service discovery endpoint, the aud value is either `"https://cds.example.org/cds-services"` or `["https://cds.example.org/cds-services"]`. Similarly, when the EHR invokes a particular CDS Service (say, `some-service`), the aud value is either `"https://cds.example.org/cds-services/some-service"` or `["https://cds.example.org/cds-services/some-service"]`.
 
 The EHR MUST make its public key, expressed as a JSON Web Key (JWK) in a JWK Set, as defined by [rfc7517](https://tools.ietf.org/html/rfc7517). The `kid` value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature.