Subject: [netmod] capability() and feature()

From: Andy Bierman <[email-masked]>
Date: Wed, 03 Dec 2008 14:03:27 -0800

Hi,

Here is another way to solve the capabilities vs. features problems,
using (mostly) existing mechanisms.  It also solves one of the
problems with if-feature in XPath.

Proposal: Add 2 functions to the YANG XPath context:

   boolean capability (QName);

       Returns 'true' if the capability identified by the QName string 
parameter
       is enabled.  False if capability is unknown or not enabled.  Protocol
       capabilities are identified by the prefix for the NETCONF base 
namespace
       and the name of the capability.  Vendor capabilities must use a
       different namespace.

   boolean feature (QName);

       Returns 'true' if the feature identified by the QName string 
parameter
       is enabled.  False if feature is unknown or not enabled.

   E.g.:
   
      when "capability('nc:candidate') and 
feature('acme:candidate-extensions')";

      when "capability('nc:partial-lock') and feature('pl:xpath')";

I know feature('foo') is the same thing as 'if-feature foo', but it
serves a purpose in XPath. You are not supposed to continue
AND expression evaluation once you hit a false result (just like C).

E.g., a a leaf augmenting the edit-config/input node:

   leaf my-test-mode {
      when "capability('nc:rollback-on-error') and 
../test-option='test-then-set'";
      type enumeration { ... }
   }

The feature() function allows when expressions to be
platform independent, and test conditional nodes only if the
feature is first enabled.

The capability() function allows access to protocol and vendor capabilities
in conditional schema nodes, without getting rid of features or adding
a YANG capability-stmt and if-capability.

E.g., a leaf augmenting the commit/input node:

  leaf my-rollback-options {
      when "capability('nc:confirmed-commit')";
      type bits { ... }
   }

Both functions together provide a DM designer with complete control
over the NETCONF environment, and XPath provides for much
more powerful expressions than if-feature alone.

Andy

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

---

From: Phil Shafer <[email-masked]>
Date: Wed, 3 Dec 2008 20:56:25 -0500

>   boolean capability (QName);

This would move features from a first class language construct to
a second (or third?) class one.  By using an explicit YANG statement,
we allow tools visibility into features without parsing XPath
strings.  This allows features to be handled directly without waiting
til runtime to evaluate "when" expressions.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Wed, 03 Dec 2008 19:00:57 -0800

> til runtime to evaluate "when" expressions.

I think XPath is a big part of YANG, and not 3rd order.
The DM writer can choose not to use the feature() function.
There is no option available for the capability() function
except define features for all the protocol capabilities.

XPath can prevent the definition of artificial features:

  leaf default-storage {
      description 
         "Defines the default storage location if the local-storage feature
           is not supported.";
     when "not(feature('local-storage'))";
     type "yang:uri";
  }
 
IMO, this is better than defining a feature called 'not-local-storage'.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 3 Dec 2008 22:28:02 -0500

>     when "not(feature('local-storage'))";

Consider the "when" expression:

    when "pigs > fly && feature('local')";

To know if this applies, I need to either
(a) evaluate it (using a XPath library),
(b) break it apart (using an XPath parser), or
(c) "know" via human inspection.

(a) is how most implementations will process XPath expressions
unless they are hard-coding for their particular device, in
which case (c) will be used.

But in many cases, I'd like to know at build time whether I
need to carry information about schema nodes on to my products.
If the product doesn't support 'local', I never need to ship
that part of the compiled YANG modules onto that device.

Making "if-feature" an explicit, first class YANG statement
allows me to do this.  Putting this into "when" means I'll
need to do (b) and some additional heavy lifting.

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 04 Dec 2008 10:57:23 +0100 (CET)

> need to do (b) and some additional heavy lifting.

I agree with this, and can add that moving this function into 'when'
fundamentally changes what a when expression is.  Currently, the
'when' expression can only reference data in the data tree.  So given
the expression and the entire data tree, the when expression evaluates
to the same value regardless of the device type.  By adding 'feature'
and/or 'capability' functions, this would no longer be true.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 04 Dec 2008 06:33:03 -0800

> and/or 'capability' functions, this would no longer be true.

Actually, these XPath conditionals can be used in notificaions
and RPC input/output also.

IMO, feature() is cleaner and much more versatile than if-feature.
Why invent yet another filtering mechanism with if-feature
or if-capability?

XPath provides a function library, so why not use it?
This 1st order vs. 3rd-order YANG clause doesn't seem
very compelling to me.  Looks a lot like 'not invented here'
syndrome instead.

XPath also provides a variable binding mechanism that I support with
extensions.  So I will implement $rollback-on-error=true
instead of capability('nc:rollback-on-error') = true.
That way, no new mechanisms need to be invented at all.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 4 Dec 2008 15:44:43 +0100

> Why invent yet another filtering mechanism with if-feature

I am with Phil and Martin on this. The when expression is conceptually
evaluated against the data tree at runtime as far as I can tell. The
feature mechanism is conceptually evaluated at compile time and not
really against the data tree if I understand things correctly.

If your argument is that a simple feature selection is not expressive
enough, then the solution should be to make the if-feature argument an
(xpath?) expression rather than a qname.

/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/>
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Andy Bierman <[email-masked]>
Date: Thu, 04 Dec 2008 06:57:58 -0800

> (xpath?) expression rather than a qname.

Then I strongly oppose the if-feature mechanism.
I do not want #ifdef in YANG.  I thought if-feature was just
like the when-stmt, except instead of the agent evaluating
an XPath expression against the target configuration, the
agent evaluates a boolean test based on the features
actually supported at runtime.

Now if-feature seems to be an extremely crude version of the C pre-compiler
construct #ifdef.  Changing it to #if (what about #else and #elif) is not
a good option -- I want to get rid of compile-time conditionals, not
make them 10X more complicated.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 4 Dec 2008 16:01:36 +0100

> make them 10X more complicated.

Features in data models that do not apply to all implementations are a
reality. I am unsure how you want to deal with this reality.

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 04 Dec 2008 07:13:48 -0800

> reality. I am unsure how you want to deal with this reality.

What a toolset does with the YANG modules is outside the
scope of the standard.  In fact, the only official purpose or use
for YANG is to convert it to YIN or DSDL.  So, do the if-feature
statements cause part of the DSDL translation to be skipped
if a feature is disabled?

The feature advertisement by a NETCONF agent addresses
the "I only support this much" problem, but that it at run-time.

To the NETMOD WG, compile-time means validation of
the YANG module, and translation to YIN or DSDL.
It has nothing to do with NETCONF agents or managers.

Why does YANG need #ifdef?

Andy

---

From: Phil Shafer <[email-masked]>
Date: Thu, 4 Dec 2008 11:22:13 -0500

Andy Bierman writes:
>In fact, the only official purpose or use
>for YANG is to convert it to YIN or DSDL.

This is simply not true.  YANG is a language that allows data models
for netconf to be defined.  There data models can be manipulated
via NETCONF.  YIN and DSDL are by-products that can be generated
from YANG, but are not the main purpose, let alone the "only official
purpose or use".

If you have gotten this idea from the YANG draft, the netmod-arch
draft, or the working group charter, please let me know and we can
address them.

>the "I only support this much" problem, but that it at run-time.

For a device, this isn't a runtime issue.  If my products won't
have disks, not supporting 'local-storage' isn't something available
at runtime.

>Why does YANG need #ifdef?

Your use of #ifdef is a strawman.  YANG needs the feature mechanism
to allow the data modelers to express the fact that portions of
their data model are optional.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Thu, 04 Dec 2008 08:47:14 -0800

> their data model are optional.

IMO, we can close this issue.
When validating a YANG module, or converting it to YIN or DSDL,
the supported features on a particular NETCONF agent implementation
are not relevant.

I never said the ability to specify partial module conformance was not
needed.  That is a strawman.

Andy

---

From: David Partain <[email-masked]>
Date: Mon, 15 Dec 2008 17:05:37 +0100

Hi,

> > (xpath?) expression rather than a qname.

I agree with Jürgen.

On Thursday 04 December 2008 15.57.58 Andy Bierman wrote:
> I do not want #ifdef in YANG.

That's exactly how I've thought of if-feature (despite the fact that #ifdef 
might be something people are allergic to) and think that it's a reality that 
the language should deal with.

As Phil wrote, I think that "YANG needs the feature mechanism
to allow the data modelers to express the fact that portions of
their data model are optional."

(Chair hat on) I agree with Andy that this issue can be closed...

Cheers,

David

---

From: Andy Bierman <[email-masked]>
Date: Mon, 15 Dec 2008 08:30:08 -0800

> (Chair hat on) I agree with Andy that this issue can be closed...

I think #ifdef was a non-issue; just a mis-understanding by me
on Martin's use of the term compile-time.  Most of the clever things
a toolset can do with YANG are traditionally out of scope in the IETF.

For the purpose of YANG file validation and translation
to YIN or DSDL, the if-feature-stmt has some affect.
One of the valid permutations of the feature-set
is 'all enabled', so it falls out that validation
of the entire YANG file is required.  In order
to check all permutations of the if-features for a node,
a compiler needs to find certain nodes that have more
features attached to them than some of their ancestor nodes.

yangdump checks that the child nodes specified in a key or unique
statement are not 'more conditional' than their ancestors
(back to the list). Also, the default case in a choice
cannot be more conditional than its parent.
I should do the same checks for must-stmt but that is TBD (and complicated).

Andy