Subject: [netmod] Consensus call on yang-00088: new "refine" statement

From: David Partain <[email-masked]>
Date: Fri, 17 Oct 2008 15:06:11 +0200

Greetings,

This is a call for consensus about issue 'yang-00088: new
"refine" statement'.  See the wiki at
http://wiki.tools.ietf.org/wg/netmod/trac/wiki/Issues_yang#issue-00088

This mail and other consensus calls after the interim will follow
a similar pattern.  First, we have the question and the proposed
consensus, then details.  The details include examples, followed
by a summary of the interim discussion on the issues.  Please
read the whole message.

PLEASE speak up if you favor or object to the proposed change,
including people who attended the interim.  Silence is impossible
to interpret.

This issue on the wiki actually is about 4 interrelated issues,
all of which have a proposed consensus in this mail:

1. Should we add a refine statement (assuming we have 'augment'
   inside uses) in "uses"?

   Rough Consensus from the interim: make this change

2. Should we have an 'augment' statement inside the 'uses'
   (while keeping the top-level 'augment')?

   (very) Rough Consensus from the interim: make this change

3. Should we put a "when" as a substatement of a leaf?

   Rough Consensus from the interim: yes, assuming #2 is yes.

4. Should we have two 'augment' keywords?

   Rough Consensus from the interim: yes, assuming #2 is yes.

More details below...

The current way YANG does things is to use an overlay and a
conditional change.  For example:

container x
  augment . {
  when "..." ;
  leaf a { foo } ;
  }

------------------------------------------------------------------
First subissue: 1. Should we add a refine statement (assuming
we have 'augment' inside uses) in 'uses'.

That would look like this:

uses foo {
  refine "b/c" {
    default 42;
    ...
  }
}

First consensus call is to determine whether we're going to add
the refine statement and change the "overlay" way of doing things
that we do today (see above).  The sense of the room at the
interim was that we have rough consensus to do so.

However, adding separate keywords for refining each kind of node
(refine-leaf, refine-container, etc.) generated no support, so
that is off the table.

------------------------------------------------------------------
Second subissue: 2. Should we have an 'augment' statement inside
the 'uses' (while keeping the top-level 'augment')?

That would mean, for example:

uses foo {
  augment "b/c" {
    ...
  }
}

This is 'just a syntactic change'. You cannot do more than you
could before.  Advantage is that you know which node the 'uses'
come from.

This does not disallow the top-level augment; it adds the augment
to 'uses'.  'augment' was originally written to add nodes to a
different namespace.  At the top-level, 'augment' adds nodes to
someone else's namespace, whereas this 'augment' adds to the
current namespace.

It also means we no longer have definitions spread out in
seemingly unrelated places.  Moving the augments inside uses
forces you to collect related statements (the augment and the
uses).  Forces model writers to collect related information
rather than spreading it around.

The interim had very rough consensus to make this change.  The
primary argument for was the clear association of the 'augment'
with the definition of the 'nodes' being augmented (clarity).
Some of the arguments against were that what we have works fine
and a worry of lost flexibility (unclear what flexibility,
though).

------------------------------------------------------------------
Third subissue: 3. Should we put a "when" as a substatement of a leaf

If we move augment to the uses statement (see previous subissue),
we need to have "when" 'everywhere' (leaf, leaf-list, container,
grouping, case, choice, notification, input, output).

Rough concensus from the interim was that if #2 is introduced,
this should be as well.

------------------------------------------------------------------
Fourth subissue: 4. Should we have two 'augment' keywords?

Should we have two keywords (for top-level 'augment' and for
'augment' inside uses)?  For example, the 'augments' under uses
could be called "extend".

Rough consensus in the meeting to have two different names.  What
the second name should be has not been decided.

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

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 17 Oct 2008 21:14:14 +0200

Hi,

I am strongly in favor of all these changes, they make the language more
predictable. My suggestion for the new name of top-level augment is
"insert".

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 17 Oct 2008 21:34:31 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> Hi,
> 
> I am strongly in favor of all these changes

+1

> My suggestion for the new name of top-level augment is "insert".

I pefer to keep the top-level statement called 'augment', since this
usage is most similiar to how the term is used in SMIv2.

I suggest 'extend' for the other statement.  When a grouping is used,
it can be refined and extended.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 18 Oct 2008 09:10:52 -0700

>    Rough Consensus from the interim: make this change

no -- IMO the current approach, which is slightly more
verbose, is more readable because the type of contrust
(container, list, leaf, etc.) is present, and all the
refinements are forced to be within the one and only
containment section for a given node.

The refine approach assumes that the reader is very
familiar with XPath, and with all the schema node types
associated with the QNames in the XPath expression.
Multiple refine-stmts for the same node can be present,
as well as refinements in any order.

Since YANG is new, and since the data models are always
going to be new to a DM reader, and since YANG's main
reason for existing is readability, it seems better
to stick with the current approach.

>    (very) Rough Consensus from the interim: make this change

no -- I prefer the current approach which has the 'when'
clause within the augment-stmt.  Forbidding augment (or extend)
outside of a uses-stmt seems like a CLR to me.

>    Rough Consensus from the interim: yes, assuming #2 is yes.

no -- I prefer to think of the data model as the base
contract, that is augmented when the specified condition
is true.  Changing the model to a bunch of random nodes
that only exist when the specified conditions are true
is a more complicated model.

IMO, YANG has too many conditional constructs, which
interact in ad-hoc ways.  The current augment-stmt
gathers all the additions in one place,
with one 'when' clause.  This makes it more clear
to the reader what is going on.  Sprinkling the
same complicated 'when' clause all over the place
(or is it the same?) can make it much harder for a reader
to correctly interpret the data model contents.

>    Rough Consensus from the interim: yes, assuming #2 is yes.

yes -- it might be useful to easily identify a
construct that is augmenting another XML namespace (module),
vs. an construct that is augmenting the same XML namespace.

Calling them (top-level) augment and (nested) augment
is not even accurate, because a top-level augment can
name a local or remote object with an absolute XPath.

A new name for an augment that affects a different namespace
is a good idea -- augment-extern?

Andy

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 28 Oct 2008 21:34:52 +0100

See below!
Balazs

>    Rough Consensus from the interim: make this change
I assume the things that can be refined are not changed by this proposal. Otherwise we need a 
separate debate on that. Don't really care.
>    (very) Rough Consensus from the interim: make this change
YES, collecting relevant definitions into one place is nice.
>    Rough Consensus from the interim: yes, assuming #2 is yes.
Was it just leaf or other statements as well e.g. list, leaf-list, etc???
>    Rough Consensus from the interim: yes, assuming #2 is yes.
Don't care.