From 00c3ad4a45fa8bcab57df2753c410351e1973d81 Mon Sep 17 00:00:00 2001
From: wenovus <wenbli@google.com>
Date: Mon, 10 May 2021 12:40:49 -0700
Subject: [PATCH 1/2] Proposal for clarifications when calling gNMI Set on a
 list node or element.

1. Add example JSON_IETF format for updating an individual list element.
1. Clarify that an empty subset of attributes for a keyed-list is unacceptable as a path for gNMI Set.
1. Clarify that in OpenConfig, MUST specify a path that terminates on the enclosing container in order to modify a whole list node.
1. Minor grammar fixes.

Background: I found these points to be missing from either this doc or
RFC7951. As a result, I'm proposing adding these clarifications that may
or may not be the standard or established convention. In that case,
modification suggestions are welcome to correct any inaccuracies.
---
 rpc/gnmi/gnmi-specification.md | 46 +++++++++++++++++++++++++++++-----
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md
index 20cb5a1..ad09534 100644
--- a/rpc/gnmi/gnmi-specification.md
+++ b/rpc/gnmi/gnmi-specification.md
@@ -453,6 +453,35 @@ update: <
 >
 ```
 
+For `/a/b[name=b1]`:
+
+```
+update: <
+  path: <
+    elem: <
+      name: "a"
+    >
+    elem: <
+      name: "b"
+      key: <
+        key: "name"
+        value: "b1"
+      >
+    >
+  >
+  val: <
+    json_ietf_val: `{ "b": {
+                        "name": "b1",
+                        "c": {
+                          "d": "AStringValue",
+                          "e": 10042
+                        }
+                   }
+            }`
+  >
+>
+```
+
 For `/a` :
 
 ```
@@ -467,10 +496,10 @@ update: <
                       {
                         "name": "b1",
                         "c": {
-                        "d": "AStringValue",
+                          "d": "AStringValue",
                           "e": 10042
                         }
-                       }
+                      }
                    ]
             }`
   >
@@ -1109,11 +1138,11 @@ 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.
+    operation's path specifies a strict subset of the attributes (e.g.,
+    `/a/f[k1=10]`, `/a/f`), then this MUST be considered an error by the target
+    system - and an status code of` InvalidArgument (3)` specified.
 *   Where the path specified refers to a node which itself represents the
-    collection of objects (list, map, or array) a replace operation MUST remove
+    collection of objects (list, map, or array), a replace operation MUST remove
     all collection entries that are not supplied in the value provided in the
     `SetRequest`. An update operation MUST be considered to add new entries to
     the collection if they do not exist.
@@ -1121,6 +1150,11 @@ array), the following considerations apply:
     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 OpenConfig, a path which refers to a keyed YANG list node for
+    modification (as opposed to an element of the list node) MUST terminate at
+    the [enclosing
+    container](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list)
+    element.
 
 For example, consider a tree corresponding to the examples above, as illustrated
 below.

From 393efa147878e183344a7fdd6ff95b17efcbd66a Mon Sep 17 00:00:00 2001
From: wenovus <wenbli@google.com>
Date: Wed, 20 Oct 2021 16:12:26 -0700
Subject: [PATCH 2/2] Remove openconfig-specific info, fix example, and improve
 wording.

---
 rpc/gnmi/gnmi-specification.md | 20 +++++++-------------
 1 file changed, 7 insertions(+), 13 deletions(-)

diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md
index ad09534..6ece436 100644
--- a/rpc/gnmi/gnmi-specification.md
+++ b/rpc/gnmi/gnmi-specification.md
@@ -470,13 +470,12 @@ update: <
     >
   >
   val: <
-    json_ietf_val: `{ "b": {
-                        "name": "b1",
-                        "c": {
-                          "d": "AStringValue",
-                          "e": 10042
-                        }
-                   }
+    json_ietf_val: `{ 
+                      "name": "b1",
+                      "c": {
+                        "d": "AStringValue",
+                        "e": 10042
+                      }
             }`
   >
 >
@@ -1138,7 +1137,7 @@ 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 strict subset of the attributes (e.g.,
+    operation's path specifies a proper subset of the attributes (e.g.,
     `/a/f[k1=10]`, `/a/f`), then this MUST be considered an error by the target
     system - and an status code of` InvalidArgument (3)` specified.
 *   Where the path specified refers to a node which itself represents the
@@ -1150,11 +1149,6 @@ array), the following considerations apply:
     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 OpenConfig, a path which refers to a keyed YANG list node for
-    modification (as opposed to an element of the list node) MUST terminate at
-    the [enclosing
-    container](https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md#list)
-    element.
 
 For example, consider a tree corresponding to the examples above, as illustrated
 below.