Add behaviour tables for GetResponse and SubscribeResponse

Fixes #142 and #155
openconfig · Jul 6, 2022 · 27efa09 · 27efa09
1 parent 8684078
commit 27efa09
Showing 1 changed file with 23 additions and 3 deletions.
diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md
@@ -38,8 +38,9 @@ April 28, 2022
     * [3.2.2 The CapabilityResponse message](#322-the-capabilityresponse-message)
   * [3.3 Retrieving Snapshots of State Information](#33-retrieving-snapshots-of-state-information)
     * [3.3.1 The GetRequest Message](#331-the-getrequest-message)
-    * [3.3.2 The GetResponse message](#332-the-getresponse-message)
+    * [3.3.2 The GetResponse Message](#332-the-getresponse-message)
     * [3.3.3 Considerations for using Get](#333-considerations-for-using-get)
+    * [3.3.4 GetResponse Behaviour Table](#333-getresponse-behaviour-table)
   * [3.4 Modifying State](#34-modifying-state)
     * [3.4.1 The SetRequest Message](#341-the-setrequest-message)
     * [3.4.2 The SetResponse Message](#342-the-setresponse-message)
@@ -53,14 +54,15 @@ April 28, 2022
       * [3.5.1.1 The SubscribeRequest Message](#3511-the-subscriberequest-message)
       * [3.5.1.2 The SubscriptionList Message](#3512-the-subscriptionlist-message)
       * [3.5.1.3 The Subscription Message](#3513-the-subscription-message)
-      * [3.5.1.4 The SubscribeResponse Message](#3514-the-subscriberesponse-message)
+  * [3.5.1.4 The SubscribeResponse Message](#3514-the-subscriberesponse-message)
       * [3.5.1.5 Creating Subscriptions](#3515-creating-subscriptions)
         * [3.5.1.5.1 ONCE Subscriptions](#35151-once-subscriptions)
         * [3.5.1.5.2 STREAM Subscriptions](#35152-stream-subscriptions)
         * [3.5.1.5.3 POLL Subscriptions](#35153-poll-subscriptions)
     * [3.5.2 Sending Telemetry Updates](#352-sending-telemetry-updates)
       * [3.5.2.1 Bundling of Telemetry Updates](#3521-bundling-of-telemetry-updates)
       * [3.5.2.3 Sending Telemetry Updates](#3523-sending-telemetry-updates)
+      * [3.5.2.4 SubscribeResponse Behaviour Table](#3523-subscriberesponse-behaviour-table)
 * [4 Appendix: Current Protobuf Message and Service Specification](#4-appendix-current-protobuf-message-and-service-specification)
 * [5 Appendix: Current Outstanding Issues/Future Features](#5-appendix-current-outstanding-issuesfuture-features)
 * [6 Copyright](#6-copyright)
@@ -866,7 +868,7 @@ The types of data currently defined are:
 If the `type` field is not specified, the target MUST return CONFIG, STATE  and
 OPERATIONAL data fields in the tree resulting from the client's query.
 
-### 3.3.2 The GetResponse message
+### 3.3.2 The GetResponse Message
 
 The `GetResponse` message consists of:
 
@@ -898,6 +900,15 @@ accuracy for individual data items, the `Subscribe` RPC is recommended to
 request a telemetry stream (see [Section
 3.5.2](#352-sending-telemetry-updates)).
 
+### 3.3.4 GetResponse Behaviour Table
+
+| GetRequest Scenario                                                                                                     | Target Behaviour |
+| ----------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1) | Value is returned |
+| Subscribed paths are syntactically correct but one or more paths do not (yet) exist                                     | Return `NOT_FOUND` |
+| Subscribed paths are syntactically correct but one or more paths is not implemented by the server                       | Return `UNIMPLEMENTED` |
+| One or more subscribed paths is syntactically incorrect                                                                 | Return `INVALID_ARGUMENT` |
+
 ## 3.4 Modifying State
 
 Modifications to the state of the target are made through the `Set` RPC. A
@@ -1535,6 +1546,15 @@ by any updates representing subsequent changes to current state. For a `POLL` or
 `updates_only` field allows a client to only watch for changes, e.g. an update
 to configuration.
 
+#### 3.5.2.4 SubscribeResponse Behaviour Table
+
+| Subscription Scenario                                                                                                   | ONCE                                     | POLL                                     | STREAM |
+| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------- | ------ |
+| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1) | Value is returned                        | Value is returned                        | Value is returned |
+| Subscribed paths are syntactically correct but one or more paths do not (yet) exist                                     | No value returned for non-existent paths | No value returned for non-existent paths | nothing is sent for non-existent paths (yet), RPC is not closed |
+| Subscribed paths are syntactically correct but one or more paths is not implemented by the server                       | Return `UNIMPLEMENTED`                   | Return `UNIMPLEMENTED`                   | Return `UNIMPLEMENTED` |
+| One or more subscribed paths is syntactically incorrect                                                                 | Return `INVALID_ARGUMENT`                | Return `INVALID_ARGUMENT`                | Return `INVALID_ARGUMENT` |
+
 # 4 Appendix: Current Protobuf Message and Service Specification
 
 The latest Protobuf IDL gNMI specification is found in GitHub at