HL7 · isaacvetter · Jun 28, 2022 · May 2, 2022 · Jun 21, 2022 · Jun 21, 2022
diff --git a/input/pagecontent/2-1-SessionDiscovery.md b/input/pagecontent/2-1-SessionDiscovery.md
@@ -4,4 +4,4 @@ A session is an abstract concept representing a shared workspace, such as user's
 
 Systems SHOULD use SMART on FHIR to authorize, authenticate, and exchange initial shared context. If using SMART, following a [SMART on FHIR EHR launch](http://www.hl7.org/fhir/smart-app-launch#ehr-launch-sequence) or [SMART on FHIR standalone launch](http://www.hl7.org/fhir/smart-app-launch/#standalone-launch-sequence), the app SHALL request and, if authorized, SHALL be granted one or more [FHIRcast OAuth 2.0 scopes](2-2-FhircastScopes.html). Accompanying this scope grant, the authorization server SHALL supply the `hub.url` and `hub.topic` SMART launch parameters alongside the access token and other parameters appropriate to establish initial shared context. Per SMART, when the `openid` scope is granted, the authorization server additionally sends the current user's identity in an `id_token`.
 
-Although FHIRcast works best with the SMART on FHIR launch and authorization process, implementation-specific launch, authentication, and authorization protocols may be possible. If not using SMART on FHIR, the mechanism enabling the app to discover the `hub.url` and `hub.topic` is not defined in FHIRcast. See [other launch scenarios](4-1-launch-scenarios.html) for guidance.
+Although FHIRcast works best with the SMART on FHIR launch and authorization process, implementation-specific launch, authentication, and authorization protocols may be possible. If not using SMART on FHIR, the mechanism enabling the app to discover the `hub.url` and `hub.topic` is not defined in FHIRcast. See [other launch scenarios](4-1-launch-scenarios.html#alternate-app-launch) for guidance.
diff --git a/input/pagecontent/2-3-Events.md b/input/pagecontent/2-3-Events.md
@@ -6,7 +6,7 @@ FHIRcast context events do not communicate previous contexts. For a given event,
 
 ### Event Definition Format
 
-Each event definition: specifies a single event name, a description of the workflow in which the event occurs, and contextual information associated with the event. FHIR is the interoperable data model used by FHIRcast. The context information associated with an event is communicated as subsets of FHIR resources. Event notifications SHALL include the elements of the FHIR resources defined in the context from the event definition. Event notifications MAY include other elements of these resources.
+Each event definition specifies a single event name, a description of the workflow in which the event occurs, and contextual information associated with the event. FHIR is the interoperable data model used by FHIRcast. The context information associated with an event is communicated as subsets of FHIR resources. Event notifications SHALL include the elements of the FHIR resources defined in the context from the event definition. Event notifications MAY include other elements of these resources.
 
 All events are documents in the [standard event catalog](3_Events.html) and SHALL be defined in the following format.
 
@@ -25,10 +25,10 @@ The event name defines the event. Most FHIRcast events conform to an extensible
 
 Patterned after the SMART on FHIR scope syntax and expressed in EBNF notation, the FHIRcast syntax for context change related events is:
 
-The `fhir-resource` indicates the focus of the event; the `suffix` defines the type of event.
-
 {% include img.html img="events-railroad.png" caption="Figure: Syntax for FHIRcast events" %}
 
+The `fhir-resource` indicates the focus of the event; the `suffix` defines the type of event.
+
 Event names are unique and case-insensitive. Implementers may define their own events. Such proprietary events SHALL be named with reverse domain notation (e.g. `org.example.patient_transmogrify`). Reverse domain notation SHALL NOT be used by a standard event catalog. Proprietary events SHALL NOT contain a dash ("-").
 
 When subscribing to FHIRcast events a list of events is added. These events may contain wild cards. Wild cards are expressed as a `*` replacing either the `fhir-resource` or `suffix`  with `*` indicates any events that match the resulting definition are requested. The event `*` means the subscriber subscribes to any event. The table below shows some typical examples.
@@ -92,7 +92,7 @@ Selection events use the suffix `select`. The format of selection events is:
 
 `hub.events ::= ( fhir-resource  ) '-' ( select )`
 
-The `fhir-resource` indicates the context of the selection. The `context` element in a select event typically contains two fields. One with the name of the `fhir-resource` holding a the anchor resource and one or more named `select` indicating the resources that is selected.
+The `fhir-resource` indicates the context of the selection. The `context` element in a select event typically contains two fields. One with the name of the `fhir-resource` holding the anchor resource and one or more named `select` indicating the resources that are selected.
 
 
-This allows of communication of different select sets for the different anchor-types.
+This allows communication of different select sets for the different anchor-types.
diff --git a/input/pagecontent/2-4-Subscribing.md b/input/pagecontent/2-4-Subscribing.md
@@ -37,7 +37,8 @@ Field | Optionality | Channel | Type | Description
 
 If OAuth 2.0 authentication is used, this POST request SHALL contain the Bearer access token in the HTTP Authorization header.
 
-Hubs SHALL allow subscribers to re-request subscriptions that are already activated. Each subsequent and verified request to a Hub to subscribe or unsubscribe SHALL override the previous subscription state for a specific `hub.topic`, `hub.callback` / `hub.channel.endpoint` url combination. For example, a subscriber MAY modify its subscription by sending a subscription request (`hub.mode=subscribe`) with a different `hub.events` value with the same topic and callback/endpoint url, in which case the Hub SHALL replace the subscription’s previous `hub.events` with the newly provided list of events.
+Hubs SHALL allow subscribers to re-request subscriptions that are already activated. Each subsequent and verified request to a Hub to subscribe or unsubscribe SHALL override the previous subscription state for a specific (`hub.topic`, `hub.callback`) combination or (`hub.topic`, `hub.channel.endpoint` url) combination. For example, a subscriber MAY modify its subscription by sending a subscription request (`hub.mode=subscribe`) with a different `hub.events` value with the same topic and callback/endpoint url, in which case the Hub SHALL replace the subscription’s previous `hub.events` with the newly provided list of events.
+
 
 For `webhook` subscriptions, the callback URL MAY contain arbitrary query string parameters (e.g., `?foo=bar&red=fish`). Hubs SHALL preserve the query string during subscription verification by appending new, Hub-defined, parameters to the end of the list using the `&` (ampersand) character to join. When sending event notifications, the Hub SHALL make a POST request to the callback URL including any query string parameters in the URL portion of the request, not as POST body parameters.
 
@@ -71,7 +72,7 @@ hub.channel.type=webhook&hub.callback=https%3A%2F%2Fapp.example.com%2Fsession%2F
 
 ### Subscription Response
 
-Upon receiving subscription or unsubscription requests, the Hub SHALL respond to a subscription request with an HTTP 202 "Accepted" response. This indicates that the request was received and will now be verified by the Hub. When using WebSockets, the HTTP body of the response SHALL consist of a JSON object containing an element name of `hub.channel.endpoint` and a value of the WSS URL. The WebSocket WSS URL SHALL be cryptographically random, unique, and unguessable. If using webhooks, the Hub SHOULD perform verification of intent as soon as possible.
+Upon receiving subscription or unsubscription requests, the Hub SHALL respond to a subscription request with an HTTP 202 "Accepted" response. This indicates that the request was received and will now be verified by the Hub. When using WebSockets, the HTTP body of the response SHALL consist of a JSON object containing an element name of `hub.channel.endpoint` and a value for the WSS URL. The WebSocket WSS URL SHALL be cryptographically random, unique, and unguessable. If using webhooks, the Hub SHOULD perform verification of intent as soon as possible.
 
 If a Hub refuses the request or finds any errors in the subscription request, an appropriate HTTP error response code (4xx or 5xx) SHALL be returned. In the event of an error, the Hub SHOULD return a description of the error in the response body as plain text, to be used by the client developer to understand the error. This is not meant to be shown to the end user. Hubs MAY decide to reject some subscription requests based on their own policies.
 

diff --git a/input/pagecontent/2-5-EventNotification.md b/input/pagecontent/2-5-EventNotification.md
@@ -2,14 +2,16 @@ The Hub SHALL notify subscribed apps of workflow-related events to which the app
 
 ### Event Notification Request
 
-The HTTP request notification interaction to the subscriber SHALL include a description of the subscribed event that just occurred, an ISO 8601-2 formatted timestamp in UTC and an event identifier that is universally unique for the Hub. The timestamp SHOULD be used by subscribers to establish message affinity (message ordering) through the use of a message queue. Subscribers SHALL ignore messages with older timestamps than the message that established the current context. The event identifier MAY be used to differentiate retried messages from user actions.
+The HTTP request notification interaction include the following fields:
 
 Field | Optionality | Type | Description
 --- | --- | --- | ---
 `timestamp` | Required | *string* | ISO 8601-2 timestamp in UTC describing the time at which the event occurred.
 `id` | Required | *string* | Event identifier used to recognize retried notifications. This id SHALL be unique for the Hub, for example a UUID.
 `event` | Required | *object* | A JSON object describing the event see [Event Definition](2-3-Events.html).
 
+The timestamp SHOULD be used by subscribers to establish message affinity (message ordering) through the use of a message queue. Subscribers SHALL ignore messages with older timestamps than the message that established the current context. The event identifier MAY be used to differentiate retried messages from user actions.
+
 #### `webhook` Event Notification Request Details
 
 For `webhook` subscriptions, the Hub SHALL generate an HMAC signature of the payload (using the `hub.secret` from the subscription request) and include that signature in the request headers of the notification. The `X-Hub-Signature` header's value SHALL be in the form *method=signature* where method is one of the recognized algorithm names and signature is the hexadecimal representation of the signature. The signature SHALL be computed using the HMAC algorithm ([RFC6151](https://www.w3.org/TR/websub/#bib-RFC6151)) with the request body as the data and the `hub.secret` as the key.
@@ -62,7 +64,7 @@ For both `webhook` and `websocket` subscriptions, the event notification content
 
 ### Event Notification Response
 
-The subscriber SHALL respond to the event notification with an appropriate HTTP status code. In the case of a successful notification, the subscriber SHALL respond with an any of the response codes indicated below:
+The subscriber SHALL respond to the event notification with an appropriate HTTP status code. In the case of a successful notification, the subscriber SHALL respond with any of the response codes indicated below:
 HTTP 200 (OK) or 202 (Accepted) response code to indicate a success; otherwise, the subscriber SHALL respond with an HTTP error status code.
 
 Code  |        | Description
@@ -117,9 +119,7 @@ The figure below illustrates the `webhook` and `websocket` Event Notification Er
 
 More information on the source of notification errors and how to resolve them can be found in [Synchronization Considerations](4-2-syncconsiderations.html).
 
-More information on the source of notification errors and how to resolve them can be found in [Synchronization Considerations](4-2-syncconsiderations.html).
-
-## Hub Generated `syncerror` Events
+### Hub Generated `syncerror` Events
 
 In addition to distributing [`syncerror`](3-2-1-syncerror.html) events sent by one application to other subscribed applications, the Hub MAY generate and communicate [`syncerror`](3-2-1-syncerror.html) events to applications under the following conditions -- 
 

diff --git a/input/pagecontent/2-7-Conformance.md b/input/pagecontent/2-7-Conformance.md
@@ -15,7 +15,7 @@ Field | Optionality | Type | Description
 `websocketSupport` | Required | boolean | The static value: `true`, indicating support for websockets.
 `webhookSupport` | Optional | boolean | `true` or `false` indicating support for webhooks. Hubs SHOULD indicate their support for web hooks. 
 `fhircastVersion` | Optional | string | `STU1` or `STU2` or `STU3` indicating support for a specific version of FHIRcast. Hubs SHOULD indicate the version of FHIRcast supported. 
-`getCurrentSupport` | Optional | boolean | `true` or `false` indicating support for the [Get Current Context](2-9-GetCurrentContext.html) API. 
+`getCurrentSupport` | Optional | boolean | `true` or `false` indicating support for the "[Get Current Context](2-9-GetCurrentContext.html)" API. 
 
 #### Wellknown endpoint discovery example
 
@@ -64,7 +64,7 @@ Extension | Cardinality | Type | Description
             "extension": [
               {
                 "url": "hub.url",
-                "valueUri": "https://hub.example.com/fhircast/hub.v2"
+                "valueUri": "https://hub.example.com/fhircast/hub"
               }
             ]
           }

diff --git a/input/pagecontent/3-1-1-template.md b/input/pagecontent/3-1-1-template.md
@@ -4,11 +4,11 @@ This section presents the template to use for defining new events.
 
 eventMaturity | [0 - Draft](3-1-2-eventmaturitymodel.html)
 
-#### Workflow
+### Workflow
 
 Describe when this event occurs in a workflow. Describe how the context fields relate to one another. Event creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion amongst implementors.
 
-#### Context
+### Context
 
 Define context values that are provided when this event occurs, and indicate whether they must be provided, and the FHIR query used to generate the resource.
 
@@ -17,7 +17,7 @@ Key | Optionality | FHIR operation to generate context | Description
 `example` | REQUIRED | `FHIRresource/{id}?_elements=identifer` | Describe the context value
 `encounter` | OPTIONAL | `Encounter/{id}` | Describe the context value
 
-#### Examples
+### Examples
 
 ```json
 {

diff --git a/input/pagecontent/3-1-2-eventmaturitymodel.md b/input/pagecontent/3-1-2-eventmaturitymodel.md
@@ -6,7 +6,7 @@ Maturity Level | Maturity title | Requirements
 1 | Submitted  | _The above, and …_ Event definition is written up as a pull request using the [Event template](3-1-1-template.html) and community feedback is solicited from the community (e.g. the zulip FHIRcast stream](https://chat.fhir.org/#narrow/stream/179271-FHIRcast)).
 2 | Tested | _The above, and …_ The event has been tested and successfully supports interoperability among at least one Hub and two independent subscribing apps using semi-realistic data and scenarios (e.g. at a FHIR Connectathon). The github pull request defining the event is approved and published.
 3 | Considered |  _The above, and …_ At least 3 distinct organizations recorded ten distinct implementer comments (including a github or jira issue, tracker item, or comment on the event definition page), including at least two Hubs and three subscribing apps. The event has been tested at two Connectathons.
-4 | Documented | _The above, and …_ The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes.  The event is implemented in the standard FHIRcast reference implementation and multiple prototype projects. The Event specification SHALL: <ul><ol>Identify a broad set of example contexts in which the event may be used with a minimum of three, but as many as 10.</ol><ol>Clearly differentiate the event from similar events or other standards to help an implementer determine if the event is correct for their scenario.</ol><ol>Explicitly document example scenarios when the event should not be used.</ol></ul>
+4 | Documented | _The above, and …_ The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes.  The event is implemented in the standard FHIRcast reference implementation and multiple prototype projects. The Event specification SHALL: <ul><li>Identify a broad set of example contexts in which the event may be used with a minimum of three, but as many as 10.</li><li>Clearly differentiate the event from similar events or other standards to help an implementer determine if the event is correct for their scenario.</li> <li>Explicitly document example scenarios when the event should not be used.</li> </ul>
 5 | Mature | _The above, and ..._ The event has been implemented in production in at least two Hubs and three independent subscribing apps. An HL7 working group ballots the event and the event has passed HL7 STU ballot.
 6 | Normative | _The above, and ..._ the responsible HL7 working group and the sponsoring working group agree the material is ready to lock down and the event has passed HL7 normative ballot
 

diff --git a/input/pagecontent/3-2-1-syncerror.md b/input/pagecontent/3-2-1-syncerror.md
@@ -12,7 +12,7 @@ Unlike most of FHIRcast events, `syncerror` is an infrastructural event and does
 
 An array containing a single FHIR OperationOutcome. The OperationOutcome SHALL use a code of `processing`. The OperationOutcome's details SHALL contain the id of the event that this error is related to as a `code` with the `system` value of `https://fhircast.hl7.org/events/syncerror/eventid` and the name of the relevant event with a `system` value of `https://fhircast.hl7.org/events/syncerror/eventname`. Other `coding` values can be included with different `system` values so as to include extra information about the `syncerror`. The OperationOutcome's `diagnostics` element should contain additional information to aid subsequent investigation or presentation to the end-user.
 
-Key | Optionality | Fhir operation to generate context | Description
+Key | Optionality | FHIR operation to generate context | Description
 ----- | -------- | ---- | ---- 
 `operationoutcome` | OPTIONAL | `OperationOutcome` | FHIR resource describing an outcome of an unsuccessful system action.
 

diff --git a/input/pagecontent/3-2-2-heartbeat.md b/input/pagecontent/3-2-2-heartbeat.md
@@ -35,7 +35,7 @@ An example heartbeat event is indicated below.
     "hub.event":"heartbeat"
   }
 }
-
+````
 
 ### Change Log
 

diff --git a/input/pagecontent/3-3-1-patient-open.md b/input/pagecontent/3-3-1-patient-open.md
@@ -4,11 +4,11 @@ eventMaturity | [2 - Tested](3-1-2-eventmaturitymodel.html)
 
 ### Workflow
 
-User opened patient's medical record. Only a single patient is currently in context.  
+User opened patient's medical record. The indicated patient is the current patient in context. 
 
 ### Context
 
-Key | Optionality | Fhir operation to generate context | Description
+Key | Optionality | FHIR operation to generate context | Description
 ----- | -------- | ---- | ---- 
 `patient` | REQUIRED | `Patient/{id}?_elements=identifier` | FHIR Patient resource describing the patient whose chart is currently in context.
 ~~`encounter`~~ | ~~REQUIRED, if exists~~ | ~~`Encounter/{id}?_elements=identifier`~~ | ~~FHIR Encounter resource in context in the newly opened patient's chart.~~ DEPRECATED in favor of a dedicated `encounter-open` event. 

diff --git a/input/pagecontent/3-3-2-patient-close.md b/input/pagecontent/3-3-2-patient-close.md
@@ -8,7 +8,7 @@ User closed patient's medical record. A previously open and in context patient c
 
 ### Context
 
-Key | Optionality | Fhir operation to generate context | Description
+Key | Optionality | FHIR operation to generate context | Description
 ----- | -------- | ---- | ---- 
 `patient` | REQUIRED | `Patient/{id}?_elements=identifier` | FHIR Patient resource describing the patient whose chart was previously in context.
 ~~`encounter`~~ | ~~REQUIRED, if exists~~ | ~~`Encounter/{id}?_elements=identifier`~~ | ~~FHIR Encounter resource previously in context in the now closed patient's chart.~~ DEPRECATED in favor of dedicated `encounter-close` event.
@@ -48,7 +48,7 @@ Key | Optionality | Fhir operation to generate context | Description
 }
 ```
 
-## Change Log
+### Change Log
 
 Version | Description
 ---- | ----