Subject: Re: [netmod] Y26 again, sorry

From: Robert Wilton <[email-masked]>
Date: Mon, 5 Oct 2015 10:16:33 +0100

Hi Juergen,

Did you get a chance to consider this proposed text for mandatory nodes 
at all?

Thanks,
Rob

On 23/09/2015 14:50, Robert Wilton wrote:
> Hi Juergen,
>
> On 21/09/2015 09:26, Juergen Schoenwaelder wrote:
>> On Tue, Sep 15, 2015 at 10:00:46AM +0200, Ladislav Lhotka wrote:
>>> Juergen Schoenwaelder <[email-masked]> writes:
>>>
>> Still some text needs to be written explaining that breaking old
>> clients by adding new mandatory nodes is a no go. I did not ask to
>> enumerate all situations where it is allowed, I am looking for text
>> that clearly says what people have to look out for if they add
>> mandatory nodes.
> Would it be sufficient to just change the MUST NOT to SHOULD NOT and 
> then reference section 5.17.2 of draft-ietf-netmod-rfc6087bis which 
> seems to provide the explanation that you are requesting?
>
> E.g. something like:
>
> draft-ietf-netmod-rfc6020bis, section 7.17.  The augment Statement
>
> From:
>
> If the target node is in another module, then nodes added by the
> augmentation MUST NOT be mandatory nodes (see Section 3.1).
>
> To:
>
> If the target node is in another module, then nodes added by the
> augmentation SHOULD NOT be mandatory nodes (see Section 3.1).  The
> safe scenarios to augment with mandatory nodes are described in
> [draft-ietf-netmod-rfc6087bis] section 5.17.2.
>
>
> For reference, I've also reproduced the text for 
> draft-ietf-netmod-rfc6087bis-04] section 5.17.2 below:
>
> 5.17.  Augment Statements
>
>    The YANG "augment" statement is used to define a set of data
>    definition statements that will be added as child nodes of a target
>    data node.  The module namespace for these data nodes will be the
>    augmenting module, not the augmented module.
>
>    A top-level "augment" statement SHOULD NOT be used if the target data
>    node is in the same module or submodule as the evaluated "augment"
>    statement.  The data definition statements SHOULD be added inline
>    instead.
>
> 5.17.1.  Conditional Augment Statements
>
>    The "augment" statement is often used together with the "when"
>    statement and/or "if-feature" statement to make the augmentation
>    conditional on some portion of the data model.
>
>    The following example from [RFC7223] shows how a conditional
>    container called "ethernet" is added to the "interface" list only for
>    entries of the type "ethernetCsmacd".
>
>         augment "/if:interfaces/if:interface" {
>             when "if:type = 'ianaift:ethernetCsmacd'";
>
>             container ethernet {
>                 leaf duplex {
>                     ...
>                 }
>             }
>         }
>
> 5.17.2.  Conditionally Mandatory Data Definition Statements
>
>    YANG has very specific rules about how configuration data can be
>    updated in new releases of a module.  These rules allow an "old
>    client" to continue interoperating with a "new server".
>
>    If data nodes are added to an existing entry, the old client MUST NOT
>    be required to provide any mandatory parameters that were not in the
>    original module definition.
>
>    It is possible to add conditional augment statements such that the
>    old client would not know about the new condition, and would not
>    specify the new condition.  The conditional augment statement can
>    contain mandatory objects only if the condition is false unless
>    explicitly requested by the client.
>
>    Only a conditional augment statement that uses the "when" statement
>    form of condition can be used in this manner.  The YANG features
>    enabled on the server cannot be controlled by the client in any way,
>    so it is not safe to add mandatory augmenting data nodes based on the
>    "if-feature" statement.
>
>    The XPath "when" statement condition MUST NOT reference data outside
>    of target data node because the client does not have any control over
>    this external data.
>
>    In the following dummy example, it is OK to augment the "interface"
>    entry with "mandatory-leaf" because the augmentation depends on
>    support for "some-new-iftype".  The old client does not know about
>    this type so it would never select this type, and therefore not be
>    adding a mandatory data node.
>
>      module my-module {
>        ...
>
>        identity some-new-iftype {
>           base iana:iana-interface-type;
>        }
>
>        augment "/if:interfaces/if:interface" {
>           when "if:type = 'mymod:some-new-iftype'";
>
>           leaf mandatory-leaf {
>              mandatory true;
>              ...
>           }
>        }
>      }
>
>    Note that this practice is safe only for creating data resources.  It
>    is not safe for replacing or modifying resources if the client does
>    not know about the new condition.  The YANG data model MUST be
>    packaged in a way that requires the client to be aware of the
>    mandatory data nodes if it is aware of the condition for this data.
>    In the example above, the "some-new-iftype" identity is defined in
>    the same module as the "mandatory-leaf" data definition statement.
>
>    This practice is not safe for identities defined in a common module
>    such as "iana-if-type" because the client is not required to know
>    about "my-module" just because it knows about the "iana-if-type"
>    module.
>
>
>
> Rob
>
>
>>
>> /js
>>
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 5 Oct 2015 11:32:09 +0200

Robert,

I think this is listed as the first issue in our list of last call
comments.

/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: Robert Wilton <[email-masked]>
Date: Mon, 5 Oct 2015 10:46:02 +0100

Thanks. Yes.

I had missed that.

Rob