Subject: [netmod] yang-04: when-stmt and rpc/input

From: Andy Bierman <[email-masked]>
Date: Sat, 04 Apr 2009 08:56:57 -0700

Hi,

The section on the rpc input statement is not clear enough.

I don't know what para 2 means:

    If a container in the input tree has a "presence" statement, the
    container need not be present in a NETCONF RPC invocation.

An NP container does not have to be present unless it has
1 or more mandatory descendants.  Let's not override the
mandatory true/false flag in this special case (rpc/input).
If the container is mandatory=false then it is optional.
The presence-stmt is still relevant.  Somebody could define
an RPC method where an empty container meant something
and they would put it in the presence-stmt.

The when-stmt is not mentioned at all.
IMO, the agent should ignore when-stmt for rpc/input.
The 'delete-all-false-when-stmts' procedure does not
make any sense on an RPC invocation, if the XPath expression
includes any nodes in the RPC definition itself.

A procedure for processing when-stmt on rpc/input
is needed, or some text that says it does not apply
to the agent.

7.19.5.  The when Statement

    The "when" statement makes its parent data definition statement
    conditional.  The node defined by the parent data definition
    statement is only valid when the condition specified by the "when"
    statement is satisfied.

I don't know exactly what 'valid' means in sentence 2 above.
I know what it means for must-stmt: for a <commit>, or an
<edit-config> on <running/>, the result must satisfy the
must expressions.

For when-stmt, it seems the agent just silently deletes false nodes.
This does not seem like a good idea on /rpc/input contents.
It seems strange to return an 'unknown-element' error
in this case, but that is the closest error code.
Maybe another error-app-tag (false-when-expr?) might
help applications figure out what went wrong.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 08 Apr 2009 13:03:03 +0200 (CEST)

Hi,

Andy Bierman <[email-masked]> wrote:
> 1 or more mandatory descendants.

I see what you mean.  I suggest we simply remove this sentence.

> IMO, the agent should ignore when-stmt for rpc/input.

Section 7.19.5 The when Statement specifies how the when statement is
used in rpc input/output.  I believe it was the consensus to allow
when in rpcs (see the mail thread called "Proposed consensus mail on
yang-00172"), so I'd rather fix the text in the RPC section instead.

I propose this text in section 7.13.2 (and similar in 7.13.3):

  If any node has a "when" statement which would evaluate to
  false, then this node MUST NOT be present in the input tree.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 09 Apr 2009 09:31:00 -0700

> I see what you mean.  I suggest we simply remove this sentence.

yes

>   false, then this node MUST NOT be present in the input tree.

This is different than the 'silently delete all false when-stmt nodes'
procedure used on the database target(s).  I think returning
an 'unknown-element' error is confusing, but so is deleting/ignoring
false when-stmt nodes.

I'm a bit unclear on the use-cases for when-stmt in rpc/input.
I can see if-feature quite easily, but not when-stmt.
Does anyone have any use-cases for this, or are we just
adding complexity every opportunity we get?

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 14 Apr 2009 11:06:37 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> procedure used on the database target(s).

But it is consistent with this, from the Payload Parsing section:

- If data for a node tagged with "when" is present, and the "when"
  condition evaluates to "false", the server MUST reply with an
  'unknown-element' error-tag in the rpc-error.

> adding complexity every opportunity we get?

I think we want to avoid having too many special cases for these
statements - if the semantics of a particular statement combination is
clear then it is allowed.   There are some cases where the semantics
are unclear, and where we thus do not allow it, e.g. for 'ordered-by'
we have:

  This statement is ignored if the list represents state data, RPC
  output parameters, or notification content.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 14 Apr 2009 07:09:08 -0700

>   'unknown-element' error-tag in the rpc-error.

I strongly disagree with this text.
The false node stuff applies (like must-stmt) to valid configurations.
The false when-stmt test does not apply to the candidate config.
That test only applies to the running config.
The candidate is allowed to be invalid.

> are unclear, and where we thus do not allow it, e.g. for 'ordered-by'

I guess you can't think of a single use-case either.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 14 Apr 2009 20:53:56 +0200 (CEST)

> The candidate is allowed to be invalid.

But that's not how "when" works.  The difference between "when" and
"must" is how the constraint is enforced.  "when" can be viewed as a
generalization of "choice"; they share the same processing model and
behavior. 

> I guess you can't think of a single use-case either.

Any discriminated union, such as:

  input {
      leaf ip-version {
          type inet:ip-version;
      }
      container ipv4-params {
          when "../ip-version = 'ipv4'";
          ...
      }
      container ipv6-params {
          when "../ip-version = 'ipv6'";
          ...
      }
      ...
  }

Or any case where "when" is used in a grouping which is used in "rpc".

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 14 Apr 2009 12:17:19 -0700

> Or any case where "when" is used in a grouping which is used in "rpc".

The difference between when-stmt and choice-stmt
is that a choice is well-constrained and contained.
The when-stmt is arbitrary XPath.  Silently deleting
all the false nodes in the scratch-pad database
seems harder to use to me, but it doesn't
matter that much.  The astonishment train
left the station already anyway. ;-)

I would prefer a real discriminated choice, if
that is important enough to have.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Wed, 15 Apr 2009 09:34:12 -0700

Martin Bjorklund wrote:
.....
> generalization of "choice"; they share the same processing model and

Then I think some error handling procedures (new error-app-tag?)
are needed to deal with problems with 'silent-delete'.
If an <edit-config> operation would result in the deletion
of nodes that are partial-locked or the session is not authorized
to delete, then the <edit-config> MUST fail with some error-tag.
It will confuse the manager to get back <error-path> values
for nodes that are completely unrelated to the actual target
of the edit (especially access-denied).

An actual <configChanged> notification is going to be
needed as well, for this thing to move out of the sandbox.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 15 Apr 2009 21:29:17 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> > behavior. >...

There are some kinds of errors where the error-path will refer to an
object which is not in the PDU.  'when' and 'must' are two examples.

For 'access-denied', you will get the same behaviour if you have
access to one case but not another in a choice.  Also, I think I have
seen recommendations to not include error-path in 'access-denied'
errors, for security reasons?

/martin