Subject: [netmod] uses and augment

From: [email-masked] (Dale R. Worley)
Date: Wed, 22 Mar 2017 14:26:53 -0400

I've got a couple of questions about the interaction of "uses" and
"augment".  I hope that these have straightforward answers that the old
hands can tell me easily enough.

1. Augmenting a grouping

I notice that "augment" is not allowed to target a "grouping", despite
that naively seems to be an operation that a module designer might like
to do.  I expect that there is a reason why this is not allowed.

For example:

     module foo {
       ...
       grouping target {
         leaf address {
           type inet:ip-address;
           description "Target IP address.";
         }
         leaf port {
           type inet:port-number;
            description "Target port number.";
         }
       }
     }

     module bar {
       ...
       import foo {
	 ...
       }
       augment "/foo:target" {
         leaf new-leaf {
           type string;
         }
       }
    }

     module baz {
       ...
       import foo {
	 ...
       }
       container main {
         uses foo:target;
       }
    }

giving an effective schema:

       container main {
         leaf address {
           type inet:ip-address;
           description "Target IP address.";
         }
         leaf port {
           type inet:port-number;
            description "Target port number.";
         }
         leaf new-leaf {
           type string;
         }
       }

This construct seems to be well-defined to me, other than that it's not
immediately clear what namespace baz:main/new-leaf is in.  (For some
reason, I reflexively think that it's in bar's namespace, not baz's, but
I can't state any reasoning for that.)

2.  "augment" as a substatement of "uses"

In section 7.17:

   The "augment" statement allows a module or submodule ...  to add to
   the nodes from a grouping in a "uses" statement.

When I first read this, I took it to mean that an "augment" substatement
adds a peer node to the set of nodes 'from a grouping in a "uses"
statement'.  But I suspect that it is intended to mean that an "augment"
only adds nodes *under* one of the nodes from the grouping.  There's an
ambiguity that could be fixed by better wording.

7.17 also says:

   If the "augment" statement is a substatement to the
   "uses" statement, the descendant form (defined by the rule
   "descendant-schema-nodeid" in Section 14) MUST be used.

My understanding is that "descendant-schema-nodeid" is an XPath
expression, and that the "context node" for its evaluation is the node
to which the "uses" statement adds nodes -- but that doesn't seem to be
stated anywhere.

(Those last two I should have caught in my Gen-ART review!)

Thanks for any information,

Dale

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 22 Mar 2017 21:24:11 +0100 (CET)

> to do.  I expect that there is a reason why this is not allowed.

There were lots of debate over this one when we first designed YANG.
The main reason for not allowing this is that it can easily have
unintended consequences.  Module A uses a grouping G b/c it fits the
purpose.  Later someone augments G with some nodes; at this point it
is not at all clear that the additional nodes are suitable for module
A.

[...]

> ambiguity that could be fixed by better wording.

Ok.  Well, if you want to add a sibling node to the nodes in the
grouping it is trivial:

  grouping foo {
    leaf a { ... }
  }

  uses foo;
  leaf b { ... }

gives you:

   leaf a { ... }
   leaf b { ... }

> to which the "uses" statement adds nodes -- but that doesn't seem to be

Well, the syntax of descendant-schema-nodeid looks like an XPath path
expression in abbreviated form, but it is not defined in terms of
XPath, hence there is no text about any XPath context.  See also
section 6.5

/martin

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 22 Mar 2017 21:40:35 +0100

>             description "Target port number.";

This is not at all clear. You only import 'foo' - so why would the
augment of /foo:target (which is not exactly defined either) done in
'bar' apply to uses foo:target in baz? In short, it is unclear where
the augmentation of the grouping applies and where not. Augments are
restricted to things that have a well defined name in the data tree
because this makes it clear what is being augmented. One would have to
create additional language constructs to make augmentations of
groupings work.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: [email-masked] (Dale R. Worley)
Date: Thu, 23 Mar 2017 20:50:48 -0400

> is not at all clear that the additional nodes are suitable for module

True...  But assuming that the grouping G has clean semantics, it
corresponds to some facility in the device, which in some way or another
appears in multiple places in the device's data model.  And a module
that augments G adds semantics about that facility, and would only be
implemented by a device for which the facility uniformly has that
additional semantics.  So it would be suitable for every place where the
grouping is used.

It seems like this consideration applies to the "Yang mount" facility
also -- if a module A augments another module B, and module B is mounted
in several places in the full data model, then all the instances of
module B will be augmented.

> Ok.  Well, if you want to add a sibling node to the nodes in the

Of course, that works.  But what I'm considering is a modification of
the grouping which implicitly applies to all "uses" of that grouping --
because you don't want to have duplicate declarations of the added nodes
in every place the grouping is used.

> XPath, hence there is no text about any XPath context.  See also

OK, "context node" isn't the right term, but the idea still applies --
if the schema node identifier is descendant, the starting point for
reckoning the descending path has to be specified.

Juergen Schoenwaelder <[email-masked]> writes:
> 'bar' apply to uses foo:target in baz?

I'd say because that's what one would expect "augmenting" of a grouping
to mean.  Again, it looks like there will be similar behavior in "Yang
mount".

> Augments are restricted to things that have a well defined name in the
> data tree because this makes it clear what is being augmented. One
> would have to create additional language constructs to make
> augmentations of groupings work.

It's clear that *groupings* have well-defined names, because "uses"
statements can refer to them.  RFC 7950 section 7.13 isn't particularly
clear about how the argument string of the statement is to be
interpreted, but going back over 7950, I'm getting the idea that the
names of groupings are not descendant-schema-nodeid's, that is, named
based on where the grouping statement sits in the syntactic hierarchy,
but are in a separate namespace which is flat regarding equality and
inequality comparisons, but has elaborate scoping rules regarding which
groupings are visible in which locations.

OK, that clarifies why you can't apply "augment" to a grouping --
groupings (and thus the things defined within them) don't have names
that can be expressed by descendant-schema-nodeid's.

Dale

---

From: Andy Bierman <[email-masked]>
Date: Thu, 23 Mar 2017 17:59:19 -0700

Hi,

I think the reason this was rejected is because you cannot control
which "uses" of the grouping should get the augmenting nodes.
They all get the nodes.  There is no way for the uses-stmt to "opt-in"
to the new changes, except manually:

   grouping foo { ... }

   grouping new-foo {
       uses foo;
       // add new nodes via augment or data-def-stmt;
   }

By forcing the "uses foo" to change to "uses new-foo",
the data model designer is explicitly accepting the new changes.

Note that import-without-revision can also cause the uses-stmt
to expand differently as the imported module changes over time.
This is a separate problem.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 24 Mar 2017 07:31:38 +0100

> additional semantics.  So it would be suitable for every place where the

But this is an assumption and it is not generally true.

[...]
 
> But what I'm considering is a modification of

There may be cases where this may appear useful but I see also cases
where people will get largely suprised by the result if such wildcard
augmentations would be possible.

> statements can refer to them.

I wrote 'name in the data tree' and I meant 'name in the schema tree'
(sorry). Augments apply to something that has a name in the schema
tree, groupings do not have that.

   The "grouping" statement is not a data definition statement and, as
   such, does not define any nodes in the schema tree.

> RFC 7950 section 7.13 isn't particularly

Yes.

> that can be expressed by descendant-schema-nodeid's.

Yes. This is how things were defined.

/js