freshness review of reference articles

Author: cebundy

articles/azure-web-pubsub/includes/reference-json-requests.md

@@ -18,7 +18,7 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see  [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 ### Leave groups
 
@@ -32,7 +32,7 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 ### Publish messages
 
@@ -49,14 +49,15 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
-* `noEcho` is optional. If set to true, this message is not echoed back to the same connection. If not set, the default value is false.
-* `dataType` can be one of `json`, `text`, or `binary`:
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `noEcho` is optional. If set to true, this message isn't echoed back to the same connection. If not set, the default value is false.
+* `dataType` can be set to `json`, `text`, or `binary`:
      * `json`: `data` can be any type that JSON supports and will be published as what it is; If `dataType` isn't specified, it defaults to `json`.
      * `text`: `data` should be in string format, and the string data will be published;
      * `binary`: `data` should be in base64 format, and the binary data will be published;
 
 #### Case 1: publish text data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -67,7 +68,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -77,9 +79,11 @@ Format:
     "data" : "text data"
 }
 ```
-* What the raw client in this group `<group_name>` receives is string data `text data`.
+
+* The raw clients in `<group_name>` receive the string `text data`.
 
 #### Case 2: publish JSON data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -91,7 +95,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -103,10 +108,11 @@ Format:
     }
 }
 ```
-* What the raw client in this group `<group_name>` receives is serialized string data `{"hello": "world"}`.
 
+* The raw clients in `<group_name>` receive the serialized string `{"hello": "world"}`.
 
 #### Case 3: publish binary data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -117,7 +123,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -127,7 +134,8 @@ Format:
     "data" : "<base64_binary>", 
 }
 ```
-* What the raw client in this group `<group_name>` receives is the **binary** data in the binary frame.
+
+* The raw clients in `<group_name>` receive the **binary** data in the binary frame.
 
 ### Send custom events
 
@@ -143,14 +151,15 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 `dataType` can be one of `text`, `binary`, or `json`:
-* `json`: data can be any type json supports and will be published as what it is; If `dataType` is not specified, it defaults to `json`.
-* `text`: data should be in string format, and the string data will be published;
-* `binary`: data should be in base64 format, and the binary data will be published;
+* `json`: data can be any type json supports and will be published as what it is; The default is `json`.
+* `text`: data is in string format, and the string data will be published;
+* `binary`: data is in base64 format, and the binary data will be published;
 
 #### Case 1: send event with text data:
+
 ```json
 {
     "type": "event",
@@ -161,7 +170,7 @@ Format:
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `text/plain` for `dataType`=`text`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -184,6 +193,8 @@ text data
 
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `text/plain` when `dataType` is `text`.
+
 #### Case 2: send event with JSON data:
 ```json
 {
@@ -197,7 +208,7 @@ text data
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `application/json` for `dataType`=`json`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -222,6 +233,8 @@ ce-eventName: <event_name>
 
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `application/json` when `dataType` is `json`
+
 #### Case 3: send event with binary data:
 ```json
 {
@@ -233,7 +246,7 @@ ce-eventName: <event_name>
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream` for `dataType`=`binary`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -256,6 +269,6 @@ binary
 
 ```
 
-The WebSocket frame can be `text` format for text message frames or UTF8 encoded binaries for `binary` message frames.
+The `Content-Type` for the CloudEvents HTTP request is `application/octet-stream` when `dataType` is `binary`.  The WebSocket frame can be `text` format for text message frames or UTF8 encoded binaries for `binary` message frames.
 
-Service declines the client if the message does not match the described format.
+The Web PubSub service declines the client if the message doesn't match the described format.

articles/azure-web-pubsub/includes/reference-permission.md

@@ -8,14 +8,14 @@ ms.date: 08/06/2021
 
 ## Permissions
 
-You may have noticed that when we describe the PubSub WebSocket clients, a client can publish to other clients only when it's *authorized* to. The `role`s of the client determines the *initial* permissions the client have:
+A Web PubSub WebSocket client can only publish to other clients when it's authorized to. The `roles` assigned to the client determine the initial permissions granted to the client:
 
 | Role | Permission |
 |---|---|
 | Not specified | The client can send event requests.
 | `webpubsub.joinLeaveGroup` | The client can join/leave any group.
 | `webpubsub.sendToGroup` | The client can publish messages to any group.
-| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave group `<group>`.
-| `webpubsub.sendToGroup.<group>` | The client can publish messages to group `<group>`.
+| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave the group `<group>`.
+| `webpubsub.sendToGroup.<group>` | The client can publish messages to the group `<group>`.
 
-The server-side can also grant or revoke permissions of the client dynamically through REST APIs or server SDKs.
+The server can also dynamically grant or revoke permissions from the client through REST APIs or server SDKs.

articles/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol.md

@@ -5,7 +5,7 @@ author: zackliu
 ms.author: chenyl
 ms.service: azure-web-pubsub
 ms.topic: conceptual 
-ms.date: 11/06/2021
+ms.date: 01/04/2023
 ---
 
 #  Azure Web PubSub supported Reliable JSON WebSocket subprotocol
@@ -26,7 +26,7 @@ For example, in JS, a Reliable PubSub WebSocket client can be created using:
 var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.reliable.webpubsub.azure.v1');
 ```
 
-When using `json.reliable.webpubsub.azure.v1` subprotocol, the client must follow the [How to create reliable clients](./howto-develop-reliable-clients.md) to implement reconnection, publisher and subscriber.
+When using `json.reliable.webpubsub.azure.v1` subprotocol, see [How to create reliable clients](./howto-develop-reliable-clients.md) to implement reconnection, publisher and subscriber for clients.
 
 [!INCLUDE [reference-permission](includes/reference-permission.md)]
 
@@ -45,13 +45,13 @@ Format:
 }
 ```
 
-Reliable PubSub WebSocket client must send sequence ack message once it received a message from the service. Find more in [How to create reliable clients](./howto-develop-reliable-clients.md#subscriber)
+Reliable PubSub WebSocket client must send a sequence ack message once it receives a message from the service. Find more in [How to create reliable clients](./howto-develop-reliable-clients.md#subscriber)
 
 * `sequenceId` is a incremental uint64 number from the message received.
 
 ## Responses
 
-Messages received by the client can be several types: `ack`, `message`, and `system`. Messages with type `message` have `sequenceId` property. Client must send [Sequence Ack](#sequence-ack) to the service once it receives a message.
+Messages received by the client can be several types: `ack`, `message`, and `system`. Messages with type `message` have `sequenceId` property. Client must send a [Sequence Ack](#sequence-ack) to the service once it receives a message.
 
 ### Ack response
 

articles/azure-web-pubsub/reference-json-webpubsub-subprotocol.md

@@ -4,26 +4,30 @@ description: The reference describes Azure Web PubSub supported WebSocket subpro
 author: vicancy
 ms.author: lianwei
 ms.service: azure-web-pubsub
-ms.topic: conceptual 
-ms.date: 11/06/2021
+ms.topic: reference 
+ms.date: 01/06/2023
 ---
 
-#  Azure Web PubSub supported JSON WebSocket subprotocol
-     
-This document describes the subprotocol `json.webpubsub.azure.v1`.
+# Azure Web PubSub supported JSON WebSocket subprotocol
+
+The JSON WebSocket subprotocol, `json.webpubsub.azure.v1`, enables the exchange of publish/subscribe messages directly between clients.  A WebSocket connection using the `json.webpubsub.azure.v1` subprotocol is called a PubSub WebSocket client.
 
-When the client is using this subprotocol, both outgoing data frame and incoming data frame are expected to be **JSON** payloads.
+This document describes the subprotocol `json.webpubsub.azure.v1`.
 
 ## Overview
 
-Subprotocol `json.webpubsub.azure.v1` empowers the clients to do publish/subscribe directly instead of a round trip to the upstream server. We call the WebSocket connection with `json.webpubsub.azure.v1` subprotocol a PubSub WebSocket client.
+In a simple native WebSocket client, a *server* role is required to handle events from clients. A simple WebSocket connection triggers a `message` event when it sends messages, and relies on the server-side to process messages and do other operations. 
+
+When you use the `json.webpubsub.azure.v1` subprotocol, an authorized client can join a group using [join requests](#join-groups) and publish messages directly to a group using [publish requests](#publish-messages). The client can also route messages directly to upstream event handlers using [event requests](#send-custom-events).
 
-For example, in JS, a PubSub WebSocket client can be created using:
-```js
+In JavaScript, a PubSub WebSocket client can be created using:
+
+```javascript
 // PubSub WebSocket client
 var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
 ```
-For a simple WebSocket client, the *server* is a MUST HAVE role to handle the events from clients. A simple WebSocket connection always triggers a `message` event when it sends messages, and always relies on the server-side to process messages and do other operations. With the help of the `json.webpubsub.azure.v1` subprotocol, an authorized client can join a group using [join requests](#join-groups) and publish messages to a group using [publish requests](#publish-messages) directly. It can also route messages to different upstream (event handlers) by customizing the *event* the message belongs using [event requests](#send-custom-events).
+
+ The following information describes the subprotocol requests and responses.  Both incoming and outgoing data frames must contain JSON payloads.
 
 [!INCLUDE [reference-permission](includes/reference-permission.md)]
 
@@ -33,13 +37,18 @@ For a simple WebSocket client, the *server* is a MUST HAVE role to handle the ev
 
 ## Responses
 
-Messages received by the client can be several types: `ack`, `message`, and `system`: 
+Messages received by the client can be `ack`, `message`, and `system`:
+
+* ack - The response to a request containing an `ackId`.
+* message - Messages from the group or server.
+* system - Responses from the Web PubSub service to system related client requests.
 
 ### Ack response
 
-If the request contains `ackId`, the service will return an ack response for this request. The client implementation should handle this ack mechanism, including waiting for the ack response for an `async` `await` operation, and having a timeout check when the ack response is not received during a certain period.
+When the client request contains `ackId`, the service will return an ack response for the request. The client should handle the ack mechanism, by waiting for the ack response with an `async` `await` operation and a using a timeout operation when the ack response isn't received in a certain period.
 
 Format:
+
 ```json
 {
     "type": "ack",
@@ -52,11 +61,11 @@ Format:
 }
 ```
 
-The client implementation SHOULD always check if the `success` is `true` or `false` first. Only when `success` is `false` the client reads from `error`.
+The client implementation SHOULD always check if the `success` is `true` or `false` first, then only read the error when `success` is `false`.
 
 ### Message response
 
-Clients can receive messages published from one group the client joined, or from the server management role that the server sends messages to the specific client or the specific user.
+Clients can receive messages published from a group the client has joined or from the server. 
 
 1. When the message is from a group
 
@@ -71,7 +80,7 @@ Clients can receive messages published from one group the client joined, or from
     }
     ```
 
-1. When The message is from the server.
+1. When the message is from the server.
 
     ```json
     {
@@ -83,8 +92,11 @@ Clients can receive messages published from one group the client joined, or from
     ```
 
 #### Case 1: Sending data `Hello World` to the connection through REST API with `Content-Type`=`text/plain` 
-* What a simple WebSocket client receives is a text WebSocket frame with data: `Hello World`;
-* What a PubSub WebSocket client receives is as follows:
+
+
+* A simple WebSocket client receives a text WebSocket frame with data: `Hello World`;
+* A PubSub WebSocket client receives:
+
     ```json
     {
         "type": "message",
@@ -95,8 +107,10 @@ Clients can receive messages published from one group the client joined, or from
     ```
 
 #### Case 2: Sending data `{ "Hello" : "World"}` to the connection through REST API with `Content-Type`=`application/json`
-* What a simple WebSocket client receives is a text WebSocket frame with stringified data: `{ "Hello" : "World"}`;
-* What a PubSub WebSocket client receives is as follows:
+
+* A simple WebSocket client receives a text WebSocket frame with stringified data: `{ "Hello" : "World"}`.
+* A PubSub WebSocket client receives:
+
     ```json
     {
         "type": "message",
@@ -108,11 +122,13 @@ Clients can receive messages published from one group the client joined, or from
     }
     ```
 
-If the REST API is sending a string `Hello World` using `application/json` content type, what the simple WebSocket client receives is a JSON string, which is `"Hello World"` that wraps the string with `"`.
+If the REST API is sending a string `Hello World` using `application/json` content type, the simple WebSocket client receives a JSON string, which is `"Hello World"` wrapped with double quotes (`"`).
 
 #### Case 3: Sending binary data to the connection through REST API with `Content-Type`=`application/octet-stream`
-* What a simple WebSocket client receives is a binary WebSocket frame with the binary data.
-* What a PubSub WebSocket client receives is as follows:
+
+* A simple WebSocket client receives a binary WebSocket frame with the binary data.
+* A PubSub WebSocket client receives:
+
     ```json
     {
         "type": "message",
@@ -124,11 +140,11 @@ If the REST API is sending a string `Hello World` using `application/json` conte
 
 ### System response
 
-The Web PubSub service can also send system-related responses to the client. 
+The Web PubSub service sends system related responses to client requests. 
 
 #### Connected
 
-When the connection connects to service.
+The responses when the client connects to service.
 
 ```json
 {
@@ -141,7 +157,7 @@ When the connection connects to service.
 
 #### Disconnected
 
-When the server closes the connection, or when the service declines the client.
+The response when the server closes the connection, or when the service declines the client.
 
 ```json
 {