I see it is useful to relax the restriction on mandatory augment given several use cases that have been discussed on the list. The proposed changes get in line with draft-ietf-netmod-rfc6087bis-04 and look good to me.
-Qin -----邮件原件----- 发件人: netmod [mailto:[email protected]] 代表 Robert Wilton 发送时间: 2015年9月23日 21:51 收件人: Ladislav Lhotka; [email protected]; [email protected] 主题: Re: [netmod] Y26 again, sorry 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 > _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
