From 0aa10d6464a8a33b3c30dca68dad409e5784b3a7 Mon Sep 17 00:00:00 2001 From: Ebben Aries Date: Fri, 18 Nov 2022 10:30:15 -0700 Subject: [PATCH 1/3] Adjust gNMI SetRequest Update handling for list keys + value payloads --- rpc/gnmi/gnmi-specification.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 424f189..c0a2ec2 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -4,10 +4,10 @@ Paul Borman, Marcus Hines, Carl Lebsack, Chris Morrow, Anees Shaikh, Rob Shakir **Date:** -July 7, 2022 +Nov 18, 2022 **Version:** -0.8.1 +0.9.0 # Table of Contents @@ -1133,19 +1133,23 @@ root + The path convention defined in [Section 2.2.2](#222-paths) allows nodes in the data tree to be identified by a unique set of node names (e.g.,` /a/b/c/d`) or paths that consist of node names coupled with attributes (e.g., `/a/e[key=10]`). -In the case where where a node name plus attribute name is required to uniquely -identify an element (i.e., the path within the schema represents a list, map, or -array), the following considerations apply: +In the case where a node name plus attribute name is required to uniquely +identify an element (i.e., the path within the schema represents a list, map, +or array), the following considerations apply: * In the case that multiple attribute values are required to uniquely address an element - e.g., `/a/f[k1=10][k2=20] `- and a replace or update operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) then this MUST be considered an error by the target system - and an status code of` InvalidArgument (3)` specified. -* In the case that key values are specified both as attributes of a node, and - as their own elements within the data tree, update or replace operations - that modify instances of the key in conflicting ways MUST be considered an - error. The target MUST return a status code of `InvalidArgument (3)`. +* In the case that key values are specified both as attributes of a node in the + path, and as their own elements within the value, then this MUST be considered + an error by the target system - and a status code of `InvalidArgument (3)` + specified. Targeting a list member with update or replace operations that + modify it's own keys in either conflicting or identical fashion is not + permitted thus they must be omitted from the value payload. This holds true + for the direct descendant list key nodes as well as the ultimate leafref'd + nodes per OpenConfig [style guidelines](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list). For example, consider a tree corresponding to the examples above, as illustrated below. @@ -1169,8 +1173,8 @@ root + In this case, nodes `k1` and `k2` are standalone nodes within the schema, but also correspond to attribute values for the node "`f`". In this case, an update or replace message specifying a path of `/a/f[k1=10][k2=20]` setting the value -of `k1` to 100 MUST be considered erroneous, and a status code of -`InvalidArgument (3)` specified. +of `k1` to either the same value (10) or an alternate value (100) MUST be +considered erroneous, and a status code of `InvalidArgument (3)` specified. ### 3.4.6 Deleting Configuration @@ -1653,6 +1657,10 @@ limitations under the License # 7 Revision History +* v0.9.0: Nov 18, 2022 + * Clarify that for `Set`, that if targeting a path by list keys that the + list keys cannot be included within the value payload + * v0.8.1: July 7, 2022 * Clarify that for `Subscribe`, a transition to a YANG default value for a leaf must use `update` rather than just a `delete`. From 3b22ada1cb53dd9c1e2f6b2390d9c0b5ed9d849a Mon Sep 17 00:00:00 2001 From: Ebben Aries Date: Tue, 27 Jun 2023 11:28:19 -0600 Subject: [PATCH 2/3] Cleanup merge conflicts --- rpc/gnmi/gnmi-specification.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 1fc0cac..fadabb4 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1255,7 +1255,6 @@ or array), the following considerations apply: an element - e.g., `/a/f[k1=10][k2=20]`- and a replace or update operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) then this MUST be considered an error by the target system - and an status -<<<<<<< HEAD code of` InvalidArgument (3)` specified. * In the case that key values are specified both as attributes of a node in the path, and as their own elements within the value, then this MUST be considered @@ -1265,13 +1264,10 @@ or array), the following considerations apply: permitted thus they must be omitted from the value payload. This holds true for the direct descendant list key nodes as well as the ultimate leafref'd nodes per OpenConfig [style guidelines](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list). -======= - code of`InvalidArgument (3)` specified. - In the case that key values are specified both as attributes of a node, and as their own elements within the data tree, update or replace operations that modify instances of the key in conflicting ways MUST be considered an error. The target MUST return a status code of `InvalidArgument (3)`. ->>>>>>> master For example, consider a tree corresponding to the examples above, as illustrated below. @@ -1779,14 +1775,10 @@ limitations under the License # 7 Revision History -<<<<<<< HEAD -* v0.9.0: Nov 18, 2022 - * Clarify that for `Set`, that if targeting a path by list keys that the +- v0.10.1: June 27, 2023 + - Clarify that for `Set`, that if targeting a path by list keys that the list keys cannot be included within the value payload -* v0.8.1: July 7, 2022 - * Clarify that for `Subscribe`, a transition to a YANG default value for a -======= - v0.10.0: May 25, 2023 - Add `union_replace` operation. Sync revision to gNMI proto revision. @@ -1800,7 +1792,6 @@ limitations under the License - v0.8.1: July 7, 2022 - Clarify that for `Subscribe`, a transition to a YANG default value for a ->>>>>>> master leaf must use `update` rather than just a `delete`. - Clarify that for `Set`, deleting configuration using `replace(nil)` is prohibited. From 0ce69e9ede1d6f1de47994fa3e2835dd9855b9ef Mon Sep 17 00:00:00 2001 From: Ebben Aries Date: Tue, 27 Jun 2023 11:31:15 -0600 Subject: [PATCH 3/3] Syntax/alignment cleanup --- rpc/gnmi/gnmi-specification.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index fadabb4..ef38247 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1252,22 +1252,22 @@ identify an element (i.e., the path within the schema represents a list, map, or array), the following considerations apply: - In the case that multiple attribute values are required to uniquely address - an element - e.g., `/a/f[k1=10][k2=20]`- and a replace or update - operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) - then this MUST be considered an error by the target system - and an status - code of` InvalidArgument (3)` specified. -* In the case that key values are specified both as attributes of a node in the - path, and as their own elements within the value, then this MUST be considered - an error by the target system - and a status code of `InvalidArgument (3)` - specified. Targeting a list member with update or replace operations that - modify it's own keys in either conflicting or identical fashion is not - permitted thus they must be omitted from the value payload. This holds true - for the direct descendant list key nodes as well as the ultimate leafref'd - nodes per OpenConfig [style guidelines](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list). + an element - e.g., `/a/f[k1=10][k2=20]`- and a replace or update + operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) + then this MUST be considered an error by the target system - and an status + code of` InvalidArgument (3)` specified. +- In the case that key values are specified both as attributes of a node in the + path, and as their own elements within the value, then this MUST be considered + an error by the target system - and a status code of `InvalidArgument (3)` + specified. Targeting a list member with update or replace operations that + modify it's own keys in either conflicting or identical fashion is not + permitted thus they must be omitted from the value payload. This holds true + for the direct descendant list key nodes as well as the ultimate leafref'd + nodes per OpenConfig [style guidelines](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list). - In the case that key values are specified both as attributes of a node, and - as their own elements within the data tree, update or replace operations - that modify instances of the key in conflicting ways MUST be considered an - error. The target MUST return a status code of `InvalidArgument (3)`. + as their own elements within the data tree, update or replace operations + that modify instances of the key in conflicting ways MUST be considered an + error. The target MUST return a status code of `InvalidArgument (3)`. For example, consider a tree corresponding to the examples above, as illustrated below.