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

From: RFC Errata System <[email-masked]>
Date: Sun, 22 Nov 2020 14:14:45 -0800 (PST)

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/eid6342

--------------------------------------
Type: Technical
Reported by: Muly Ilan <[email-masked]>

Section: 4.6.1

Original Text
-------------
To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might
send a plain patch as follows:
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
If-Match: "b8389233a4c"
Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox">
<year>2011</year>
</album>

Corrected Text
--------------
To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might
send a plain patch as follows:
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
If-Match: "b8389233a4c"
Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<year>2011</year>
</album>

Notes
-----
Missing key leaf value in the message-body (<name>Wasting Light</name>)

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: Martin Björklund <[email-masked]>
Date: Mon, 23 Nov 2020 09:37:29 +0100 (CET)

Hi,

The issue boils down to if list keys are required in a plain patch.
Unfortunately, the RFC doesn't specifucy this.  From a technical pow,
list keys are not necessary.  In fact, if they are present in the
payload, they are redundant (since they are part of the URL) (this is
actually mentioned in the RFC).

Since it isn't clearly specified, I think we must assume that the keys
are not required.  Hence I think that this errata should be rejected.

In a future version of this document, the behaviour should be
clarified.

/martin

RFC Errata System <[email-masked]> wrote:
> _______________________________________________
> netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

---

From: Muly Ilan <[email-masked]>
Date: Mon, 23 Nov 2020 11:31:43 +0000

Hi,

If list keys are not required in message body for plain PATCH then they are also not required for the PUT method.
But the example for PUT in section 4.5 is:

PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011
}
]
}

So, do we want consistency between PUT and plain PATCH?

I believe consistency is important and currently the RFC contains two inconsistent examples.

Best,

Muly

-----Original Message-----
From: netconf [mailto:[email-masked]] On Behalf Of Martin Bj?rklund
Sent: 23/11/2020 10:37
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [netconf] [Technical Errata Reported] RFC8040 (6342)

Hi,

The issue boils down to if list keys are required in a plain patch.
Unfortunately, the RFC doesn't specifucy this.  From a technical pow, list keys are not necessary.  In fact, if they are present in the payload, they are redundant (since they are part of the URL) (this is actually mentioned in the RFC).

Since it isn't clearly specified, I think we must assume that the keys are not required.  Hence I think that this errata should be rejected.

In a future version of this document, the behaviour should be clarified.

/martin

RFC Errata System <[email-masked]> wrote:
> The following errata report has been submitted for RFC8040, "RESTCONF 
> Protocol".
> 
> https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.
> rfc-editor.org%2Ferrata%2Feid6342&amp;data=04%7C01%7Cmuly_i%40rad.com%
> 7Cf7ffd30dde054f875cc608d88f8b0eed%7Cf9047108cc2c4e4897a343fad1b3bf9d%
> 7C1%7C0%7C637417174712193376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwM
> DAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=2nm
> LthW5HkwRvJZi%2F2Pj6%2B9qkLV9gV55wiBpIoiC%2FD4%3D&amp;reserved=0
> 
> Content-Type: application/yang-data+xml <album 
> xmlns="https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%
> 2Fexample.com%2Fns%2Fexample-jukebox&amp;data=04%7C01%7Cmuly_i%40rad.c
> om%7Cf7ffd30dde054f875cc608d88f8b0eed%7Cf9047108cc2c4e4897a343fad1b3bf
> 9d%7C1%7C0%7C637417174712193376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLj
> AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=
> hxW6LA8t%2BNRka2GGRqRNsTnK2itYH1rRLnOxU7JbNlc%3D&amp;reserved=0">
> <year>2011</year>
> </album>
> 
> Corrected Text
> --------------
> Content-Type: application/yang-data+xml <album 
> xmlns="https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%
> 2Fexample.com%2Fns%2Fexample-jukebox&amp;data=04%7C01%7Cmuly_i%40rad.c
> om%7Cf7ffd30dde054f875cc608d88f8b0eed%7Cf9047108cc2c4e4897a343fad1b3bf
> 9d%7C1%7C0%7C637417174712193376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLj
> AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=
> hxW6LA8t%2BNRka2GGRqRNsTnK2itYH1rRLnOxU7JbNlc%3D&amp;reserved=0">
> 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.
> 
> https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.
> ietf.org%2Fmailman%2Flistinfo%2Fnetconf&amp;data=04%7C01%7Cmuly_i%40ra
> d.com%7Cf7ffd30dde054f875cc608d88f8b0eed%7Cf9047108cc2c4e4897a343fad1b
> 3bf9d%7C1%7C0%7C637417174712193376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4
> wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sda
> ta=GOd8xUYLJ9C69r7aN6rujBhsYFJd05CxiHNXT9YXOZ0%3D&amp;reserved=0

_______________________________________________
netconf mailing list
[email-masked]
https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fnetconf&amp;data=04%7C01%7Cmuly_i%40rad.com%7Cf7ffd30dde054f875cc608d88f8b0eed%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417174712193376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=GOd8xUYLJ9C69r7aN6rujBhsYFJd05CxiHNXT9YXOZ0%3D&amp;reserved=0

---

From: Martin Björklund <[email-masked]>
Date: Mon, 23 Nov 2020 13:14:52 +0100 (CET)

Hi,

Muly Ilan <[email-masked]> wrote:
> Hi,
> 
> If list keys are not required in message body for plain PATCH then
> they are also not required for the PUT method.

You are right that the keys are redundant also in PUT.  However, PUT
means completely replace or create the resource, but plain PATCH modifies
only the given fields.

/martin

---

From: Muly Ilan <[email-masked]>
Date: Mon, 23 Nov 2020 12:26:14 +0000

Hi Martin,

Plain PATCH is defined as a merge operation i.e. it can create a resource.
It's not limited to editing of existing resources.

>From section 4.6.1:
" The plain patch mechanism merges the contents of the message-body
with the target resource."

" Plain patch can be used to create or update, but not delete, a child
resource within the target resource."

It's better to have consistent examples.
I suggest either to modify the plain PATCH example or the PUT example.

Best,

Muly

-----Original Message-----
From: Martin Björklund [mailto:[email-masked]] 
Sent: 23/11/2020 14:15
To: Muly Ilan <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]
Subject: Re: [netconf] [Technical Errata Reported] RFC8040 (6342)

Hi,

> they are also not required for the PUT method.

You are right that the keys are redundant also in PUT.  However, PUT means completely replace or create the resource, but plain PATCH modifies only the given fields.

/martin

> Content-Type: application/yang-data+json { "example-jukebox:album" : [ 
> { "name" : "Wasting Light", "genre" : "example-jukebox:alternative", 
> "year" : 2011 } ] }
> 
> > xmlns="https://eur01.safelinks.protection.outlook.com/?url=http%3A%2
> > F%25 
> > AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdat
> > a= hxW6LA8t%2BNRka2GGRqRNsTnK2itYH1rRLnOxU7JbNlc%3D&amp;reserved=0">
> > <year>2011</year>
> > </album>
> > 
> > Corrected Text
> > --------------
> > xmlns="https://eur01.safelinks.protection.outlook.com/?url=http%3A%2
> > F%25 
> > AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdat
> > a= hxW6LA8t%2BNRka2GGRqRNsTnK2itYH1rRLnOxU7JbNlc%3D&amp;reserved=0">
> d.com%7Cf5c6b052c9fe4dd9c64308d88fa96449%7Cf9047108cc2c4e4897a343fad1b
> 3bf9d%7C1%7C0%7C637417304990448682%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4
> ta=SOPMijRWiUHA%2BpJnmxGJ4%2FLWqneTaFwfyIpdpuFl5yU%3D&amp;reserved=0

---

From: Muly Ilan <[email-masked]>
Date: Mon, 23 Nov 2020 12:52:31 +0000

Hi Martin,

Putting aside the similarity or not between plain PATCH and PUT, there's another example of inconsistency with plain PATCH in the RFC.

Please check the plain PATCH example in appendix B.2.5. " Edit a Data Resource".
This example has keys both in the message header and message body.

This means that either the example in 4.6.1 or the example in B.2.5 should be modified. 

Section 4.6.1 includes the following text:
"
If the target resource represents a YANG list instance, then the key
leaf values, in message-body representation, MUST be the same as the
key leaf values in the request URI.
"

If keys are not needed in the message body so this "warning text" is not needed either.

Moreover, since the above "warning text" is part of the RFC, it suggests to me that the RFC assumes that there are keys in both header URI and body.  

Best,

Muly

-----Original Message-----
From: Muly Ilan 
Sent: 23/11/2020 14:26
To: Martin Björklund <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]
Subject: RE: [netconf] [Technical Errata Reported] RFC8040 (6342)

Hi Martin,

>From section 4.6.1:
" The plain patch mechanism merges the contents of the message-body with the target resource."

" Plain patch can be used to create or update, but not delete, a child resource within the target resource."

Best,

Muly

-----Original Message-----
From: Martin Björklund [mailto:[email-masked]]
Sent: 23/11/2020 14:15
To: Muly Ilan <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]
Subject: Re: [netconf] [Technical Errata Reported] RFC8040 (6342)

Hi,

/martin

---

From: Andy Bierman <[email-masked]>
Date: Mon, 23 Nov 2020 05:02:49 -0800

> In a future version of this document, the behaviour should be

+1

reject this errata

> /martin
Andy

---

From: Muly Ilan <[email-masked]>
Date: Mon, 23 Nov 2020 13:34:49 +0000

Hi Andy,

The example for plain PATCH in appendix B.2.5 has keys in both the URI and body.
Whereas the example in section 4.6.1 has keys only in the URI.

Clearly one of the examples is wrong.

Best,

Muly

From: netconf [mailto:[email-masked]] On Behalf Of Andy Bierman
Sent: 23/11/2020 15:03
To: Martin Björklund <[email-masked]>
Cc: Kent Watsen <[email-masked]>; Netconf <[email-masked]>; RFC Editor <[email-masked]>
Subject: Re: [netconf] [Technical Errata Reported] RFC8040 (6342)

On Mon, Nov 23, 2020 at 12:37 AM Martin Björklund <[email-masked]<mailto:[email-masked]>> wrote:
Hi,

+1

reject this errata

/martin

Andy

RFC Errata System <[email-masked]<mailto:[email-masked]>> wrote:
> https://www.rfc-editor.org/errata/eid6342<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.rfc-editor.org%2Ferrata%2Feid6342&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989910693%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=Ah8q7Rb9GwOp4Ck6%2FErNLDk92PpSA6KPbnrxJ%2FHYpjc%3D&reserved=0>
>
> Reported by: Muly Ilan <[email-masked]<mailto:[email-masked]>>
>
> Section: 4.6.1
>
> Original Text
> -------------
> Host: example.com<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2F&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989920683%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=R4iqFtnIw%2FktGcQd1UzdrY5gT6LYF2cl0q%2BfNg63sWs%3D&reserved=0>
> If-Match: "b8389233a4c"
> <album xmlns="http://example.com/ns/example-jukebox<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2Fns%2Fexample-jukebox&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989920683%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=T8NtFORUGSRk6HjN%2F382U0vkB%2FVF%2FJ5YvKDkBMETFuA%3D&reserved=0>">
> <year>2011</year>
> </album>
>
> Corrected Text
> --------------
> Host: example.com<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2F&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989930678%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=63TdkWZRnrYaSaHSHMDbAlxHTkIDP4Zu7YPrzn96RgE%3D&reserved=0>
> If-Match: "b8389233a4c"
> <album xmlns="http://example.com/ns/example-jukebox<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2Fns%2Fexample-jukebox&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989930678%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=gysKTJN95f59w58%2BNWMVp5ZG6N7V1Ir0m6dL8JG6qI0%3D&reserved=0>">
> [email-masked]<mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/netconf<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fnetconf&data=04%7C01%7Cmuly_i%40rad.com%7C556dc10cce6348d850e808d88fb024e0%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637417333989940676%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=RTyHWObVREumAU3i3pb0Q0c8tJVUEcG1v0D0olUm1LA%3D&reserved=0>

---

From: Martin Björklund <[email-masked]>
Date: Mon, 23 Nov 2020 14:36:47 +0100 (CET)

> resource within the target resource."

I meant:

  However, PUT means completely replace or create the target resource,
  but plain PATCH modifies only the given fields in the target
  resource.

/martin

---

From: Martin Björklund <[email-masked]>
Date: Mon, 23 Nov 2020 14:38:40 +0100 (CET)

> This means that either the example in 4.6.1 or the example in B.2.5 should be modified. 

No, different examples can show different things.

> If keys are not needed in the message body so this "warning text" is not needed either.

It is needed, since keys are *allowed*.  *If* the keys are present,
they MUST match the existing keys.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Mon, 23 Nov 2020 08:00:27 -0800

On Mon, Nov 23, 2020 at 5:38 AM Martin Björklund <[email-masked]> wrote:

> > Putting aside the similarity or not between plain PATCH and PUT, there's
> another example of inconsistency with plain PATCH in the RFC.
> >
Agreed.

Although we have several customers that would like to rename list entries,
and sometimes think RESTCONF allows it.  I do not think any YANG-based
protocol
allows list keys to be modified.  You have to delete and re-create the list
entry.
I think this is something for YANG-next to consider, so it is done
consistently across
all protocols.

Andy

>
>
> >
> > Moreover, since the above "warning text" is part of the RFC, it suggests
> to me that the RFC assumes that there are keys in both header URI and
> body.
> >
> >
> > Best,
> >
> > Muly
> >

---

From: Kent Watsen <[email-masked]>
Date: Mon, 23 Nov 2020 17:27:39 +0000

+1 on rejecting the errata.  PUT replaces the resource, PATCH modifies it.

Any node not present in a PUT representation is assumed to be deleted, but it is not allowed to delete keys, hence why keys MUST always to present in a PUT.

> and sometimes think RESTCONF allows it.  I do not think any YANG-based protocol
> allows list keys to be modified.  You have to delete and re-create the list entry.
> I think this is something for YANG-next to consider, so it is done consistently across
> all protocols.

YANG-next or RESTCONF-next?

I think that it is unique to RESTCONF since only RC (not considering COAP) targets specific resources.

That said, the feature might be something that could be added via an I-D, as opposed to an 8440-bis.

K.

---

From: Andy Bierman <[email-masked]>
Date: Tue, 24 Nov 2020 13:31:12 -0800

On Mon, Nov 23, 2020 at 9:27 AM Kent Watsen <[email-masked]> wrote:

> Any node not present in a PUT representation is assumed to be deleted, but
> it is not allowed to delete keys, hence why keys MUST always to present in
> a PUT.
>
>

I think any YANG list with keys can have this problem.
IMO it is better to define the common semantics in YANG and let the
protocols
decide how to encode them on the wire.

The workaround (of course) is to pick an arbitrary integer or label as the
key
so there is no reason to change it.

That said, the feature might be something that could be added via an I-D,
> as opposed to an 8440-bis.
>
>
Not to restart this thread, but I prefer yang-next vs. lots of add-on RFCs.
Yes it is harder for standards writers to produce, but easier to use in the
long run
for the vendors and operators.

Andy