Subject: [netconf] [Technical Errata Reported] RFC8040 (6271)

From: RFC Errata System <[email-masked]>
Date: Tue, 1 Sep 2020 10:37:26 -0700 (PDT)

The following errata report has been submitted for RFC8040,
"RESTCONF Protocol".

--------------------------------------
You may review the report below and at:
https://www.rfc-editor.org/errata/eid6271

--------------------------------------
Type: Technical
Reported by: Kent Watsen <[email-masked]>

Section: 4.5

Original Text
-------------
   The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
   parameters MUST be supported by the PUT method for data resources.
   These parameters are only allowed if the list or leaf-list is
   "ordered-by user".

Corrected Text
--------------
   The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
   parameters MUST be supported by the PUT method for data resources.
   These parameters are only allowed if the target resource is a
   non-existent entry of an "ordered-by user" list or leaf-list.

Notes
-----
First, Section 3.5 (Data Resource) says that "list" and "leaf-leaf" are not a data resources:

  A data resource represents a YANG data node that is a descendant node
  of a datastore resource. Each YANG-defined data node can be uniquely
  targeted by the request-line of an HTTP method. Containers, leafs,
  leaf-list entries, list entries, anydata nodes, and anyxml nodes are
  data resources.

Second, these query parameters only make sense when targeting a non-existent entry.   If the entry does not exist, then PUT is being used like a POST: to create and place an item in an ordered list.  However, if the entry exists, then PUT is being used to both replace the contents and (presumably) re-place the order in the list; but this doesn't make sense because:

  1) "insert" defaults to "last".
  2) there is no "insert" value to indicate "keep existing placement".
  3) having to concoct valid "insert" and "point" values is hard.

Thus indiscriminate PUTs would move entries to the end, which can't be desired...

Instructions:
-------------
This erratum is currently posted as "Reported". If necessary, please
use "Reply All" to discuss whether it should be verified or
rejected. When a decision is reached, the verifying party  
can log in to change the status and edit the report, if necessary. 

--------------------------------------
RFC8040 (draft-ietf-netconf-restconf-18)
--------------------------------------
Title               : RESTCONF Protocol
Publication Date    : January 2017
Author(s)           : A. Bierman, M. Bjorklund, K. Watsen
Category            : PROPOSED STANDARD
Source              : Network Configuration
Area                : Operations and Management
Stream              : IETF
Verifying Party     : IESG

---

From: Andy Bierman <[email-masked]>
Date: Tue, 1 Sep 2020 12:28:22 -0700

Hi,

I agree this errata should be accepted.

Andy

On Tue, Sep 1, 2020 at 10:37 AM RFC Errata System <[email-masked]>
wrote:

> Second, these query parameters only make sense when targeting a
> non-existent entry.   If the entry does not exist, then PUT is being used
> like a POST: to create and place an item in an ordered list.  However, if
> the entry exists, then PUT is being used to both replace the contents and
> (presumably) re-place the order in the list; but this doesn't make sense
> because:
>

---

From: Kent Watsen <[email-masked]>
Date: Tue, 1 Sep 2020 20:45:46 +0000

Maybe the wording is too strong?

    OLD: These parameters are only allowed if... 
    NEW: These parameters are only processed if…

Note also the HTTP goal to be idempotent.

K.

> On Sep 1, 2020, at 3:28 PM, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> On Tue, Sep 1, 2020 at 10:37 AM RFC Errata System <[email-masked] <mailto:[email-masked]>> wrote:
> https://www.rfc-editor.org/errata/eid6271 <https://www.rfc-editor.org/errata/eid6271>
> 
> Reported by: Kent Watsen <[email-masked] <mailto:[email-masked]>>
> 
> Section: 4.5
> 
> Original Text
> -------------

---

From: Martin Björklund <[email-masked]>
Date: Wed, 02 Sep 2020 08:27:18 +0200 (CEST)

Hi,

> The following errata report has been submitted for RFC8040,

I don't think this is correct.  The new text makes it impossible to
move an existing ordered-by user list entry, which should be
possible.  4.8.6 says:

   The "point" query parameter is used to specify the insertion point
   for a data resource that is being created or moved within an
   "ordered-by user" list or leaf-list.

See below.

> non-existent entry.  If the entry does not exist, then PUT is being
> used like a POST: to create and place an item in an ordered list.
> However, if the entry exists, then PUT is being used to both replace
> the contents and (presumably) re-place the order in the list; but this
> doesn't make sense because:
> 

I think this is the real problem.  It should be (and the intention was):

  1.  if "insert" isn't present and a new entry is created, the new
      entry will be appended to the end of the list.

  2.  if "insert" isn't present a an entry is modified (PUT), the
      entry keeps its place in the list.

/martin

> _______________________________________________
> netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

---

From: Andy Bierman <[email-masked]>
Date: Wed, 2 Sep 2020 07:42:19 -0700

>       entry keeps its place in the list.

Agreed.  So the errata only applies to the  "insert" query parameter.

Andy

---

From: Kent Watsen <[email-masked]>
Date: Wed, 2 Sep 2020 16:24:00 +0000

[removing RFC Editor]

> RFC Errata System <[email-masked] <mailto:[email-masked]>> wrote:

We can cancel and resubmit errata as needed.

I think there might be two Errata:

1) for the r/list/list entry/ fix

    NEWER:
        The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
        parameters MUST be supported by the PUT method for data resources.
        These parameters are only allowed if the target resource is an
        entry of an "ordered-by user" list or leaf-list.

2) for the “insert” query parameter

    In Section 4.8.5: The "insert" Query Parameter

    OLD:

       The default value is "last".

       This parameter is only supported for the POST and PUT methods.  It is
       also only supported if the target resource is a data resource, and
       that data represents a YANG list or leaf-list that is
       "ordered-by user”.

    NEW:

       The default value is “last”, with exception to when used with PUT
       and the target resource already exists, in which case the default
       is to replace the target resource without altering its position in the
       "ordered-by user” list or leaf-list.

       This parameter is only supported for the POST and PUT methods.
       It is also only supported if the target resource is a data resource 
       that is an entry of an "ordered-by user" list or leaf-list.

Thoughts?

Separately, but related, is it possible to PUT on an "ordered-by user” leaf-list?   Presumably, the operation changes the implicit “key” field...

K.

---

From: Martin Björklund <[email-masked]>
Date: Wed, 02 Sep 2020 21:56:51 +0200 (CEST)

>         entry of an "ordered-by user" list or leaf-list.

This isn't quite correct (the target resource in POST is not a list
entry), and it isn't needed IMO.  The text in 4.8.5 and 4.8.6 says the
same thing already, so we don't need to say it here as well.  Esp. not
in an errata.

>        "ordered-by user” list or leaf-list.

Ok, but is the grammar correct "with exception to when..."?

>        that is an entry of an "ordered-by user" list or leaf-list.

I prefer the old text over this.

> 
> Thoughts?
> 
> Separately, but related, is it possible to PUT on an "ordered-by
> user” leaf-list?   Presumably, the operation changes the implicit
> “key” field...

Section 4.5 says:

   If the target resource represents a YANG leaf-list, then the PUT
   method MUST NOT change the value of the leaf-list instance.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Wed, 2 Sep 2020 19:57:27 +0000

> On Sep 2, 2020, at 12:24 PM, Kent Watsen <[email-masked]> wrote:
> 
>     NEW:
> 

The text above allows/suggests that are four “insert” values MAY always be explicitly passed (and presumably processed).  Do we want to support the case where a PUT is used only to move an element?  i.e. the passed “replacement” data is identical to what exists on the server, only the insert/point have an effect?

Or should this strategy be that the insert/point can always be passed (in a PUT for an "ordered-by user” list or leaf-list), but they only have meaning (i.e., are processed) when/if the object is being created, and otherwise ignored?

K.

---

From: Kent Watsen <[email-masked]>
Date: Wed, 2 Sep 2020 20:07:50 +0000

Hi Martin,

> entry), and it isn't needed IMO.  The text in4.8.5 and 4.8.6 says the

But this is in Section 4.5, which only regards PUT.

That said, I also noticed redundant text regarding where the query-parameters are allowed.  Generally, it seems such text should be in Sections 4.8.5 and 4.8.6, more so than Section 4.5...

> Ok, but is the grammar correct "with exception to when..."?

There’s a fork in this thread on this point.  Let’s see how that resolves first…

> I prefer the old text over this.

But Section 3.5 (Data Resource) clearly says that “list entry" and "leaf-leaf entry" are data resources (not “list” and “leaf-list”).

>   method MUST NOTchange the value of the leaf-list instance.

Ah-ha, very good.  And, interestingly, if not "changing the value of the leaf-list instance”, then it seems the only thing it could be used for it to move the entry’s position - right?

> /Martin

K.

---

From: Kent Watsen <[email-masked]>
Date: Wed, 2 Sep 2020 20:24:18 +0000

Typo:

> The text above allows/suggests that are four “insert” values MAY always be explicitly passed (and presumably processed).  

s/that are four/that the four/

K.

---

From: Martin Björklund <[email-masked]>
Date: Thu, 03 Sep 2020 07:37:23 +0200 (CEST)

Kent Watsen <[email-masked]> wrote:
> The text above allows/suggests that are four “insert” values MAY
> always be explicitly passed (and presumably processed).  Do we want to
> support the case where a PUT is used only to move an element?
> i.e. the passed “replacement” data is identical to what exists on the
> server, only the insert/point have an effect?
> 
> Or should this strategy be that the insert/point can always be passed
> (in a PUT for an "ordered-by user” list or leaf-list), but they only
> have meaning (i.e., are processed) when/if the object is being
> created, and otherwise ignored?

No, move (and possibly modify the entry) is supported.  Section 4.8.6
says:

                                             ^^^^^^^^

/martin

---

From: Kent Watsen <[email-masked]>
Date: Thu, 3 Sep 2020 12:25:16 +0000

I don’t think that I’m able to edit this errata for Section 4.5.  If I could, I would submit again with the new text that fixes the *entries* language.

I think that the AD needs to “reject” this Errata (EID 6271).  We could file separate errata to fix the “entries” language in Sections 4.5, 4.8.5, and 4.8.6, but I’m unsure it’s worth it.

So I just filed a new errata https://www.rfc-editor.org/errata/eid6277 <https://www.rfc-editor.org/errata/eid6277> to fix just the “insert” query parameter "default" issue.

K.

> On Sep 3, 2020, at 1:37 AM, Martin Björklund <[email-masked]> wrote:
>