Subject: [yang-doctors] Yangdoctors early review of draft-ietf-teas-yang-path-computation-11

From: Martin Björklund via Datatracker <[email-masked]>
Date: Thu, 17 Dec 2020 10:58:42 -0800

Reviewer: Martin Björklund
Review result: Ready with Nits

o  General

  The language is called "YANG", not "Yang".

o  1.2. Tree Diagram

  The text says:

    A simplified graphical representation of the data model is used in
    section 6.1 of this this document.  The meaning of the symbols in
    these diagrams is defined in [RFC8340].

  Tree diagrams are used also in chapter 5.  I suggest:

    Tree diagrams used in this document follow the notation defined in
    [RFC8340].

o  Tree diagrams in general

   You can use pyang -f tree --tree-line-length 68 ... in order to
   avoid long lines in the RFC.

o  6.1

  This section presents a fully expanded tree diagram of the module.
  Tree diagrams are mainly used to give an overview of a module's
  structure.  The tree diagram in this section spans 13 pages and is
  quite hard to read.

  I also note that a majority of the nodes in this tree diagram come
  from the expansion of groupings that aren't defined in this
  document.  Hence, I suggest that you might want to run:

    pyang -f tree --tree-line-length 68 \
      --tree-print-groupings --tree-no-expand-uses

o  There are a number of groupings that are used only once, and do not
   seem to be defined to be reused by other modules, e.g.,
   "requested-info", "requested-state", "svec-metrics-bounds" and more.

   If they are intended to be reused, it should be made clear in their
   description statements.  If not, I think they should be inlined and
   removed.

o  grouping svec-exclude

   This grouping has an ordered-by user list.  Why is this list user
   ordered?  If the order matters, it should be explained how it matters.

   Also, the index leaf has this description:

     "XRO subobject index"

   What is "XRO"?  Is this description sufficiently clear?

o  path-request

   In the path-request, there is construct for path-refs:

                   list primary-reverse-path-ref {
                     key index;
                     min-elements 1;
                     description
                       "The list of primary reverse paths that
                        reference this path as a candidate
                        secondary reverse path";
                     leaf index {
                       type uint32;
                       description
                         "The index used by the
                          primary-reverse-path-ref list";
                     }

  What is this index?  Is it only used as an arbitrary index, or
  something else?  If it is an arbitraty index, it should be explained
  in the descriptions.

  Also note that lists in rpc input don't need an index.

o  Validation

   The module fails YANG validation, but that is really due to errors
   in [email-masked].  Specifially, the leafref in the
   grouping "path-compute-info" must have prefixes in its path.
   Without prefixes, the path refers to nodes in the module that uses
   the grouping.  (same for other groupings in that module).

o  Layout

  I suggest you run the module through

    pyang -f yang --yang-canonical --yang-line-length 68

  in order to have the module indented and formatted consistently.

  This will make the RFC editor's job easier.

/martin

---

From: tom petch <[email-masked]>
Date: Wed, 23 Dec 2020 12:31:42 +0000

From: Teas <[email-masked]> on behalf of Martin Björklund via Datatracker <[email-masked]>
Sent: 17 December 2020 18:58

<snip>
o  Validation

<tp>
Martin,

I am confused (which is why I will never be a YANG doctor:-(.

RFC7950 p.104 says
      Identifiers appearing inside
   the grouping are resolved relative to the scope in which the grouping
   is defined, not where it is used. 
I recall much debate about paths and their resolution but I cannot find a statement that paths are resolved where they are used in RFC7950, nor in the many Errata.
And while I find teas-te almost impossible to understand because of how it is structured,  yet
the elements in
type leafref {
        path "/te/globals/named-path-constraints/"
           + "named-path-constraint/name";
      }

/martin

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

---

From: tom petch <[email-masked]>
Date: Wed, 23 Dec 2020 12:36:25 +0000

Sorry about the incomplete e-mail.  Try again

<snip>
o  Validation

<tp>
Martin,

RFC7950 p.104 says

would all appear to be in teas-te and not imported from e.g. te-typesin, in which case prefix are not needed.

So while I am sure you are right, and this is a significant problem, yet I cannot see the chapter and verse to back it up.

In passing, this construct, in teas-yang-path-computation has a history of YANG difficulties.

Tom petch

/martin

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

---

From: Martin Björklund <[email-masked]>
Date: Wed, 23 Dec 2020 14:59:21 +0100 (CET)

Hi,

tom petch <[email-masked]> wrote:
> I recall much debate about paths and their resolution but I cannot
> find a statement that paths are resolved where they are used in
> RFC7950, nor in the many Errata.

p. 104 further says:

   Prefix mappings, type names,
   grouping names, and extension usage are evaluated in the hierarchy
   where the "grouping" statement appears.

But in this case we have a leafref path w/o prefixes.

Section 6.4.1 says:

   o  Names without a namespace prefix belong to the same namespace as
      the identifier of the current node.  Inside a grouping, that
      namespace is affected by where the grouping is used (see
      Section 7.13).

And 7.13 says:

   The effect of a "uses" reference to a grouping is that the nodes
   defined by the grouping are copied into the current schema tree and
   are then updated according to the "refine" and "augment" statements.

   The identifiers defined in the grouping are not bound to a namespace
   until the contents of the grouping are added to the schema tree via a
   "uses" statement that does not appear inside a "grouping" statement,
   at which point they are bound to the namespace of the current module.

/martin

> would all appear to be in teas-te and not imported from
> e.g. te-typesin, in which case prefix are not needed.
> 
> So while I am sure you are right, and this is a significant problem,
> yet I cannot see the chapter and verse to back it up.
>

---

From: tom petch <[email-masked]>
Date: Wed, 23 Dec 2020 16:39:57 +0000

<inline>

From: Martin Björklund <[email-masked]>
Sent: 23 December 2020 13:59

p. 104 further says:

Section 6.4.1 says:

And 7.13 says:

<tp>
Martin,

Thank you for the comprehensive reply;  it is what I would have remembered until I looked in RFC7950 to check my understanding and read that first sentence on p.104 'identifiers are .. resolved' which I took as identifiers being given a prefix and so given global uniqueness; the subsequent  sentence on prefixes, types etc. I am fine with , it is the 'resolved' that made me doubt my memory.  What is 'resolved' in this context?

Tom Petch

/martin