Re: [Netconf] Editorial change-2 for draft-ietf-netconf-nmda-netconf

On 04/06/2018 11:17, Martin Bjorklund wrote:
> Hi
>
> Two comments inline.
>
> Robert Wilton <rwilton@cisco.com> wrote:
>> Hi Rohit, authors,
>>
>> I think that these are valid clarifications. I've reworded them
>> slightly, and moved the ancestor node text to the YANG module
>> instead.  I also think that the ancestor node text generically covers
>> the config filter clarification that you raised previously.
>>
>> Hence, I propose the following diff to the NETCONF NMDA draft:
>>
>> rwilton@rwilton-lnx:~/netconf-wg/netconf-nmda$ git diff --staged
>> diff --git a/ietf-netconf-nmda.yang b/ietf-netconf-nmda.yang
>> index f2929b9..72a674a 100644
>> --- a/ietf-netconf-nmda.yang
>> +++ b/ietf-netconf-nmda.yang
>> @@ -105,6 +105,9 @@ module ietf-netconf-nmda {
>>          by get-data must satisfy all filters, i.e., the filter
>>          criteria are logically ANDed.
>>
>> +       Any ancestor nodes (including list keys) of nodes matched by
>> +       the filter are included in the response.
>> +
>>          The 'with-origin' parameter is only valid for an operational
>>          datastore. If 'with-origin' is used with an invalid datastore,
>>          then the server MUST return an <rpc-error> element with an
>> @@ -193,7 +196,7 @@ module ietf-netconf-nmda {
>>             description
>>               "Filter based on the 'origin' annotation.  A node matches
>>                the filter if its 'origin' annotation is not derived
>> -             from and not equal to all of the given filter values.";
>> +             from and not equal to any of the given filter values.";
>>           }
>>         }
>>
>> diff --git a/nmda-netconf.org b/nmda-netconf.org
>> index e44e2c7..100e173 100644
>> --- a/nmda-netconf.org
>> +++ b/nmda-netconf.org
>> @@ -129,14 +129,17 @@ The "config-filter" parameter can be used to
>> retrieve only "config
>>   true" or "config false" nodes.
>>
>>   The "origin-filter" parameter, which can be present multiple times,
>> -selects nodes matching any of the given values. The
>> -"negated-origin-filter", which can be present multiple times, selects
>> -nodes that do not match all given values. The "origin-filter"
>> -and "negated-origin-filter" parameters cannot be used together.
>> +selects nodes with origins matching, or derived from, any of the
>> given
> I would prefer:
>
>   selects nodes with origins equal to, or derived from, any of the
>   given
>
>
> IMO, the term "match" in the original text means "equal to or
> derived-from", as explained in the data model.
>
> The term "match" is problematic unless it is explained, b/c some
> people will think it means "equal to".  (Noone will think that
> "matches the regular expression" means "equal to the regular
> expression" though...)
>
> Conclusion: always avoid the term "match".
OK.

>
>> +values. The "negated-origin-filter", which can be present multiple
>> +times, selects nodes with origins that do not match, and are not
>> +derived from, any of the given values. The "origin-filter" and
>> +"negated-origin-filter" parameters cannot be used together.
>>
>>   The "max-depth" parameter can be used by the client to limit the
>>   number of sub-tree levels that are returned in the reply.
>>
>> Note to the authors, for the negative-origin-filter, I've also changed
>> "all" to "any" (which changes the semantics, but I think it was wrong
>> before).
> Agree that "any" is correct.
>
> But does it really change the semantics?  "all" sounds quite odd, but
> isn't the end result the same?
I think that it is confusing, and probably depends on how you read it.

But, if you are OK with "any" then I think that reads better and is more 
intuitive.

Thanks,
Rob

>
>
> /martin
>
>
>> Similar updates will need to also be done to RESTCONF, but let's agree
>> the NETCONF text first.
>>
>> Thanks,
>> Rob
>>
>>
>> On 01/06/2018 10:10, Rohit R Ranade wrote:
>>> Hi All,
>>>
>>> Section 3.1.1
>>>
>>> OLD:
>>>
>>>     The "origin-filter" parameter, which can be present multiple times,
>>>
>>>     selects nodes matching any of the given values.  The
>>>
>>> "negated-origin-filter", which can be present multiple times, selects
>>>
>>>     nodes that do not match all given values.
>>>
>>> NEW:
>>>
>>> The "origin-filter" parameter, which can be present multiple times,
>>>
>>>     selects nodes which are derived from or matching any of the given
>>> values.  The
>>>
>>> "negated-origin-filter", which can be present multiple times, selects
>>>
>>>     nodes which are not derived from and do not match all given values.
>>>
>>> When a data-node matching the filter is selected, the configuration
>>> ancestors
>>>
>>> (if any) and list key leafs (if any), even if they do not match the
>>> filter, are also returned.
>>>
>>> Consider two origins such as “learned” and “derived-from-learned”.
>>>
>>> “derived-from-learned” is derived from learned origin.
>>>
>>> Using the origin filters it is not possible to get nodes belonging to
>>> “learned”
>>>
>>> only as the nodes of derived origin are automatically selected.
>>>
>>> Notes:
>>>
>>> The text in 3.1.1 did not include the “derived-from” logic for
>>> selection , while in the data-model definition it was present.
>>>
>>>   We can also add clarification about the ancestor and key being
>>> output, even if though they do match the filter, since the leaf
>>>
>>> matches the filter.
>>>
>>> Example : We can use the RFC 8342 Appendix C.2 BGP Example
>>>
>>>     <rpc message-id="101"
>>>
>>> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>>>
>>>       <get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda"
>>>
>>> xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">
>>>
>>> <datastore>ds:running</datastore>
>>>
>>> <subtree-filter>
>>>
>>>           <bgp xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda"/>
>>>
>>>        </subtree-filter>
>>>
>>> <negated-origin-filter>intended</negated-origin-filter>
>>>
>>> <with-origin>true</with-origin>
>>>
>>>       </get-data>
>>>
>>> </rpc>
>>>
>>>     <rpc-reply message-id="101"
>>>
>>> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>>>
>>>       <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
>>>
>>>        <bgp xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
>>>
>>> or:origin="or:intended">
>>>
>>>         <peer>
>>>
>>> <name>2001:db8::2:3</name>
>>>
>>>           <local-as or:origin="or:default">64501</local-as>
>>>
>>>           <peer-as or:origin="or:default">64502</peer-as>
>>>
>>>           <local-port or:origin="or:system">60794</local-port>
>>>
>>>           <remote-port or:origin="or:default">179</remote-port>
>>>
>>> <state>established</state>
>>>
>>>         </peer>
>>>
>>>        </bgp>
>>>
>>>       </data>
>>>
>>>     </rpc-reply>
>>>
>>> With Regards,
>>>
>>> Rohit R Ranade
>>>
>>>
>>>
>>> _______________________________________________
>>> Netconf mailing list
>>> Netconf@ietf.org
>>> https://www.ietf.org/mailman/listinfo/netconf