Robert, I think this is listed as the first issue in our list of last call comments.
/js On Mon, Oct 05, 2015 at 10:16:33AM +0100, Robert Wilton wrote: > 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 protected]> 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 > >> > > > -- 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 protected] https://www.ietf.org/mailman/listinfo/netmod
