Re: [netmod] WG Last Call: draft-ietf-netmod-yang-instance-file-format-06

[Balázs Lengyel <[e-mail]>]

Hello Jurgen,
See answers below as "BALAZS3". I am putting them into the -08 revision this
weekend.
One general comment:
As partial data sets are allowed, it is not always necessary to indicate if
a feature is not supported. 
E.g. If you have an instance dataset for ietf-system, which does not include
authentication data, 
you do not care whether the feature  authentication is supported or not.
Similarly if the deviation does not impact your particular instance data
items, you might not care to specify it.
Regards Balazs

-----Original Message-----
From: Schönwälder, Jürgen <[e-mail]> 
Sent: 2020. február 19., szerda 11:17
To: Balázs Lengyel <[e-mail]>
Cc: Kent Watsen <[e-mail]>; NETMOD Working Group
<[e-mail]>
Subject: Re: [netmod] WG Last Call:
draft-ietf-netmod-yang-instance-file-format-06

On Thu, Feb 13, 2020 at 01:40:13PM +0000, Balázs Lengyel wrote:
> See below as BALAZS2.
> 
> -----Original Message-----
> From: Schönwälder, Jürgen <[e-mail]>
> Sent: 2020. február 12., szerda 10:07
> Subject: [Not Scanned] - Re: [netmod] WG Last Call:
> draft-ietf-netmod-yang-instance-file-format-06
> 
> >   - Is it necessary to describe P2 in terms of (presumably) NETCONF
> >     operations? I would prefer to have the document written in a
> >     protocol agnostic style. Perhaps simply drop "similar to the
> >     response of a <get> operation/request".
> > BALAZS: This is a reference both to NETCONF and RESTCONF. It was 
> > explicitly asked for by other reviewers.
> 
> Well, then the correct wording would be "similar to the response of a 
> NETCONF <get> operation or the RESTCONF response to a GET method 
> invocation on the (unified) datastore resource". Sounds complex and I 
> still prefer the text to be agnostic to specific operations - in 
> particular since <get> and the unified datastore have their 
> limitations. The format is simply reusing the already defined data 
> model encoding formats, i.e., the format has nothing to do with the
operations used to retrieve the data. So I suggest:
> 
>    P2  Instance data shall reuse existing encoding rules for
>        YANG defined data. 
> 
> There is no need to refer to specific protocol operations.
> BALAZS: I will use both of your texts. That is the most common 
> question I
> get: Will this use the same format as a get-reply? People like to 
> think in terms of a specific easy-to-grasp function instead of a 
> non-descript set of "existing" rules. Existing means you need to 
> understand X number of RFCs, while just looking up a get-reply is 
> easy. It is not precise, but IMHO that's how people think.

If you write "reuse existing encoding rules", then actually fewer documents
need to be understood. And operations have additional issues in how they
interact with 'datastores', so they may even be misleading and I rather have
the standards precise (and minimal normative dependencies).
BALAZS3: Sorry, I don't fully understand your point. What would you like in
P2? 
The text now is: 
P2  Instance data shall reuse existing encoding rules for YANG
       defined data.  Its format will be similar to the response of a
       NETCONF <get> operation or the RESTCONF response to a GET method
       invocation on the (unified) datastore resource.
It refers to existing rules as you asked for and also  says" similar" to a
get response, using phrasing from your email on 2020-02-12.  
Are you OK with this? Or how would you like to change it?
 
> >   - Why MUST XML attributes be ignored, why is there no text about
> >     unknown JSON data, 'attributes' (or annotations)? What should
> >     implementations generally do about unknown elements, attributes,
> >     objects, arrays, ...)? Why are we specific about only one specific
> >     case?
> > BALAZS:  Generally we want to allow users/creators to decorate the 
> > data with additional information, that is not standardized. Like 
> > YANG extensions  these may be useful, but at least should not cause
problems.
> > XML attributes are often used as meta-data and I was asked to list 
> > them specifically.
> > 
> I do not understand why there are specific rules for XML encodings but 
> not equivalent JSON rules. It looks like either the XML rules are not 
> needed or equivalent JSON rules are missing if the XML rules are 
> needed or there should be an explanation why the different encodings 
> lead to different results (which is operationally rather surprising).
> BALAZS2:XML has 2 distinct ways to encode information XML attributes 
> and elements.  JSON only has one uniform way. XML attributes are often 
> used to carry metadata which is a useful facility and they are not 
> used to encode "real" YANG defined data. So we want to allow the use 
> of XML attributes and not go for a least common denominator of the 2 
> encodings. IMHO it is a useful facility, IMHO it belongs here, but if you
insist I can remove it.

I believe this text is odd for what I wrote below.
BALAZS3: IMO as XML attributes are encoding specific (they do not exists in
JSON) the rules about them are also inherently encoding specific. 
I see no problem with allowing a special rule about them to allow the
customers to make use of this richer encoding. 
 
> If we want rules that apply to all encodings, they should be expressed 
> in an encoding neutral way. The current text and your response leaves 
> me puzzled what the specification really wants to say here. And do we 
> have to say something at all?
> 
> >     It is unclear what "will be very similar" really means but perhaps
> >     this is clarified later. If not, this sentence says nothing in
> >     terms of a technical specification.
> 

> 
> >   - I like to understand why we need several methods to specify the
> >     schema. Having N solution is always bad for interoperability and
> >     also for maintainability. Perhaps the WG failed to reach consensus
> >     on a single solution.  Or there are strong technical reasons - but
> >     then they should be clearly stated. What are implementations
> >     expected to support, all methods? Or whatever the implementer
> >     prefers? How do we achieve interoperability across tools?
> > BALAZS: Different people in the WG wanted different solutions.
> > - Some (as I remember you too) asked for a full flexible solution 
> > which can use multiple modules potentially not even the 
> > ietf-yang-library to define the schema  (Inline solution)
> > - some asked for a simple solution listing the content schema 
> > modules
> > - some wanted just to use a reference (If any this is the one, I 
> > would
> > remove)
> > - some stated that they do not want to define the content-schema at 
> > all because it is already known So we ended up with 4 methods
> 
> But reaching consensus by doing all four is not necessarily cheap. So 
> what are compliant tools required to implement. All 4 method?
> Whatever the implementer prefers? Or is there a mandatory to support 
> method (other than external ;-)? The WG needs to understand the costs 
> of having N ways to do the same thing.
> BALAZS: 2 methods are mandatory:  Simplified-Inline & URI. 
> Inline is controlled by a feature, so it is optional.  
> External is inherently optional, as whatever is outside this 
> specification is undefined thus it may or may not be supported.

This means that as soon as I have deviations or I am not supporting all
features (this can be quite likely), there is no guaranteed to be supported
way to communicate schema information. Well, if that is what the WG believes
is what we want...
BALAZS3: Often you will not care for non-supported features or data nodes,
you just don't provide the instance data for them. 
OK, I will add that if the feature inline-content-schema is supported, the
usage of ietf-yang-library MUST be supported. This guarantees a common
solution even in the complicated case where we do want to specify
features/deviations.
  
 
> In this case, I think it helps to spell out that users cannot assume 
> that instance data always represents consistent snapshots.
> BALAZS2: I would like to avoid the topic. We never stated anything 
> about the quality of data in the instance data set.
> E.g. if this is a snapshot of state data and it takes time to create a 
> snapshot, data might change even during creating the snapshot. This is 
> not described here or in Netconf or in Restconf.
> Why should we describe this in more details than the protocols.

I think the phrase 'snapshot of information at a specific point of time'
makes the difference for me. I do not think that RFC 6241 or RFC
8040 promise to create a snapshot or a snapshot of information at a specific
point of time.
BALAZS: OK> IMHO the word snapshot does not inherently mean consistent. But
I will change the wording:
New: "YANG instance data set is created at a specific point in time.  If the
data changes afterwards, ..."
 
> 
> > * Delivery of Instance Data
> > 
> >   - Why do we need this SHOULD? I do not think we should use RFC 2119
> >     keywords to define how organizations may use the instance data
> >     format. My proposal is to delete this entire section.
> > BALAZS: I will change it to lower case may.
> > I was asked to and I want to state that we want to use instance data 
> > both for offline delivery of design time information and for 
> > run-time delivery of other data.
> 
> But should this not be stated in the use cases and principles list in 
> section 2? I think section 5 is a mixture of a use-case concern and a 
> requirement (oops principle):
> 
>   PX: Instance data sets may be read from or produced by a live server
>       [is YANG server the proper term?] or they can be the result of a
>       specification or design effort that does not involve a live
>       server.
> 
> I think the essence of section 5 should be integrated into section 2.
> What it says seems misplaced in the middle of the document. (I 
> personally prefer to talk about objectives rather than principles but 
> that may be just
> me.)
> BALAZS: OK, I will move it into chapter 2 Introduction. This is really 
> not something mandatory on the implementation.

I still do not see why one use case gets a subsection while others are
elaborated on in the appendix. I am still not sure section 2.2 is needed. I
would rather add the proposed PX to the principles and dump section 2.2.
BALAZS3: This was explicitly requested by the group, on multiple occasions.
IMHO it is good information.
  
> > * Backwards Compatibility
> > 
> >   - I do not think 'managed entity' is a YANG term.
> > BALAZS: What term do you propose for something that is managed like 
> > an interface or user etc. ? I was told managed entity is a generic 
> > term that is commonly understood . Would "managed item" or "managed
thing"
> > be better?
> > 
> >   - I think this text is use case specific and the items are kind of
> >     conflicting with each other (2nd says changing the semantics of a
> >     list should lead to a change of the key while the 1st suggests
> >     that changing keys may lead to misinterpretation of something
> >     being new).
> > 
> >   - My proposal is to simply drop this entire section. If use case
> >     specific text is needed, add it to the use cases in the appendix.
> > BALAZS: You don't know how many trouble reports we got in multiple 
> > use-cases for violating these recommendations. While they may not be 
> > important for all use-cases, the are important for many.
> > Actually we met the problem or had to avoid it in all but one of the 
> > listed use-cases.
> 
> This text seems specific to certain use cases or best practices and as 
> such I suggest to integrate it into the appendix C. I do not think 
> this advice needs to be part of the technical instance data format 
> specification. One could even argue that some of this also concerns 
> config changes to live servers. My issue is that I find this 
> discussion misplaced - I like to to see the format definition separated
from any guidelines how to use it.
> BALAZS2: I still see this as important as proved by real life 
> situations and also as a n explicit request from the Yang versioning
requirements  draft.
> The text is specific to some use cases:  In practice relevant to 90% 
> of the use cases.

I understand that you care about this specific use case a lot and it might
be 90% in your estimation but this does not change my point that the text
seems guidelines text that I prefer to see separated from the technical
instance format specification and hence moved into the matching appendix.

BALAZS3: OK: This was explicitly requested by the group and IMO it is
important and have been seen in practice to be needed advice. But I can move
it into an appendix.
  
> 
> How much simplification is there really compared to the inline method 
> if I only list modules in the yang library schema without derivations 
> etc? See my earlier point about which schema formats are mandatory to 
> implement and whether the simplification is worth the extra code and 
> possible interoperability issues.
> BALAZS2:
> Compare:
> INLINE method:
>   <content-schema>
>     <inline-module>
>       ietf-yang-library@2016-06-21
>     </inline-module>
>     <inline-schema>
>       <module-state
>         xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
>         <module>
>           <name>ietf-yang-library</name>
>           <revision>2016-06-21</revision>
>         </module>
>         <module>
>           <name>ietf-netconf-monitoring</name>
>           <revision>2010-10-04</revision>
>         </module>
>       </module-state>
>     </inline-schema>
>   <content-schema>
> 
> SIMPLIFIED INLINE method:
>   <content-schema>
>     <module> ietf-yang-library@2020-01-14</module>
>     <module> ietf-netconf-monitoring@2020-01-14</module>
>   </content-schema>

The begining is static overhead (does not increase with # of modules) and
the rest marginal when it comes to tools reading this, at least not a big
enough argument for me to invent another format. And once you have a
deviation or a feature not implemented, you will need the longer format
anyway (or simply announce a schema that is not quite correct - I guess this
is what people will do).

BALAZS3: In practice (at least in Ericsson) humans also read and write the
instance data files, so static overhead is bad.  It is 18 lines versus 4.
People (Rob, and someone else maybe Reshad ?) explicitly asked for the
simple-inline format.  
   
/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]
<https://protect2.fireeye.com/v1/url?k=e6c5c1e7-ba4ecad8-e6c5817c-868f25761b
72-3c9e50798f5110a6&q=1&e=d2da5d9c-6439-4134-905f-953fbbdfbd43&u=https%3A%2F
%2Fwww.jacobs-university.de%2F>