Merge branch 'master' into iss278-add-puncuation-to-table-descriptions

Author: brettmarquard

docs/specification/1.0.md

@@ -15,7 +15,7 @@ This specification has the following limitations.
 
 * The specification provides options for providing a CDS Service access to the EHR's FHIR resources through use of either prefetch and/or a bearer access token to be presented to the FHIR Server.  Decisions regarding which approach to take, and details regarding how the choice is implemented, are left up to the EHR vendor/provider, as architectural considerations will come into play.
 * The specification requires that each CDS Service provider be registered (client_id, key-pair identifier) with the EHR Authorization Server, but does not dictate how registration is accomplished (e.g., dynamic vs. manual).
-* The specification acknowledges that each EHR vendor/provider will need to vet CDS Service providers and suggests that vendors/providers may want to create a "white list" of providers deemed "safe" and/or a "black list" of providers deemed "unsafe."  Similarly, an EHR vendor/provider may choose to assess the safety of active links embedded in CDS Hooks Cards returned to the EHR.  The specification does not suggest how such vetting is accomplished nor suggest factors to consider, as these judgments are dependent upon each EHR vendor's or provider's existing vetting processes and risk-management policy.
+* The specification acknowledges that each EHR vendor/provider will need to vet CDS Service providers and suggests that vendors/providers create a "white list" of providers deemed "safe" and/or a "black list" of providers deemed "unsafe."  Similarly, an EHR vendor/provider MAY assess the safety of active links embedded in CDS Hooks Cards returned to the EHR.  The specification does not suggest how such vetting is accomplished nor suggest factors to consider, as these judgments are dependent upon each EHR vendor's or provider's existing vetting processes and risk-management policy.
 
 ## Open API Specification
 
@@ -165,16 +165,16 @@ curl
 
 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.
 
-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 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.
 
-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 choose to pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required.  Each EHR may 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.
+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.
 
 Similarly, each EHR will decide what FHIR resources to authorize and to prefetch, based on the CDS Service description's "prefetch" request and on the provider's assessment of the "minimum necessary."  The EHR provider and the CDS Service provider will negotiate the set of FHIR resources to be provided, and how these data will be provided, as part of their service agreement.
 
 ### Prefetch Template
 
 The prefetch template is a dictionary of `read` and `search` requests to supply
-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.
+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.
 
 Prefetch tokens MUST be delimited by `{{` and `}}`, MUST be named based upon the field they correspond to, and MUST have a primitive value.
 
@@ -205,9 +205,9 @@ The prefetch tokens defined by this `example-hook` would be `{{context.patientId
 
 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:
 
-- 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 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 SHALL deny access if the requested resource is outside the user's authorized context.
 
@@ -334,7 +334,7 @@ Below is an example `fhirAuthorization` parameter:
 
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
-`cards` | REQUIRED | *array* | An array of **Cards**. Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The EHR decides how to display cards, but we recommend displaying suggestions using buttons, and links using underlined text.
+`cards` | REQUIRED | *array* | An array of **Cards**. Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The EHR decides how to display cards, but this specification recommends displaying suggestions using buttons, and links using underlined text.
 
 If your CDS Service has no decision support for the user, your service should return a 200 HTTP response with an empty array of cards.
 
@@ -365,7 +365,7 @@ The **Source** is described by the following attributes.
 
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
-<nobr>`label`</nobr>| REQUIRED | *string* | A short, human-readable label to display for the source of the information displayed on this card. If a `url` is also specified, this may be the text for the hyperlink.
+<nobr>`label`</nobr>| REQUIRED | *string* | A short, human-readable label to display for the source of the information displayed on this card. If a `url` is also specified, this MAY be the text for the hyperlink.
 `url` | OPTIONAL | *URL* | An optional absolute URL to load (via `GET`, in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card. Note that this URL should not be used to supply a context-specific "drill-down" view of the information on this card. For that, use `link.url` instead.
 `icon` | OPTIONAL | *URL* | An absolute URL to an icon for the source of this card. The icon returned by this URL SHOULD be a 100x100 pixel PNG image without any transparent regions.
 
@@ -386,8 +386,8 @@ Each **Action** is described by the following attributes.
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
 `type` |  REQUIRED | *string* | The type of action being performed. Allowed values are: `create`, `update`, `delete`.
-`description` | REQUIRED | *string* | Human-readable description of the suggested action. May be presented to the end-user.
-`resource` | OPTIONAL | *object* | Depending upon the `type` attribute, a new resource or the id of a resource. For a type of `create`, the `resource` attribute contains a new FHIR resource to apply within the current activity (e.g. for `medication-prescribe`, this holds the updated prescription as proposed by the suggestion).  For `delete`, this is the id of any resource to remove (e.g. for the `order-review` activity, this would provide a way to remove an order from the pending list). In activities like `medication-prescribe` where only one "content" resource is ever relevant, this field may be omitted. For `update`, this holds the updated resource to modify from the current activity (e.g. for the `order-review` activity, this would provide a way to annotate an order from the pending list with an assessment).
+`description` | REQUIRED | *string* | Human-readable description of the suggested action MAY be presented to the end-user.
+`resource` | OPTIONAL | *object* | Depending upon the `type` attribute, a new resource or the id of a resource. For a type of `create`, the `resource` attribute contains a new FHIR resource to apply within the current activity (e.g. for `medication-prescribe`, this holds the updated prescription as proposed by the suggestion).  For `delete`, this is the id of any resource to remove (e.g. for the `order-review` activity, this would provide a way to remove an order from the pending list). In activities like `medication-prescribe` where only one "content" resource is ever relevant, this field MAY be omitted. For `update`, this holds the updated resource to modify from the current activity (e.g. for the `order-review` activity, this would provide a way to annotate an order from the pending list with an assessment).
 
 #### Link
 
@@ -396,7 +396,7 @@ Each **Link** is described by the following attributes.
 Field | Optionality | Type | Description
 ----- | ----- | ----- | --------
 <nobr>`label`</nobr>| REQUIRED | *string* | Human-readable label to display for this link (e.g. the EHR might render this as the underlined text of a clickable link).
-`url` | REQUIRED | *URL* | URL to load (via `GET`, in a browser context) when a user clicks on this link. Note that this may be a "deep link" with context embedded in path segments, query parameters, or a hash.
+`url` | REQUIRED | *URL* | URL to load (via `GET`, in a browser context) when a user clicks on this link. Note that this MAY be a "deep link" with context embedded in path segments, query parameters, or a hash.
 `type` | REQUIRED | *string* | The type of the given URL. There are two possible values for this field. A type of `absolute` indicates that the URL is absolute and should be treated as-is. A type of `smart` indicates that the URL is a SMART app launch URL and the EHR should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters.
 `appContext` | OPTIONAL | *string* |  An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The `appContext` field should only be valued if the link type is `smart` and is not valid for `absolute` links. The `appContext` field and value will be sent to the SMART app as part of the [OAuth 2.0][OAuth 2.0] access token response, alongside the other [SMART launch parameters](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/#launch-context-arrives-with-your-access_token) when the SMART app is launched. Note that `appContext` could be escaped JSON, base64 encoded XML, or even a simple string, so long as the SMART app can recognize it.
 
@@ -462,17 +462,17 @@ CDS Hooks defines a security model that addresses these risks by assuring that t
 
 ### Trusting CDS Services
 
-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.
+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.
 
 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.
 
-The EHR’s authorization server is responsible for enforcing restrictions on the CDS Services that may be called and the scope of the FHIR resources that may be prefetched or retrieved from the FHIR server.  Therefore, all CDS Services to be called from within an EHR system are pre-registered with the authorization server of that EHR.  Pre-registration includes registering a CDS client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required.
+The EHR’s authorization server is responsible for enforcing restrictions on the CDS Services that MAY be called and the scope of the FHIR resources that MAY be prefetched or retrieved from the FHIR server.  Therefore, all CDS Services to be called from within an EHR system are pre-registered with the authorization server of that EHR.  Pre-registration includes registering a CDS client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required.
 
 ### Trusting EHRs
 
-The service agreement negotiated between the EHR vendor/provider and the CDS Service provider will include obligations the EHR vendor/provider commits to the CDS Service provider. Some agreements may include the use of mutual TLS, in which both ends of the channel are authenticated.
+The service agreement negotiated between the EHR vendor/provider and the CDS Service provider will include obligations the EHR vendor/provider commits to the CDS Service provider. Some agreements MAY include the use of mutual TLS, in which both ends of the channel are authenticated.
 
 However, mutual TLS is impractical for many organizations, and because the EHR initiates the TLS channel set-up, only the CDS Service endpoint will be authenticated.  To enable the CDS Service to authenticate the identity of the EHR, CDS Hooks uses digitally signed [JSON web tokens (JWT)](https://jwt.io/).
 
@@ -497,7 +497,7 @@ The JWT payload contains the following fields:
 
 Field | Optionality | Type | Value
 ----- | ----- | ----- | --------
-iss | REQUIRED | *string* | The URI of the issuer of this JWT.  Note that the JWT may be self-issued by the EHR, or may be issued by a third-party identity provider.
+iss | REQUIRED | *string* | The URI of the issuer of this JWT.  Note that the JWT MAY be self-issued by the EHR, or MAY be issued by a third-party identity provider.
 aud | REQUIRED | *string* or *array of string* | The CDS Service endpoint that is being called by the EHR. (See more details below).
 exp | REQUIRED | *number* | Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC).
 iat | REQUIRED | *number* | The time at which this JWT was issued, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC).