From 87f1f52171a384b4505eb93beb968c004bc0554b Mon Sep 17 00:00:00 2001 From: ashu-ciena <100347291+ashu-ciena@users.noreply.github.com> Date: Thu, 17 Jul 2025 00:28:39 +0530 Subject: [PATCH 1/5] Update gnmi-specification.md Target_Defined mode description Add clarity on using sample-interval in target defined mode. --- rpc/gnmi/gnmi-specification.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index d164ca9..ddbe037 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -978,7 +978,7 @@ The `GetResponse` message consists of: The `Get` RPC is intended for clients to retrieve relatively small sets of data as complete objects, for example a part of the configuration. Such requests are -not expected to put a significant resource burden on the target. Since the +not expected to put a signifit resource burden on the target. Since the target is expected to return the entire snapshot in the `GetResponse` message, `Get` is not well-suited for retrieving very large data sets, such as the full contents of the routing table, or the entire component inventory. For such @@ -1022,7 +1022,7 @@ A SetRequest containing [union_replace](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md) operations MUST NOT contain delete, replace and update operations. -The order of the fields MUST be treated as significant within a +The order of the fields MUST be treated as signifit within a single `SetRequest` message. If a single path is specified multiple times for a single operation (i.e., within `update` or `replace`), then the state of the target MUST reflect the application of all of the operations in order, even if @@ -1034,7 +1034,7 @@ In response to a `SetRequest`, the target MUST respond with a `SetResponse` message. For each operation specified in the `SetRequest` message, an `UpdateResult` message MUST be included in the response field of the `SetResponse`. The order in which the operations are applied MUST be maintained -such that `UpdateResult` messages can be correlated to the `SetRequest` +such that `UpdateResult` messages be correlated to the `SetRequest` operations. In the case of a failure of an operation, the status of the `UpdateResult` message MUST be populated with error information as per the specification in [Section 3.4.7](#347-error-handling). In addition, the status @@ -1327,14 +1327,14 @@ operation within the `SetRequest` the target MUST set the `message` field of the For the operation that the target is unable to process, the code indicated in the status message returned within the RPC response MUST be set to a specific error code indicating the reason for failure based on the following mappings to -canonical gRPC error codes: +onical gRPC error codes: - When the client has specified metadata requiring authentication (see [Section 3.1](#31-session-security-authentication-and-rpc-authorization)), and the authentication fails - `Unauthenticated (16)`. - When the client does not have permission to modify the path specified by the operation - `PermissionDenied (7)`. -- When the operation specifies a path that cannot be parsed by the target - +- When the operation specifies a path that not be parsed by the target - `InvalidArgument (3)`. In this case, the `message` field of the returned status specified SHOULD specify human-readable text indicating that the path could not be parsed. @@ -1370,8 +1370,8 @@ The target generates messages according to the type of subscription that has been created, at the frequency requested by the client. The methods to create subscriptions are described in [Section 3.5.1](#351-managing-subscriptions). -Subscriptions are created for a set of paths - which cannot be modified -throughout the lifetime of the subscription. In order to cancel a subscription, +Subscriptions are created for a set of paths - which not be modified +throughout the lifetime of the subscription. In order to cel a subscription, the client cancels the `Subscribe` RPC associated with the subscription, or terminates the entire gRPC session. @@ -1638,6 +1638,10 @@ with one of the following `modes`: driven (e.g., the changing of state of an entity based on an external trigger) then an `ON_CHANGE` subscription may be created, whereas if other data represents counter values, a `SAMPLE` subscription may be created. + In addition to this, the target MUST select the `sample_interval` for a + `SAMPLE` subscription under this mode, on a per-leaf basis for a fast + periodic response. The target MAY change the `sample_interval` dynamically + without notifying the client. ##### 3.5.1.5.3 POLL Subscriptions From faca2a7759aa636a2c56cbc6fdf012c1db6ba1bf Mon Sep 17 00:00:00 2001 From: ashu-ciena <100347291+ashu-ciena@users.noreply.github.com> Date: Thu, 17 Jul 2025 00:54:28 +0530 Subject: [PATCH 2/5] Fixed some auto-generated spelling issues --- rpc/gnmi/gnmi-specification.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index ddbe037..629644a 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -978,7 +978,7 @@ The `GetResponse` message consists of: The `Get` RPC is intended for clients to retrieve relatively small sets of data as complete objects, for example a part of the configuration. Such requests are -not expected to put a signifit resource burden on the target. Since the +not expected to put a significant resource burden on the target. Since the target is expected to return the entire snapshot in the `GetResponse` message, `Get` is not well-suited for retrieving very large data sets, such as the full contents of the routing table, or the entire component inventory. For such @@ -1022,7 +1022,7 @@ A SetRequest containing [union_replace](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md) operations MUST NOT contain delete, replace and update operations. -The order of the fields MUST be treated as signifit within a +The order of the fields MUST be treated as significant within a single `SetRequest` message. If a single path is specified multiple times for a single operation (i.e., within `update` or `replace`), then the state of the target MUST reflect the application of all of the operations in order, even if @@ -1034,7 +1034,7 @@ In response to a `SetRequest`, the target MUST respond with a `SetResponse` message. For each operation specified in the `SetRequest` message, an `UpdateResult` message MUST be included in the response field of the `SetResponse`. The order in which the operations are applied MUST be maintained -such that `UpdateResult` messages be correlated to the `SetRequest` +such that `UpdateResult` messages can be correlated to the `SetRequest` operations. In the case of a failure of an operation, the status of the `UpdateResult` message MUST be populated with error information as per the specification in [Section 3.4.7](#347-error-handling). In addition, the status @@ -1327,14 +1327,14 @@ operation within the `SetRequest` the target MUST set the `message` field of the For the operation that the target is unable to process, the code indicated in the status message returned within the RPC response MUST be set to a specific error code indicating the reason for failure based on the following mappings to -onical gRPC error codes: +canonical gRPC error codes: - When the client has specified metadata requiring authentication (see [Section 3.1](#31-session-security-authentication-and-rpc-authorization)), and the authentication fails - `Unauthenticated (16)`. - When the client does not have permission to modify the path specified by the operation - `PermissionDenied (7)`. -- When the operation specifies a path that not be parsed by the target - +- When the operation specifies a path that cannot be parsed by the target - `InvalidArgument (3)`. In this case, the `message` field of the returned status specified SHOULD specify human-readable text indicating that the path could not be parsed. @@ -1370,8 +1370,8 @@ The target generates messages according to the type of subscription that has been created, at the frequency requested by the client. The methods to create subscriptions are described in [Section 3.5.1](#351-managing-subscriptions). -Subscriptions are created for a set of paths - which not be modified -throughout the lifetime of the subscription. In order to cel a subscription, +Subscriptions are created for a set of paths - which cannot be modified +throughout the lifetime of the subscription. In order to cancel a subscription, the client cancels the `Subscribe` RPC associated with the subscription, or terminates the entire gRPC session. From bc8ad5e2333aba086c450be1e53c0155ae0c56d8 Mon Sep 17 00:00:00 2001 From: ashu-ciena <100347291+ashu-ciena@users.noreply.github.com> Date: Tue, 29 Jul 2025 12:27:14 +0530 Subject: [PATCH 3/5] Update section for Target Defined mode in gnmi-specification.md Review comments incorporated. --- rpc/gnmi/gnmi-specification.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 629644a..d0e687c 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1638,10 +1638,9 @@ with one of the following `modes`: driven (e.g., the changing of state of an entity based on an external trigger) then an `ON_CHANGE` subscription may be created, whereas if other data represents counter values, a `SAMPLE` subscription may be created. - In addition to this, the target MUST select the `sample_interval` for a - `SAMPLE` subscription under this mode, on a per-leaf basis for a fast - periodic response. The target MAY change the `sample_interval` dynamically - without notifying the client. + In addition to this, the target MAY decide the `sample_interval` for a + `SAMPLE` type of subscription under this mode, on a per-leaf basis. The target + MAY change the `sample_interval` dynamically without notifying the client. ##### 3.5.1.5.3 POLL Subscriptions From cd52813559a62bfa6e659736fda5bb70f57f9559 Mon Sep 17 00:00:00 2001 From: ashu-ciena <100347291+ashu-ciena@users.noreply.github.com> Date: Mon, 8 Sep 2025 18:53:46 +0530 Subject: [PATCH 4/5] Update gnmi-specification.md Incorporated review comments in target-defined mode text change --- rpc/gnmi/gnmi-specification.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index d0e687c..96e59e4 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1638,9 +1638,12 @@ with one of the following `modes`: driven (e.g., the changing of state of an entity based on an external trigger) then an `ON_CHANGE` subscription may be created, whereas if other data represents counter values, a `SAMPLE` subscription may be created. - In addition to this, the target MAY decide the `sample_interval` for a - `SAMPLE` type of subscription under this mode, on a per-leaf basis. The target - MAY change the `sample_interval` dynamically without notifying the client. + When the target chooses a `SAMPLE` type of subscription for a leaf and the + client does not specify the `sample_interval` then target must choose a + `sample_interval` too. In this scenario, The target MAY change the + `sample_interval` dynamically without notifying the client. If the client does + include a `sample_interval` in the subscription request, then the same rules + for processing a `SAMPLE` mode of subscription applies. ##### 3.5.1.5.3 POLL Subscriptions From e4a0da45b6dafb721a2eb40eaee362a59e8d3a3b Mon Sep 17 00:00:00 2001 From: ashu-ciena <100347291+ashu-ciena@users.noreply.github.com> Date: Fri, 14 Nov 2025 15:28:30 +0530 Subject: [PATCH 5/5] Clarification on sample_interval in subscriptions Clarify behavior of sample_interval in TARGET_DEFINED subscriptions. --- rpc/gnmi/gnmi-specification.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 96e59e4..1e9d894 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1638,12 +1638,10 @@ with one of the following `modes`: driven (e.g., the changing of state of an entity based on an external trigger) then an `ON_CHANGE` subscription may be created, whereas if other data represents counter values, a `SAMPLE` subscription may be created. - When the target chooses a `SAMPLE` type of subscription for a leaf and the - client does not specify the `sample_interval` then target must choose a - `sample_interval` too. In this scenario, The target MAY change the - `sample_interval` dynamically without notifying the client. If the client does - include a `sample_interval` in the subscription request, then the same rules - for processing a `SAMPLE` mode of subscription applies. + The target is expected to choose and change a `sample_interval` dynamically. + If `sample_interval` is specified in the subscribe request, the target + `SHOULD` reject the subscription by closing the Subscribe RPC specifying an + `InvalidArgument (3)` error code. ##### 3.5.1.5.3 POLL Subscriptions