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

From: Kent Watsen <[email-masked]>
Date: Sun, 9 Feb 2020 19:23:08 +0000

This message closes the WGLC.

Authors, please respond to Juergen’s message from Jan 20, ultimately posting an update to the draft.

Thanks,
Kent // as shepherd

> On Jan 7, 2020, at 7:41 AM, Kent Watsen <[email-masked]> wrote:
> 
> 
> This begins a two-week Working Group Last Call (WGLC) on draft-ietf-netmod-yang-instance-file-format-06.  The WGLC ends on Jan 21.  Please send your comments to the working group mailing list.
> 
> Positive comments, e.g., "I've reviewed this document and believe it is ready for publication", are welcome!  This is useful and important, even from authors.  Objections, concerns, and suggestions are also welcomed at this time.
> 
> Thank you,
> NETMOD Chairs
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Balázs Lengyel <[email-masked]>
Date: Tue, 11 Feb 2020 17:15:23 +0000

-----Original Message-----
From: netmod <[email-masked]> On Behalf Of Schönwälder, Jürgen
Sent: 2020. január 20., hétfő 15:46
To: Kent Watsen <[email-masked]>
Cc: NETMOD Working Group <[email-masked]>
Subject: Re: [netmod] WG Last Call:
draft-ietf-netmod-yang-instance-file-format-06

On Tue, Jan 07, 2020 at 12:41:23PM +0000, Kent Watsen wrote:
> 
> This begins a two-week Working Group Last Call (WGLC) on
draft-ietf-netmod-yang-instance-file-format-06.  The WGLC ends on Jan 21.
Please send your comments to the working group mailing list.
> 
> Positive comments, e.g., "I've reviewed this document and believe it is
ready for publication", are welcome!  This is useful and important, even
from authors.  Objections, concerns, and suggestions are also welcomed at
this time.

I have reviewed draft-ietf-netmod-yang-instance-file-format-06. I believe
this is an important document but not quite ready yet. Most of the points I
am raising below should, however, be easy to resolve, many concern
terminology and writing consolidation and do not affect the technical
solution.

/js

* Abstract

  I think we should avoid referring to some <get> operation. Here is a
  proposal of a rewrite:

OLD

   running server available.  This document specifies a standard file
   format for YANG instance data (which follows the syntax and semantic
   from existing YANG models, re-using the same format as the reply to a
   <get> operation/request) and annotates it with metadata.

NEW

   running server available.  This document specifies a standard file
   format for YANG instance data, which follows the syntax and semantic
   of existing YANG models, and annotates it with metadata.
BALAZS: Other have expressly asked for a reference to "get" but if you want
I can remove it.

* Terminology

  - Add missing dots (full stops) at the end of sentences
BALAZS: OK

  - I fail to see the difference between 'content-schema' and 'content
    defining YANG module(s)'. The 'content-schema' is already a set of
    YANG modules. I suggest to remove 'Content defining YANG module(s)
    as it is not a necessary term. Rewrite all places where the phrase
    'content defining YANG modules' is used.
BALAZS: a schema is a full set of YANG modules needed to define the 
structure and properties of the instance data (+features, deviations).  
A  "content defining YANG module" is an individual YANG module is 
part of the content-schema. So the difference is a set versus one item. 
I updated the description to emphasize this difference.

  - Is "YANG Instance Data" a newly defined term? It's introduction
    does not follow the colon style. I also wonder why we need this
    term. Why is YANG in there? I would prefer to have this defined in
    RFC 7950 terms. Is 'instance data' a collection of instantiated
    'data nodes'? Perhaps then we should do the following and move
    this up to the first definition, so we define instance data first,
    then instance data set, and finally instance data file.

    OLD

   YANG Instance Data, or just instance data for short, is data that
   could be stored in a datastore and whose syntax and semantics is
   defined by YANG models.

    NEW

   Instance Data: A collection of instantiated data nodes.
BALAZS: OK, updated. 

* Introduction

  - It seems UC5 subsumes UC4.
BALAS: OK UC4 and 5 merged

  - One could add UCx: Storing instance data used as test cases but
    then this list of use cases does not need to be exhaustive (means
    I do not care much).
BALAZS: Valid use case, but not added for now. If you say so I can add it.

  - 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. 

  - P4: What is 'many'? Or did you want to use 'multiple'?
BALAZS: OK, changed to multiple,

* Instance Data File Format

  - Replace "real data" with instance data

  OLD

    "real data" that we want to document/provide.

  NEW

    instance data that we want to document/provide.
BALAZS: OK

  - I do not understand that text about the default attribute. Section
    4.8.9 defines a query parameter, not an attribute. And I do not
    know how that fits into content data.
BALAZS: https://tools.ietf.org/html/rfc8040#section-4.8.9:
" If the "with-defaults" parameter is set to "report-all-tagged", then
   the server MUST adhere to the default-reporting behavior defined in
   Section 3.4 of [RFC6243].  Metadata is reported by the server as
   specified in Section 5.3.  The XML encoding for the "default"
   attribute sent by the server for default nodes is defined in
   Section 6 of [RFC6243].  The JSON encoding for the "default"
   attribute MUST use the same values, as defined in [RFC6243], but
   encoded according to the rules in [RFC7952].  The module name
   "ietf-netconf-with-defaults" MUST be used for the "default"
   attribute. "
Here the usage of the default ATTRIBUTE is defined.

  - Similarly, I do not understand why implementation specific
    metadata may be included in the content-data. This seems to be the
    wrong place, no? Should metadata not go into the header?
BALAZS: As this might be meta-data about the individual instance 
data nodes (e.g.  metadata following the principles from rfc7952) it belongs
here.

  - 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.

It is not stated what an application should do with additional unknown data 
(XML elements, JSON data) that do not fit the above categories.  Should we
say something about it? 
IMHO no. We don't want to be too restrictive, as there are many potential 
users with different needs. We could state
 "Users of the instance data MAY discard any other unknown data".
However that does not mean much. 

  - References may be helpful in this sentence since <get-data> is not
    part of the original NETCONF specification:

   The content-data part will be very similar to the result returned for
   a NETCONF <get-data> or for a RESTCONF get operation.
BALAZS: OK: will add reference.

    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.

  - Does the following sentence imply that any additional data in an
    instance file renders the instance file useless?

   The content-data part MUST conform to the content-schema.
BALAZS: Maybe not useless, but at least partly corrupt.

  - You first write that instance data MUST conform to the schema and
    two paragraphs later you state that instance data MAY be partial,
    i.e., it MAY NOT conform to the content-schema. Perhaps I have an
    idea what you wanted to say but the text that is written here is
    a contradiction.
BALAZS: OK. I will correct it. The content-data part MUST conform to 
the content-schema, while allowing for the   exceptions listed below.

  - The introduction contains several MAYs and MUSTS that are not
    understandable yet and they do not seem to belong into an
    'Introduction' in the first place.
BALAZS: Section 2 Introduction 1 'may'
" further instance data formats may be specified"
I was specifically asked to include this. Why is this not understandable? 
Where should this be if not in the introduction chapter?
Section 2 does not contain the word must. 
Maybe I am not understanding your comment.

  - Why is EXTERNAL in all caps but Inline in capitalized form?  In
    the YANG definitions, EXTERNAL seems to be uri. I think we reduce
    ambiguity by being consistent with how we name things.
BALAZS: OK, EXTERNAL should not be all caps. 
Here external means that the content-schema is defined externally 
to the instance data set, not even a URI is included.

  - What is a 'real-life YANG module'?
BALAZS: OK,  will rephrase it. 

  - 3.1.1 How are the details specified in the anydata? Perhaps a
    forward reference might help. What are 'version labels'?
BALAZS: Added reference to example.
Version/Revision labels are defined in
draft-verdt-netmod-yang-module-versioning; 
added as a reference. I added them here (only as an example) as they are 
highly relevant to specifying module versions even if they are not 
agreed in Netmod yet. The name was changed from version-label to
revision-label lately.

  - 3.1.2 What is a 'list of content'? Which revision is used? What
    about these 'version labels' here?
BALAZS: You cut the sentence in half: List of content defining YANG modules"
The term "Content defining YANG module" is defined in the terminology
section.
In this case there is no possibility for using version/revision labels.
People asked for a simple method.

  - 3.2 I do not understand the example. Has this been validated?  As
    far as I can tell, the ietf-yang-library defines modules-state and
    not module-state. This inconsistency shows up multiple times.
BALAZS: Corrected to modules-state

  - 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

* Data Life Cycle

  - I am not sure the first paragraph is needed.
BALAZS: OK removed

  - In the second paragraph, I like to see some discussion of snapshot
    consistency.  How much consistency can be expected? Are there
    indicators for the level of consistency? I would remove the
    sentence about "valid values can be retrieved at run-time" as this
    is obvious but then I am not sure why 'valid' values? Perhaps the
    authors meant 'current' values?
BALAZS: OK< Changed to current. I want to keep the second sentence 
as it describes the duality between the original documented values and
 the current values that can be read in run-time.
Consistency is out of scope. No indicators are provided. It is very 
much use-case and implementation specific.

  - How do I implement the "SHOULD be described"? The default is that
    data can change, only in rare cases data is static. But how does a
    tool creating instance data know 'when and how' data changes in the
    future? I suggest to remove the SHOULD. The text saying that instance
    data is a snapshot is in my view sufficient.
BALAZS: We do not want to specify the how the changes should be described, 
But we do want to state that this information should be made available.
Just a few ideas how this could be done. Provide
- some plain text in the description of the instance data set
- some additional metadata e.g. etags, timestamp for the individual data
nodes.
- a change indicator in the content defining yang module itself 

  - This section talks about YANG instance data but it likely should
    talk about YANG instance data sets.
BALAZS: I think both are acceptable terms here. Naturally if the data
changes 
the data set containing it also changes.

* 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.

(The first 3 users of this format all want to use this for early delivery of

server capabilities. It is for now the dominant use case for which the  
2119 SHOULD is important.). 

* 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.

* YANG Model

  - How is the inline-content-schema feature used? Which component
    does indicate that inline content-schema is supported? Do all
    implementations have to support simplified-inline? If
    inline-schema is used, how do I find out which schema formats are
    supported? The more formats there are, the more interoperability
    issues will arise.
Balazs:
- case inline { is decorated with "if-feature inline-content-schema"
- feature support is generally indicated as part of the ietf-yang-library
- simplified-inline is mandatory to support. It is relatively simple, so
IMHO not a problem
- what do you mean with schema-formats? The yang schema is not actually
included anywhere.
If the "inline" case is used, instance data corresponding to the 
inline-modules is included, not the schema. 
anydata inline-schema {
             description
               "Instance data corresponding to the YANG modules
                specified in the inline-module nodes defining the set
                of content defining YANG modules for this
                instance-data-set."

* Security Considerations

  - "is designed as a wrapper" - what does this tell me? I suggest to
    rewrite the first paragraph and to remove this phrase or to explain
    what it means.

  - Why is the header part not security sensitive? Almost all data is
    security sensitive in certain situations.
BALAZS: IMHO it is a valid and meaningful statement to differentiate 
between security sensitive data like passwords and non-sensitive data 
like a revision date. RFC8341 states:
"One of the most important aspects of the data model documentation,
and one of the biggest concerns during deployment, is the
identification of security-sensitive content." 
So the differentiation between sensitive and non-sensitive information is
important.
In your opinion which part of the header data is sensitive?

  - I would prefer if the text would not use the phrase "result of a
    <get> operation". As stated before, I like to see things written
    in protocol neutral forms.
BALAZS: OK, I will change to the generic "read" operation as used by 
RFC8341 (although for me <get> is much more clear).

  - Since instance data files may require protection, is there any
    recommendation how to do this, e.g., by wrapping everything into a
    cryptographic message syntax or so? It would be important in
    certain use cases to be able to verify that instance data is
    authentic (i.e., it is signed by the original source). In other
    cases, it may be crucial to protect the instance data itself
    against occasional readers.
BALAZS: File security is an important but really big topic and
 I was instructed by multiple people to avoid a half baked discussion on the
topic.

  - It may be useful to explain that data in instance data sets may
    have been filtered by access control rules like NACM and that data
    in instance data sets itself won't be filtered anymore by access
    control rules like NACM. In other words, if I take snapshots and
    stored them as instance data files, these snapshots may leak
    information that is otherwise protected. Hence it is important
    that NACM rules and file access control rules are consistent.
BALAZS: We do not know if the instance data set was originally 
filtered by NACM or not. We don't know if the users on 
Netconf/Restconf/cli are the same as the users defined in the 
file system., so I fear defining what consistent means would be impossible. 
It is stated that " The same kind of handling should be applied, that would
   be needed for the result of a <get> operation returning the same
   data." IMHO we can't really say more.

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Wed, 12 Feb 2020 09:07:05 +0000

Trimming things down where things are clear, not fixing the quoting
problems...

> BALAZS: Other have expressly asked for a reference to "get" but if you want

Thanks. So also further below...
 
> I updated the description to emphasize this difference.

OK. But then what is a non-content defining YANG module? Or are these
schema-defining YANG modules? I still do not get why we need 'content
defining YANG modules' - we did not need that in other specifications
so far that define schemas. So why do we need new terms here?

> 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.

> Here the usage of the default ATTRIBUTE is defined.

I am still confused about terminology here, an attribute is an XML way
of representing meta data, JSON does this differently. Perhaps some
good examples would clear the confusion.

> data nodes (e.g.  metadata following the principles from rfc7952) it belongs

OK, perhaps my confusion is that it was not clear to me what kind of
metadata is meant here...
 
> However that does not mean much.

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).

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?

>     terms of a technical specification.

So what is the meaning of "will be very similar"?

> Maybe I am not understanding your comment.

Hm, I do not recall what made me write this, so lets ignore this
comment.
 
> to the instance data set, not even a URI is included.

So if I have no case in the content-schema-spec choice, then it is
external or how does this work? Perhaps define external differently?
Another attempt:

External method: Do not include the content-schema, the user needs
to obtain the information through external documents.

I removed "already known" since a tool and human producing an instance
file will in general have no clue what a user of that instance file
already knows.
 
> agreed in Netmod yet. The name was changed from version-label to

Lets use a single term then, lets say "revision labels" if that is the
most recent once. Right now, both terms seem to be used.

> 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.
 
> much use-case and implementation specific.

In this case, I think it helps to spell out that users cannot assume
that instance data always represents consistent snapshots.

> - a change indicator in the content defining yang module itself 

I do not know how I implement such a SHOULD. I admit that I do not
understand RFC 2119 language but a lowercase should would make me feel
better.  The concern here is that it is entirely implementation
specific how I make this information available and hence whether I
have followed the SHOULD or not is rather unclear.

> the data set containing it also changes.

Well, yes, but the text says "instance data set's description
statement", i.e., the change is documented on the set and not on an
individual instance. But yes, this is a minor nit.

> both for offline delivery of design time information and for run-time

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.)
 
> 2119 SHOULD is important.). 

I do not think this specification should define SHOULDs for specific
use cases. See my proposal for a possible PX to capture what I think
is the core idea.

> Actually we met the problem or had to avoid it in all but one of 

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.
 
> - case inline { is decorated with "if-feature inline-content-schema"

OK

> - feature support is generally indicated as part of the ietf-yang-library

OK

> - simplified-inline is mandatory to support. It is relatively simple, so

How do I know whether the feature inline-content-schema is supported
in this case?

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.

>                 of content defining YANG modules for this

My understanding is that the inline-module indicates a variant of the
yang library used and the inline-schema then follows that indicated
yang library variant and provides the schema. Am I entirely wrong
here?
 
> In your opinion which part of the header data is sensitive?

In today's world the idea of 'non-sensitive data' is rather difficult.
The name of an instance-data-set can reveal information, the timestamp
can be sensitive, the description can be sensitive, the combination
can be sensitive. I find the claim that instance data may be sensive
but the header part is not sensitive a very big claim. But since this
section will also be read by SECDIR reviewers, we can see whether they
will raise a point. I certainly would if I were a the assigned SECDIR
reviewer.

>  I was instructed by multiple people to avoid a half baked discussion on the

OK
 
>    data." IMHO we can't really say more.

Yes, I guess what I was trying to say is that a live server may apply
certain access control rules while instance files may not apply the
same rules. In other words, an instance file obtained from a live
server by joe and passed on to lucy may reveal information that lucy
will not be allowed to see on the live server. By passing around
instance files, information may accidentally leak. Yes, we can't solve
this, put we can point this out.

/js

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 13 Feb 2020 13:40:13 +0000

See below as BALAZS2.

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

> A  "content defining YANG module" is an individual YANG module is part 
> of the content-schema. So the difference is a set versus one item.

OK. But then what is a non-content defining YANG module? Or are these
schema-defining YANG modules? I still do not get why we need 'content
defining YANG modules' - we did not need that in other specifications so far
that define schemas. So why do we need new terms here?
BALAZS2: In some paragraphs I reference individual YANG modules that are
part of the content-schema. What would be a better term for the individual
modules?

> 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:

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. 

> Here the usage of the default ATTRIBUTE is defined.

I am still confused about terminology here, an attribute is an XML way of
representing meta data, JSON does this differently. Perhaps some good
examples would clear the confusion.
BALAZS2: The Restconf RFC uses the exact term " the default attribute". If
it is acceptable there IMHO I should be able to reuse it here. It is not my
terminology it's from RFC 8040. 

> BALAZS: As this might be meta-data about the individual instance data 
> nodes (e.g.  metadata following the principles from rfc7952) it 
> belongs here.

OK, perhaps my confusion is that it was not clear to me what kind of
metadata is meant here...
BALAZS2:  OK., will try to update, clarify the text.
 
> 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.

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?

So what is the meaning of "will be very similar"?
BALAZS: Similar means same structure, same data types, but there will also
be differences, like the additional metadata and allowing partial data,
ignoring of some constraints that are listed in the chapter. As this is not
a precise term I will use it only in the introduction chapter (principles). 

> Here external means that the content-schema is defined externally to 
> the instance data set, not even a URI is included.

So if I have no case in the content-schema-spec choice, then it is external
or how does this work? Perhaps define external differently?
Another attempt:

External method: Do not include the content-schema, the user needs to obtain
the information through external documents.

I removed "already known" since a tool and human producing an instance file
will in general have no clue what a user of that instance file already
knows.
BALAZS: OK
 
> added as a reference. I added them here (only as an example) as they 
> are highly relevant to specifying module versions even if they are not 

Lets use a single term then, lets say "revision labels" if that is the most
recent once. Right now, both terms seem to be used.
BALAZS: OK

> - 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.
 
> BALAZS: OK< Changed to current. I want to keep the second sentence as 
> it describes the duality between the original documented values and  

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.

> BALAZS: We do not want to specify the how the changes should be 
> described, But we do want to state that this information should be made
available.
> - some additional metadata e.g. etags, timestamp for the individual 
> data nodes.

I do not know how I implement such a SHOULD. I admit that I do not
understand RFC 2119 language but a lowercase should would make me feel
better.  The concern here is that it is entirely implementation specific how
I make this information available and hence whether I have followed the
SHOULD or not is rather unclear.
BALAZS: OK, lowercase should

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.
 
> 2119 SHOULD is important.). 

I do not think this specification should define SHOULDs for specific use
cases. See my proposal for a possible PX to capture what I think is the core
idea.
BALAZS2: OK, SHOULD change to lower case may.

> 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?
> 
> 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.  

OK

OK

> - simplified-inline is mandatory to support. It is relatively simple, 
> so IMHO not a problem

How do I know whether the feature inline-content-schema is supported in this
case?
BALAZS2: IMHO your question is out of scope for this draft. 
Just like for any feature you can read it on-line from ietf-yang-library. If
the information is needed offline it can be documented in any design time
document. My proposal is to use an instance data file based on
ietf-yang-library using the simplified-inline schema declaration method.

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>

> - what do you mean with schema-formats? The yang schema is not 
> actually included anywhere.

My understanding is that the inline-module indicates a variant of the yang
library used and the inline-schema then follows that indicated yang library
variant and provides the schema. Am I entirely wrong here?
BALAZS2: You are correct. Some extras:
Inline-module could indicate some other module instead of the yang-library.
I was asked to do this earlier by Rob Wilton. 
There can be multiple inline-modules so we can use yang-lib with extensions
like  a module adding revision-labels

> Netconf/Restconf/cli are the same as the users defined in the file 
> system., so I fear defining what consistent means would be impossible.

Yes, I guess what I was trying to say is that a live server may apply
certain access control rules while instance files may not apply the same
rules. In other words, an instance file obtained from a live server by joe
and passed on to lucy may reveal information that lucy will not be allowed
to see on the live server. By passing around instance files, information may
accidentally leak. Yes, we can't solve this, put we can point this out.

BALAZS2: I agree fully, but file security is a really big topic, so
highlighting some areas will not help people. I  added:
Care should be taken, when copying the original files or providing 
        file access for additional users, not to reveal information
unintentionally. 

/js

---

From: Schönwälder, Jürgen <[email-masked]>
Date: Wed, 19 Feb 2020 10:16:55 +0000

> while just looking up a get-reply is easy. It is not precise, but IMHO

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).
 
> 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.
 
> 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...
  
> 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.
 
> 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.

> The text is specific to some use cases:  In practice relevant to 90% of the

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.
  
>     <module> ietf-netconf-monitoring@2020-01-14</module>

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).
 
> like  a module adding revision-labels

Yes, I agree, this makes things even more open ended. My expectations
for finding accurate interoperable schema information in instance
formats likely needs to be low.

/js