Subject: Re: [core] js review of draft-ietf-core-yang-cbor-12

From: Ivaylo Petrov <[email-masked]>
Date: Tue, 7 Apr 2020 15:35:37 +0200

Hello Juergen,

Thank you for the detailed review and your comments! They truly help us
improve this document. Please find my answers below (prefixed by [IP]). Note
that the diff after handing your comments and those of Esko Dijk can be
found at [1].

Best regards,
Ivaylo

[1]:
https://tools.ietf.org/rfcdiff?url1=draft-ietf-core-yang-cbor&url2=http://core-wg.github.io/yang-cbor/draft-ietf-core-yang-cbor-latest.txt
On Tue, Mar 31, 2020 at 1:03 PM Juergen Schoenwaelder <
[email-masked]> wrote:

> Hi,
>
> here is my review of draft-ietf-core-yang-cbor-12. I have not checked
> the examples in detail, I assume (hope?) the authors have used tools
> to generate them or to validate them.
>
> - Nit: There is no need to capitalize Action in the abstract (and
>   elsewhere).
>

[IP]: Fixed

- You should perhaps write 'yang-data extension' instead of 'yang data
>   template' since this is more concrete and less confusing. The use of
>   'template' is a bit unfortunate in RFC 8040 since templates have
>   been used with different meanings elsewhere and I believe people
>   more commonly refer to the yang-data extension. I also checked
>   draft-ietf-netmod-yang-data-ext-05.txt and it does not use the word
>   "template" anymore.
>
>   I see that you use 'YANG data template' later on in several places.
>   This is not strictly incorrect but I find it unfortunate. I would
>   prefer to talk specifically about the yang-data extensions. You
>   actually import both terms, I believe only one is needed (and I
>   prefer yang-data (extension) over YANG data template.
>

[IP]: Fixed following your advice.

> - If this work gets approved, will other specifications like
>   draft-ietf-netmod-yang-data-ext-05.txt be expected to cover CBOR
>   encoding in addition to XML and JSON? This is more a procedural
>   question.
>

[IP]: From our discussions, I could say that that is desirable, but not
something these drafts can enforce.  (Also, for drafts that already are
well-advanced, one would expect a companion draft on a later timeline
instead of the original text-based (JSON/XML) draft.)

> - Wording:
>
>      A new set of encoding rules has been defined to allow the use of the
>      same data models in environments based on the JavaScript Object
>      Notation (JSON) Data Interchange Format [RFC8259].  This is
>      accomplished in the JSON Encoding of Data Modeled with YANG
>      specification [RFC7951].
>
>   What is "environments based on the JavaScript Object Notation (JSON)
>   Data Interchange Format". Perhaps do not even try to speculate about
>   reasons. What about this?
>
>      An additional set of encoding rules has been defined based on the
>      JavaScript Object Notation (JSON) Data Interchange Format
>      [RFC8259].
>

[IP]: Applied and added the reference to RFC7951 as that seems relevant.
Now it reads:

An additional set of encoding rules has been defined in {{RFC7951}} based on
the JavaScript Object Notation (JSON) Data Interchange Format {{RFC8259}}.

> - Is there a reason why SID terminology is not imported from the SID
>   specification? Is the reason to avoid a dependency? But then, can
>   this dependency really be avoided? I reviewed the SID document first
>   because I thought knowing what SIDs are is essential to understand
>   this document...
>

[IP]: This decision has been made before my personal involvement with this
document. I will let the other authors correct me if I am mistaken, but my
understanding is that while it is a good candidate, we did not necessarily
want to mandate the use of the SID draft in order to use the yang-cbor
draft. If the implementers want to have another way of deriving meaning for
the SIDs, that is fine. I will have to verify if the interoperability in
this case was a concern and how it was supposed to be handled.

- I am not sure I would call a notification or a container a
>   collection. Note that RFC 7950 uses the phrase child node quite a
>   bit in definitions, so this may do the same without using the
>   (overloaded) word collection:
>
>    o  child: A schema node defined as a child node of a
>       container, a list, a case, a notification, an RPC input, an RPC
>       output, an action input, an action output.
>
>    I searched the text and 'child' only shows up once and I am not
>    sure this deserves to define a term at all.
>

[IP]: I modified the definition as you suggested, but I believe we should
keep it as it aims at avoiding confusion over choice and other schema nodes
that do not add any additional payload/information during the encoding.
They are not considered child nodes in the explicit definition as otherwise
we would have had to provide rules for their encoding.

- Is 'parent' the same as an 'interior node' defined in RFC 7950? If
>   so, why not use 'interior node'? Looking at the uses or parent, I am
>   not even convinced this term needs to be defined at all, the context
>   seems to be rather clear of what is meant. RFC 7950 does not define
>   'parent' as term either but the meaning is clear in the contexts
>   where the word is being used.
>

[IP]: I reworded this definition as well, but similarly, a choice is not a
parent node in this context. Relevant text:

The container, list, case, notification, RPC input, RPC output, action
input or action output node in which a schema node is defined.

> - To summarize the last few comments, I propose to import 'item' and
>   'SID' from the SID document, to not define 'child' and 'parent'
>   (following RFC 7950), and so the only term to defined here is
>   'delta'. But see above concerning the relationship to the SID
>   document; it is not clear to me what the goals and intentions are in
>   terms of intended document dependencies.
>

[IP]: I believe that my previous points provide the relevant answers, but do
not hesitate to let us know if you have more concerns about any of your
remarks.

> - schema trees vs data trees
>
>    This document defines CBOR encoding rules for YANG schema trees and
>    their subtrees.
>
>   You are not encoding schema trees, you are encoding data trees. See
>   also the JSON document, which says:
>
>    This document defines JSON encoding for YANG data trees and their
>    subtrees.
>
>   Why did you change this from data trees to schema trees?
>

[IP]: Fixed

> - avoid 'collection'?
>
>   s/A collection such as/A data node such as/
>

[IP]: RPCs, action inputs/outputs and notifications are not included in the
data node definition, therefore I changed it to 'nodes from the data tree',
which seems to be precise enough. Please let us know how that works for
you. Also do you think we should have a definition like `serializable node`
in order to avoid listing all the different node types each time?

- If I were to use CBOR with RESTCONF, can I request (e.g. via a
>   specific media-type) how I like the keys to be encoded? Or would
>   such a mechanism have to be specified elsewhere, i.e., we would need
>   another using CBOR with RESTCONF document that defines suitable
>   media types?
>

[IP]:  Currently media types/content formats are defined in the CoMI draft,
which seems the appropriate place for me. If RESTCONF is to be used with
CBOR, I would expect that some specification should define the media type
along with uses of SIDs if needed.

- I do not understand this statement:
>
>    Application payloads carrying a value serialized using the rules
>    defined by this specification (e.g.  CoAP Content-Format) SHOULD
>    include the identifier (e.g.  SID, namespace qualified name,
>    instance-identifier) of this value.
>
>   What is "the identifier of this value"? I am not getting what
>   is being conveyed here.

[IP]: I rewrote this as

When schema node are serialized using the rules defined by this
specification as part of an application payload, the payload SHOULD include
information that would allow a stateless way to identify each node, such as
the SID number associated with each node, SID delta from another SID in the
application payload, the namespace qualified name or the
instance-identifier.

Please let us know if that is more clear.

> - s/section Section 4/Section 4/
>

[IP]: Fixed

- SIDs other than [I-D.ietf-core-sid]?
>
>      [...] If SIDs are to be used, the present specification is
>      used in conjunction with a specification defining this management.
>      One example for such a specification is [I-D.ietf-core-sid].
>
>   This seems to indicate that there can be other kinds of SIDs or SIDs
>   managed differently. Why is this? The SID I-D claims the entire
>   number space, so how would a different 'specification defining the
>   management of SIDs' ever work? Why not be specific that the usage of
>   SIDs depends on [I-D.ietf-core-sid]? See my earlier comments about
>   the unclear dependency relationship between this specification and
>   the SID specification.
>

[IP]: My understanding is that indeed there is the presumption that other
implementations that map YANG item identifiers to unsigned numbers could
exist in the future. If this is the case, I am not aware how one could
interoperate (I would guess based on the content format), but I will let my
coauthors comment on that.

> - Avoid 'collections'?
>
>     4.2.  The 'container' and other collections
>
>     Collections such as containers, list instances, notification
>
>   Rewrite to:
>
>     4.2.  The 'container' and other interior data nodes
>
>     Interior data nodes such as containers, list instances, notification
>
>   There are more uses of collections following that likely can be
>   replaced with 'interior data nodes'. The phrase 'interior data node'
>   is used in RFC 7950 (although not formally defined).
>

[IP]: I mostly agree. It seems, however, that there are some nodes from
data trees that are not qualified as data nodes that are still of interest
to us here, so I used the term `nodes from data trees` instead of 'interior
data nodes'. Now the title reads

The 'container' and other nodes from the data tree

and the first sentence just misses `Interior data nodes such as ` and
starts listing the relevant nodes for which this section applies.

> - Should
>
>        77 : {                    / event (SID 60200) /
>
>   be
>
>        77 : {                    / example-port-fault (SID 60200) /
>
>   Similarly
>
>        47(60200) : {             / event (SID 60123) /
>
>   be
>
>        47(60200) : {             / example-port-fault (SID 60200) /
>

[IP]: Fixed

> - Replace
>
>   5.  Encoding of YANG data templates
>
>    YANG data templates are data structures defined in YANG but not
>    intended to be implemented as part of a datastore.  YANG data
>    templates are defined using the 'yang-data' extension as described by
>    [RFC8040].
>
>    YANG data templates MUST be encoded using the encoding rules of a
>    collection as defined in Section 4.2.
>
>   with
>
>   5.  Encoding of the 'yang-data' extension
>
>    The yang-data extension [RFC8040] is used to define data structures
>    in YANG that are not intended to be implemented as part of a
>    datastore.
>
>    The yang-data extension MUST be encoded using the encoding rules of
>    interior nodes as defined in Section 4.2.
>
>   to avoid the use of 'templates' and 'collections'. In the following
>   text, there are a few more places where 'YANG template' should be
>   replaced by the 'yang-data extension'.
>

[IP]: Agreed, only interior nodes is replaced by for the nodes of the data
trees as follows:

The yang-data extension MUST be encoded using the encoding rules for the
nodes of the data trees as defined in Section 4.2.

- Unexpected ietf-comi module name showing up in an example
>
>      "ietf-comi:error" : {
>
>   The module prefix pops up out of the blue. You may want the put the
>   yang-data definition into an example module, give it an example
>   name, and then replace ietf-comi with that example name. Perhaps
>   even simplify the yang-data schema to just 1-2 leafs.
>

[IP]: I added extra text that should make this much easier to understand.
While the relevant part could be communicated with a smaller example, I
prefer to have a more complete example as long as it does not bloat the
relevant part, which does not appear to be the case here.

> - typo
>
>   s/section defined the CBOR encoding/section defines the CBOR encoding/
>

[IP]: Fixed

> - Improve wording
>
>    To avoid overlap of 'value' defined in different 'enumeration'
>    statements, 'enumeration' defined in a Leafs of type 'union' MUST be
>    encoded using a CBOR text string data item (major type 3) and MUST
>    contain one of the names assigned by 'enum' statements in YANG.
>
>   This does not read well. Perhaps:
>
>    Values of 'enumeration' types defined in a 'union' type MUST be
>    encoded using a CBOR text string data item (major type 3) and MUST
>    contain one of the names assigned by 'enum' statements in YANG.
>
>   There is similar text on page 31 in the context of bits encoding
>   that will also benefit from a rewrite.
>

[IP]: Fixed

> - Third example Bob vs Jack
>
>   Should the third example use
>
>    "/ietf-system:system/authentication/user[name='jack']"
>
>   instead of
>
>    "/ietf-system:system/authentication/user[name='bob']"
>
>   to line up with the third example using SIDs?
>

[IP]: Fixed

> /js
>
> --
> Juergen Schoenwaelder           Jacobs University Bremen gGmbH
> Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>
>
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 7 Apr 2020 21:47:58 +0200

Dear Ivaylo,

thanks for your item-by-item response. I will cut things down to the
few items I felt I still want to comment on (everything else I
consider resolved).

> this case was a concern and how it was supposed to be handled.

For me, the question is whether this ID defines SIDs and the other ID
details how they are managed or this ID imports the definition of SIDs
from the other document, which also details how they are managed.
Right now, it seem something in between, i.e., it is not clear what
the dependencies between these specifications is.
 
> not hesitate to let us know if you have more concerns about any of your

Your solution kind of works for me. Note that here is one usage of
'collection' left in section 4.4.
 
> Please let us know if that is more clear.

This is better, but I am still not sure what exactly this SHOULD is
about. The SIDs in the payload are assumed to be unique and so are
names and paths. So what is the requirement for an 'application
payload' that uses this serialization format?

(nit: first noun should be plural)
 
> coauthors comment on that.

Such a different mapping would most likely have to use separate SID
allocations, i.e., a part of the number space may be managed
differently but the resulting number is still a SID. (Of course, the
whole idea sounds pretty scary in terms of interoperability.)

/js

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 7 Apr 2020 22:55:28 +0200

> the dependencies between these specifications is.

Thank you for that feedback.

So I think we need to be a bit more radical/precise:

-YANG-CBOR should explain that SIDs are 63-bit unsigned integers and how the delta encoding in the CBOR map keys works.  I.e., define the concept, but not the number space management.

-sid does the latter.

The document that defines the media types (comi) gets to bind YANG-CBOR, for these media types, to the specific SID concept defined in -sid.

-YANG-CBOR can still refer to -sid as a preferred way to manage the number space.
But you can implement -YANG-CBOR without understanding -sid, so this is not a normative reference.
Any other document using -YANG-CBOR can refer to -sid as well (or, exceptionally, to something specific for that usage).

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 7 Apr 2020 23:47:37 +0200

On 2020-04-07, at 15:35, Ivaylo Petrov <[email-masked]> wrote:
> [IP]: From our discussions, I could say that that is desirable, but not something these drafts can enforce.  (Also, for drafts that already are well-advanced, one would expect a companion draft on a later timeline instead of the original text-based (JSON/XML) draft.)

Right.  Are we creating any special hardship for draft-ietf-netmod-yang-data-ext?

Grüße, Carsten

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Apr 2020 08:34:28 +0200

> Right.  Are we creating any special hardship for draft-ietf-netmod-yang-data-ext?

This is a procedural question (i.e., nothing the ID will regulate) and
ideally the WGs involved come to some common understanding how we
handle things in the future. One option is that NETMOD agrees to take
care of CBOR as a third encoding in the future like it does take care
of XML and JSON today. What I like to avoid is that YANG evolves and
the various encodings start to work with different subsets of YANG.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Apr 2020 08:57:38 +0200

> Any other document using -YANG-CBOR can refer to -sid as well (or, exceptionally, to something specific for that usage).

This makes sense, but I prefer to have the media types defined in
YANG-CBOR. If I use CBOR with RESTCONF, I love to depend on YANG-CBOR
only and not in addition on COMI just for the media type definition.
The serialization format is defined in YANG-CBOR, hence it makes sense
to me to define the corresponding media-type(s) there as well.

Note, I did not manage to review COMI due to a lack of time. So I am
digging into the type definitions now. RESTCONF (RFC 8040) defines:

application/yang-data+json
application/yang-data+xml

COMI defines:

application/yang-data+cbor
application/yang-identifiers+cbor
application/yang-instances+cbor

It seems that yang-data+cbor really is yang-data+cbor+sid and it seems
there is no media type for yang-data+cbor+names (i.e., the CBOR
encoding that uses names instead of SIDs as keys). The other two media
types yang-identifiers+cbor and yang-instances+cbor seem to be COMI
specific. Hence, me preference would be to define something like

application/yang-data+cbor+sid
application/yang-data+cbor+name

in YANG-CBOR and to leave the other two

application/yang-identifiers+cbor
application/yang-instances+cbor

for COMI. There is a certain interest to stream binary encoded YANG
data and having a self-contained YANG-CBOR document would be desirable
to minimize dependencies and maintenance headache down the road.

/js

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 8 Apr 2020 10:49:53 +0200

Hi Jürgen,

> On 2020-04-08, at 08:57, Juergen Schoenwaelder <[email-masked]> wrote:
> 
> COMI defines:
> 
> It seems that yang-data+cbor really is yang-data+cbor+sid

(We couldn’t use that syntax for the media type name, as +sid is not a structured syntax suffix, but I get the point.)

One way to build a content-type from a media-type name is to add a parameter:

application/yang-data+cbor; id=name
application/yang-data+cbor; id=sid

(In the CoAP content-format those content types would just be two different content-format numbers.)

But we could also encode that parameter in the media type name.
We would have to end the media type name with “+cbor”, because that is the structured syntax suffix that applies.

> and it seems
> in YANG-CBOR

That would put the normative reference to -sid back into YANG-CBOR.
Yes, we could do that.

Grüße, Carsten

PS.: The terminology for media types is a mess^W^W underdeveloped; see the expired https://tools.ietf.org/html/draft-bormann-core-media-content-type-format-01.txt for more info.

> and to leave the other two
> 
> for COMI.

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 8 Apr 2020 12:58:41 +0200

> application/yang-data+cbor; id=sid

Ha.

Let’s create a registry in yang-cbor for id= values (initially filled with id=name).
-sid can then register id=sid in that.

Look, ma, no normative references!

Grüße, Carsten

PS. If you wonder why I care about normative references: RFC 7252 got stuck for a year in 2013 for an ill-advised normative reference.  And have a look at https://www.rfc-editor.org/current_queue.php#draft-ietf-anima-grasp — 140+ weeks of waiting for a (totally unneeded) normative reference…

---

From: Ivaylo Petrov <[email-masked]>
Date: Wed, 8 Apr 2020 13:36:15 +0200

Hello,

I like this solution, but I am wondering if it will create a normative
reference in the other direction (sid to yang-cbor) and would we be fine
with that.

Best regards,
Ivaylo

On Wed, Apr 8, 2020 at 12:58 PM Carsten Bormann <[email-masked]> wrote:

> PS. If you wonder why I care about normative references: RFC 7252 got
> stuck for a year in 2013 for an ill-advised normative reference.  And have
> a look at
> https://www.rfc-editor.org/current_queue.php#draft-ietf-anima-grasp —
> 140+ weeks of waiting for a (totally unneeded) normative reference…
>
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Apr 2020 13:50:29 +0200

> -sid can then register id=sid in that.

He? yang-cbor defines how to use sids as ids so I see no reason to not
also register the id=sid in yang-cbor. I thought we settled on
yang-cbor defines what sids are and the sid id details how they are
assigned and how the number space is managed. This way, yang-cbor is
the base document and the sid document has a normative reference to
yang-cbor and comi has a normative reference to yang-cbor. Is there
a reason that speaks against this?

/js

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 8 Apr 2020 13:55:47 +0200

Hi,

The media type could simply say “uses the concept of SIDs” or it could say “uses SIDs as allocated in -sid”.
I’m not sure the media type needs to say anything at all about this, but if it does, for completeness I think it would need to do the latter (so we can have other media types that get their SIDs elsewhere).
That would mean a normative reference from yang-cbor to -sid.
The registry trick turns that around.

Grüße, Carsten

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Apr 2020 16:40:21 +0200

> The registry trick turns that around.

I want a bit that tells me how instance naming is done, using names or
SIDs. I want to use this to send a query and tell the server that I
want to get CBOR encoded data with SIDS

      GET /restconf/yang-library-version HTTP/1.1
      Host: example.com
      Accept: application/yang-data+cbor;id=sid

or with names are keys

      GET /restconf/yang-library-version HTTP/1.1
      Host: example.com
      Accept: application/yang-data+cbor;id=name

This bit should be defined in YANG-CBOR since this document goes into
quite some detail defining both options to name data.

The question whether alternate schemes can exist to allocate SIDs is
less important for me. I hope multiple schemes to assign SIDs will not
be needed - or only needed in case the scheme defined in the SID
document turns out to be broken up to the point that it can only be
replaced.

That said: A real complication may be the YANG versioning work. Once
publishedd YANG definitions are allowed to change arbitrarily, the
allocation and management of SIDs may get really interesting.

Or is the idea that once we conclude the current SID allocation scheme
to be broken, we go define a SIDplus allocation scheme and then we
still use SIDs in YANG-CBOR but the meaning of the numbers is entirely
different, i.e., we use

      GET /restconf/yang-library-version HTTP/1.1
      Host: example.com
      Accept: application/yang-data+cbor;id=sidplus

to make it clear that the SID numbers now mean something different?
This may make sense and then it may make sense to define

    application/yang-data+cbor;id=name

in YANG-CBOR and to define

    application/yang-data+cbor;id=sid

in the SID document - which means you can't use SIDs with just
YANG-CBOR but only in the context of another document detailing how
SIDs are allocated and managed. Perhaps this is what you have in mind?

Whatever we conclude, it would be nice to get things properly
documented so that we recall the grand plan in N years from now.

/js

---

From: Andy Bierman <[email-masked]>
Date: Wed, 8 Apr 2020 09:07:23 -0700

On Wed, Apr 8, 2020 at 7:41 AM Juergen Schoenwaelder <
[email-masked]> wrote:

> > I’m not sure the media type needs to say anything at all about this, but
> if it does, for completeness I think it would need to do the latter (so we
> can have other media types that get their SIDs elsewhere).

It would be up to the server vendor whether the protocol supported
multiple variants of CBOR encoding.  The intent for CoMI is that
a server without name string support could be implemented.

> allocation and management of SIDs may get really interesting.
The SID assignments cannot change once an RFC is published.
Any NBC changes to published modules would require new SID assignments.

> to make it clear that the SID numbers now mean something different?

I do not understand why the SID allocation scheme is broken but if future
requirements make it deficient then a replacement (e.g. sid2, sidplus) could
be introduced.

/js
Andy

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

---

From: Andy Bierman <[email-masked]>
Date: Wed, 8 Apr 2020 09:19:00 -0700

> 140+ weeks of waiting for a (totally unneeded) normative reference…
draft-ietf-netmod-syslog-model-26 has been in MISREF state for 754 days and
counting.
Talk about ill-advised normative references...

Andy