Subject: [NGO] YANG augment-stmt

From: Andy Bierman <[email-masked]>
Date: Mon, 10 Dec 2007 08:27:01 -0800

Hi,

Looking at the ABNF for the all-powerful augment statement,
I notice it can appear inside a list or inside an another augment,
anywhere a data-def-stmt can go in fact.

Since this clause does not instantiate any data where it
located, but rather at the target specified by the augment-arg-str,
the containment for the augment seems pretty much irrelevant,
except that the augment could be nested within N different 'when'
statements, nested inside obsolete nodes, etc.

The key in a list with an augment-stmt has no affect on the target data,
does it?

What does it mean to have an augment inside a grouping, so that
it is copied everywhere a 'uses' for that grouping is specified?

What is the use-case for augment inside augment?
That means while you are defining extra data to attach to /acme:foo
you also define some extra data for /a:bar/b:baz?

I have only seen augment examples that appear at the top-level.
Are there real examples of data models that actually need to
nest the augment-stmt anywhere and everywhere in the data model,
even inside the 'input' clause for an RPC method definition?

What are the requirements for WG or vendor data model augmentation exactly?

Andy

_______________________________________________
NGO mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ngo

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 10 Dec 2007 22:46:47 +0100 (CET)

> The key in a list with an augment-stmt has no affect on the target data,

I'm not sure I understand this question.

> What is the use-case for augment inside augment?

The use case for augment inside anything but on the top-level is to be
used in combination with 'uses'.  The idea is that you can do 'uses
foo', and then in a following augment add new nodes to the foo
grouping:

  grouping server {
    leaf name { type string; }
    container address {
      leaf ip { type inet:ip-address; }
    }
  }

  container foo {
    uses server;
    augment address {
      leaf port { type inet:port-number; } 
    }
  }      

Or the same thing as a reusable grouping:

  grouping server-with-port {
    uses server;
    augment address {
      leaf port { type inet:port-number; } 
    }
  }      
    
This way extensions to groupings ("complex types":) can be defined.

> you also define some extra data for /a:bar/b:baz?

Yes.

> What are the requirements for WG or vendor data model augmentation exactly?

I'm not sure I understand this question either.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 10 Dec 2007 22:50:44 +0100 (CET)

Hi,

I don't think there are any reasons to cross post this thread to yang
and ngo, so I suggest we keep the specific yang discussion on the yang
list only.  From now on then :)

/martin

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 11 Dec 2007 14:30:14 +0100

Hello,
Certainly some uses of augment could be really confusing, so if we could restrict it without 
ugly CLRs to the two use-cases it would be nice. Something like either use top level augment or 
an augment augmenting direct siblings like in Martin's example?
Imagine an augment within an augment both with a dynamic when condition or an augment within a 
choice etc.
Balazs

Martin Bjorklund wrote:
> YANG mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/yang

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Tue, 11 Dec 2007 09:12:10 -0800

> I'm not sure I understand this question.

It seems strange to me to define an augment of 'some' other data
in a potentially different namespace, in the middle of the constructs
that define named list entries.  I'm not clear on the use-case,
which is why I cc:ed the NGO list.  We need to agree on the requirements
for data model augmentation, just like every other part of
standard NETCONF content.

>       leaf port { type inet:port-number; } 

Is this right? Don't you mean:

    container foo {
      uses server {
        augment address {

I understand this use-case, where the descendant-schema-nodeid
is the target, instead of an absolute-schema-nodeid.

I still don't see any use-case for augment-within-augment,
or allowing nested augments to modify data structures outside
their parent node.

>> you also define some extra data for /a:bar/b:baz?

Why is this a feature, and what is it needed for?

> I'm not sure I understand this question either.

We should base the solution (DML) on the agreed-upon requirements.
The requirements should be based upon real use-cases.

IMO, there is a need for top-level augment clauses that name the target
with an absolute path expression, as well as nested augment clauses
that extend the data within their containment node (container, list,
choice/case-foo, rpc/input, rpc/output, notification).  It is
the DM writers choice which form to use.

You should use descendant form if 'when' clauses exist in any
ancestor nodes, instead of replicating the effective Xpath 'when'
expression for a top-level clause.

It boils down to 1 simple CLR:

    A top-level augment-stmt must use the absolute form,
    and a nested augment-stmt must use the descendant form
    of the schema-nodeid target of the augmentation.
    (A top-level augment-stmt has no context for descendants.)

The ABNF does not reflect this, or that only a choice augment
can use the case-stmt, or only an RPC augment can use the
input-stmt | output-stmt.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 11 Dec 2007 21:26:16 +0100 (CET)

Andy Bierman <[email-masked]> wrote:
> that define named list entries.

But this isn't allowed.  Only top-level augments can have absolute
paths to augment.  "Nested" augments MUST have descendant paths.

> I'm not clear on the use-case,

Ok.

>           leaf port { type inet:port-number; }

No, augment within a uses is not allowed.  I do see your point though
- if the use case is to allow augment of a 'uses', why not put the
augment within the uses.  The problem with this, as I see it, is that
it might be confusing b/c all the other stmts with 'uses' are
refinements of stmts found in the grouping.

> I still don't see any use-case for augment-within-augment,

  augment /foo/bar {
    uses my-grouping; // defines a container 'baz'
    augment baz {
      leaf xxx { ... }
    }
  }

> or allowing nested augments to modify data structures outside

No, that is not allowed.

> Why is this a feature, and what is it needed for?

Sorry.  My "Yes" should have been "No!!".

> The requirements should be based upon real use-cases.

Absolutely.

> expression for a top-level clause.

I don't see how this has anything to do with 'when'...?

>     (A top-level augment-stmt has no context for descendants.)

This is already in the draft.

> input-stmt | output-stmt.

Yes you're right, we should make this change in the ABNF.  Currently
it's just in the text.

/martin