Subject: [netmod] Fwd: New Version Notification for draft-lengyel-netmod-yang-instance-data-01.txt

From: Balazs Lengyel <[email-masked]>
Date: Wed, 13 Jun 2018 16:03:35 +0200

Hello,

I submitted a new version of the yang-instance-data draft updated
with comments from the last IETF and others. I would like to get
this adopted as a workgroup item. Please review it and if you like
it please indicate that you support it as a workgroup item.

Changes:

o  Redefined using yang-data-ext

o  Moved meta data into ordinary leafs/leaf-lists

o  Corrections, clarifications

regards Balazs

-------- Forwarded Message --------

Subject:

New Version Notification for
draft-lengyel-netmod-yang-instance-data-01.txt

Date:

Wed, 13 Jun 2018 06:47:16 -0700

From:

[email-masked]

To:

Benoit Claise <[email-masked]>, Balazs Lengyel
<[email-masked]>

A new version of I-D, draft-lengyel-netmod-yang-instance-data-01.txt
has been successfully submitted by Balazs Lengyel and posted to the
IETF repository.

Name: draft-lengyel-netmod-yang-instance-data
Revision: 01
Title: YANG Instance Data Files and their use for Documenting Server Capabilities
Document date: 2018-06-13
Group: Individual Submission
Pages: 10
URL: https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-01.txt
Status: https://datatracker.ietf.org/doc/draft-lengyel-netmod-yang-instance-data/
Htmlized: https://tools.ietf.org/html/draft-lengyel-netmod-yang-instance-data-01
Htmlized: https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data
Diff: https://www.ietf.org/rfcdiff?url2=draft-lengyel-netmod-yang-instance-data-01

Abstract:
This document specifies a standard file format for YANG instance
data, that is data that could be stored in a datastore and whose
syntax and semantics is defined by YANG models. Instance data files
can be used to provide information that is defined in design time.
There is a need to document Server capabilities (which are often
specified in design time), which should be done using instance data
files.

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat

--
Balazs Lengyel Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909 email: [email-masked]

---

From: Balazs Lengyel <[email-masked]>
Date: Wed, 13 Jun 2018 16:06:59 +0200

Hello,

Changes:

regards Balazs

-------- Forwarded Message --------

Subject:

Date:

From:

[email-masked]

To:

Abstract:

The IETF Secretariat

---

From: Robert Wilton <[email-masked]>
Date: Wed, 13 Jun 2018 15:40:31 +0100

Hi,

I would support this draft (if/when a call for adoption is made).

A few comments from a quick review :

1) I think that it would be useful to allow a file to contain multiple 
"instance data sets".  I could easily imagine that multiple different 
blocks of instance data may need to be provided and allowing these to be 
carried within a single file seems helpful.

2) I wonder whether these instance-data blocks could be used to hold 
examples in drafts/RFCs.  It would be nice if the examples could be 
automatically extracted and validated.  Possibly this draft could help 
with this, although I appreciate it is not its main focus.

3) Possibly a comment should be made about whitespace, although I think 
that it is fairly obvious how whitespace would be handled, i.e. as 
defined by the encoding.

4) "YANG instance data files SHOULD be used to provide design time 
information about server capabilities." sounds quite strong. I think 
that this should either be a MAY, or the sentence should be predicated.  
E.g . "If the server provides design time information about server 
capabilities then YANG instance data files SHOULD be used to allow them 
to be easily read and consumed by clients"

5) I'm wondering whether there needs to be some sort of identifier about 
what type data is held.  E.g. does it represent data that can be 
consumed as part of one of the configuration datastores, or does it 
represent the equivalent of operational state, or is it data for an RPC, 
etc.

6) If this data is to be stored in a file, should it state that it must 
be stored as UTF-8 character encoding?

7) It might want to include a semantic version number for an 
instance-data-set, depending on whether the YANG versioning discussions 
ends up.

Thanks,
Rob

On 13/06/2018 15:06, Balazs Lengyel wrote:
>
> Hello,
>
> I submitted a new version of the yang-instance-data draft updated with 
> comments from the last IETF and others. I would like to get this 
> adopted as a workgroup item. Please review it and if you like it 
> please indicate that you support it as a workgroup item.
>
> Changes:
> Subject: 	New Version Notification for 
> Date: 	Wed, 13 Jun 2018 06:47:16 -0700
> From: 	[email-masked]
> To: 	Benoit Claise <[email-masked]>, Balazs Lengyel 
> URL:https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-01.txt
> Status:https://datatracker.ietf.org/doc/draft-lengyel-netmod-yang-instance-data/
> Htmlized:https://tools.ietf.org/html/draft-lengyel-netmod-yang-instance-data-01
> Htmlized:https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data
> Diff:https://www.ietf.org/rfcdiff?url2=draft-lengyel-netmod-yang-instance-data-01
>
> Abstract:
> Mobile: +36-70-330-7909              email:[email-masked]  
>
>
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 13 Jun 2018 17:26:39 +0200

On Wed, Jun 13, 2018 at 03:40:31PM +0100, Robert Wilton wrote:
> what type data is held.  E.g. does it represent data that can be consumed as
> part of one of the configuration datastores, or does it represent the
> equivalent of operational state, or is it data for an RPC, etc.
> 

Yes. I think I requested this before. There should be a way to indicate
which datastore instance-data belongs to.

I also do not understand why we have instance-data-set if the set is
limited to exactly one instance-data element. Perhaps room to find a
better name for the outer container or the anyxml (perhaps change
instance-data-set to instance-data and instance-data to simply data).
Or alternatively allow multiple instance-data portions but then meta
data would need to be associated with instance-data and not
instance-data-set, so we would actually need another layer.

Also, given that this is supposed to be serialized in XML (or JSON I
assume), would it make sense to include an XML preamble in the
examples, i.e.,

<?xml version="1.0" encoding="UTF-8"?>
<instance-data xmlns=...>
  <name>...</name>
  <datastore>ds:operational</datastore>
  <data>
    <yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
    </yang-library>
  </data>
</instance-data>

/js

-- 
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: Ladislav Lhotka <[email-masked]>
Date: Fri, 15 Jun 2018 09:41:49 +0200

Hi,

I support the adoption of this I-D as a workgroup item and my plan is to
implement it.

However, my suggestion is to avoid the use of yang-data-ext. It is
absolutely useless in this case and only complicates things that are
otherwise pretty trivial.

Lada

Balazs Lengyel <[email-masked]> writes:

> Hello, 
>
> I submitted a new version of the yang-instance-data draft updated with comments from the last
> IETF and others. I would like to get this adopted as a workgroup item. Please review it and if you
> like it please indicate that you support it as a workgroup item.
>
> Changes:
>  Subject:   New Version Notification for draft-lengyel-netmod-yang-instance-data-01.txt  

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Alexander Clemm <[email-masked]>
Date: Tue, 19 Jun 2018 00:38:30 +0000

Hi Balazs,
I think the problem that this addresses is valid and having an interoperable solution for this makes sense.  (The server capabilities is still underspecified, but is straightforward to add.)  So, I will be happy to support this.
--- Alex

From: netmod [mailto:[email-masked]] On Behalf Of Balazs Lengyel
Sent: Wednesday, June 13, 2018 7:07 AM
To: [email-masked]
Subject: [netmod] Fwd: New Version Notification for draft-lengyel-netmod-yang-instance-data-01.txt

Hello,

I submitted a new version of the yang-instance-data draft updated with comments from the last IETF and others. I would like to get this adopted as a workgroup item. Please review it and if you like it please indicate that you support it as a workgroup item.

Changes:

regards Balazs

-------- Forwarded Message --------
Subject:

New Version Notification for draft-lengyel-netmod-yang-instance-data-01.txt

Date:

From:

[email-masked]<mailto:[email-masked]>

To:

Benoit Claise <[email-masked]><mailto:[email-masked]>, Balazs Lengyel <[email-masked]><mailto:[email-masked]>

IETF repository.

Revision:     01

Pages:        10

Abstract:

   files.

The IETF Secretariat

--

Senior Specialist

Mobile: +36-70-330-7909              email: [email-masked]<mailto:[email-masked]>

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 19 Jun 2018 17:10:49 +0200 (CEST)

Hi,

I think this useful work, and I support it.  However, I have some
comments on the current draft.  My main concern is that it mixes the
very useful specification of instance data with requirements on the
server.  Specifically, I think section 4 should be re-written to be an
example of what can be done.

/martin

---

From: Joe Clarke <[email-masked]>
Date: Tue, 19 Jun 2018 18:04:20 -0400

As I stated at the mic at 101, I support this work (and would support
its WG adoption).  In particular, the YANG Catalog can make use of
instance-data in how we capture a server's capabilities to describe what
modules a server (at a specific software revision) implements.

To that end, we would want to augment instance-data-set in order to add
our custom metadata (e.g., the platform name, version of code, etc.).
The state of the yang-data-ext draft is not clear, and I hope that can
be resolved such that we can augment yang-data.

Joe

On 6/13/18 10:03, Balazs Lengyel wrote:
> comments from the last IETF and others. I would like to get this adopted
> as a workgroup item. Please review it and if you like it please indicate
> that you support it as a workgroup item.
> 
> Changes:

---

From: "Einar Nilsen-Nygaard (einarnn)" <[email-masked]>
Date: Mon, 25 Jun 2018 13:32:45 +0000

Balazs,

I support adopting this draft as a workgroup item.

Others have mentioned a few items to clarify/modify. I think there are a few that jump out at me:

  *   What Martin said about how to evolve section 4.
  *   The augmentation requirements mentioned by Joe, i.e. making sure they are enabled (or at least not prevented!).
  *   Encoding issue mentioned by Rob.
  *   Datastore issue mentioned by Juergen (should be optionally specified).
  *   Server capabilities as mentioned by Alex; specifically, it’s not clear to me yet how the correct versions of the models used inside instance data are defined.

It would perhaps be interesting to talk about containing multiple instances of an instance-data-set, but it’s not clear to me that that would add much value.

Cheers,

Einar

On 13 Jun 2018, at 15:06, Balazs Lengyel <[email-masked]<mailto:[email-masked]>> wrote:

Hello,

Changes:

regards Balazs

-------- Forwarded Message --------
Subject:        New Version Notification for draft-lengyel-netmod-yang-instance-data-01.txt
Date:   Wed, 13 Jun 2018 06:47:16 -0700
From:   [email-masked]<mailto:[email-masked]>
To:     Benoit Claise <[email-masked]><mailto:[email-masked]>, Balazs Lengyel <[email-masked]><mailto:[email-masked]>

Abstract:

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org<http://tools.ietf.org>.

The IETF Secretariat

_______________________________________________
netmod mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netmod

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 13:58:44 +0200

Thanks for the comments and support. See
answers below.

Balazs

On 6/13/2018 4:40 PM, Robert Wilton
wrote:

Hi,

I would support this draft (if/when a call for adoption is
made).

1) I think that it would be useful to allow a file to contain
multiple "instance data sets".  I could easily imagine that
multiple different blocks of instance data may need to be
provided and allowing these to be carried within a single file
seems helpful.

BALAZS: We allow multiple YANG modules in a
file, but I have never seen it used. Actually my model/tool
designers asked me to prohibit multiple YANG modules (YAMs) in one
file at least within Ericsson. So if the group decides so it can
be allowed, however I think it is not a good idea.

2) I wonder whether these instance-data blocks could be used to
hold examples in drafts/RFCs.  It would be nice if the examples
could be automatically extracted and validated.  Possibly this
draft could help with this, although I appreciate it is not its
main focus.

BALAZS: It could be easily added. All we need
is a pair of tags like <CODE BEGINS> we could call it
<INSTANCE DATA BEGINS> <INSTANCE DATA ENDS>

After that we need to create the tools to extract and validate the
instance data.

3) Possibly a comment should be made about whitespace, although
I think that it is fairly obvious how whitespace would be
handled, i.e. as defined by the encoding.

BALAZS: OK. How about:

Leading and trailing whitespace before and after the actual value
MUST NOT be present for data based on types string or binary, but
MAY be present for data based on integer types, decimal64,
boolean,  enumeration, bits, identityref, instance-identifier. For
leafrefs leading
or trailing whitespace MAY or MUST NOT be present based
on the referenced data type.  For data based on a union type
leading or trailing whitespace MUST NOT be present if it is not
allowed for any of the member types.

4) "YANG instance data files SHOULD be used to provide design
time information about server capabilities." sounds quite
strong.  I think that this should either be a MAY, or the
sentence should be predicated.  E.g . "If the server provides
design time information about server capabilities then YANG
instance data files SHOULD be used to allow them to be easily
read and consumed by clients"

BALAZS: OK.  I like your text.

5) I'm wondering whether there needs to be some sort of identifier
about what type data is held.  E.g. does it represent data that
can be consumed as part of one of the configuration datastores, or
does it represent the equivalent of operational state, or is it
data for an RPC, etc.

BALAZS: For config=false data that's trivial.

For config=true data I don't see a use-case for providing
operational state data.  IMHO  If we just say that config=true
data can be loaded into the running/candidate datastore that is
enough.  We had a similar debate with Jurgen (?) but I still do
not see the use case. Maybe if there will be dynamic datastores it
would be more meaningful. If you see a use-case that needs this
please describe it.

6) If
this data is to be stored in a file, should it state that it must
be stored as UTF-8 character encoding?

BALAZS: Good idea. Maybe a more general
statement like:

Instance data MUST follow the XML and JSON encoding rules defined
in RFC7950 and 7951. Data MUST be present in canonical form or
where that is not defined in lexical representation.

It is more then just UTF-8. All stuff about encoding the different
statements and types also applies.

7) It might want to include a semantic version number for an
instance-data-set, depending on whether the YANG versioning
discussions ends up.

BALAZS: Yes I would like to. However I am not
exactly clear on what does backwards compatibility mean for
instance data.

Data MAY NOT be removed or changed only added.  ???

Who would use the semver numbers ???

Thanks,

Rob

On 13/06/2018 15:06, Balazs Lengyel
wrote:

Hello,

I submitted a new version of the yang-instance-data draft
updated with comments from the last IETF and others. I would
like to get this adopted as a workgroup item. Please review it
and if you like it please indicate that you support it as a
workgroup item.

Changes:

regards Balazs

-------- Forwarded Message --------

Subject:

Date:

From:

[email-masked]

To:

Benoit Claise <[email-masked]>,
Balazs Lengyel <[email-masked]>

Abstract:

The IETF Secretariat

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 14:11:56 +0200

On Tue, Jun 26, 2018 at 01:58:44PM +0200, Balazs Lengyel wrote:
>    Thanks for the comments and support. See answers below.
>    Balazs
> 
>    On 6/13/2018 4:40 PM, Robert Wilton wrote:
> 
>      Hi,
> 
>    BALAZS: We allow multiple YANG modules in a file, but I have never seen it
>    used. Actually my model/tool designers asked me to prohibit multiple YANG
>    modules (YAMs) in one file at least within Ericsson. So if the group
>    decides so it can be allowed, however I think it is not a good idea.

What exactly is "multiple YANG modules in a file"? I am confused and
you may be talking past each other.

>    BALAZS: It could be easily added. All we need is a pair of tags like <CODE
>    BEGINS> we could call it <INSTANCE DATA BEGINS> <INSTANCE DATA ENDS>

Why is instance data node code? Why do we need new tags? The tags are
there to extract 'stuff' - what 'stuff' is should be clear from
'stuff'. (RFC 7950 uses CODE BEGINS for yang.abnf for example.)

>    Leading and trailing whitespace before and after the actual value MUST NOT
>    be present for data based on types string or binary, but MAY be present
>    for data based on integer types, decimal64, boolean,  enumeration, bits,
>    identityref, instance-identifier. For leafrefs leading or trailing
>    whitespace MAY or MUST NOT be present based on the referenced data type.
>    For data based on a union type leading or trailing whitespace MUST NOT be
>    present if it is not allowed for any of the member types.

Why do we need new rules? Should the artwork wrapping solution not be good
enough?

>    For config=true data I don't see a use-case for providing operational
>    state data.  IMHO  If we just say that config=true data can be loaded into
>    the running/candidate datastore that is enough.  We had a similar debate
>    with Jurgen (?) but I still do not see the use case. Maybe if there will
>    be dynamic datastores it would be more meaningful. If you see a use-case
>    that needs this please describe it.

Trivial use case is an example that shows how content of <running> and
<operational> can differ. I see use cases where you snapshot the
status of <operational> and <running> for post mortem analysis. It is
easy to come up with use cases. We have datastores, so we should be
clear to which datastore instance data relates.

>    BALAZS: Good idea. Maybe a more general statement like:
>    Instance data MUST follow the XML and JSON encoding rules defined in
>    RFC7950 and 7951. Data MUST be present in canonical form or where that is
>    not defined in lexical representation.

So we do not need all the rules you mentioned above concerning white space
etc.

>    BALAZS: Yes I would like to. However I am not exactly clear on what does
>    backwards compatibility mean for instance data.

What does the version number mean? Every change of instance data in an
instacne-data-set leads to a new version number? What is a bug fix in
this sense? What is a non-backwards compatible change of instance data?
I am left a bit puzzled.

/js

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 14:37:21 +0100

> you may be talking past each other.
An example could be wanting to provide a single file that holds the 
capabilities for all different linecard types for a particular type of 
device, rather than providing them as a set of files.

Of course, this could also be achieved using a meta YANG module (e.g. 
the top level module could have a list of linecard types, which each 
linecard type contains the capabilities for that linecard).  Whether 
this make sense probably depends on the underlying YANG modules and how 
they are constructed.

Of just using separate files, in which case the meta information can 
just be managed into the file name, and the file can be provided as a zip.

> Why do we need new rules? Should the artwork wrapping solution not be good
If the draft has text about it following the encoding (e.g. as proposed 
below, then this may not be required at all), although it be useful to 
explicitly highlight that whitespace is also coded by the encoding.  It 
seems like something that could possibly be overlooked otherwise.

> So we do not need all the rules you mentioned above concerning white space
Agreed, although I still think that explicitly mentioning whitespace 
might be helpful.  I'm not sure that I care too strongly on this point.

E.g.

    Instance data MUST follow the XML and JSON encoding rules defined in
    RFC7950 and 7951.  Data MUST be present in canonical form or where that is
    not defined in lexical representation.  Whitespace must also be handled as
    defined by the encoding rules.

> this sense? What is a non-backwards compatible change of instance data?
Probably I don't mean semantic version.  But often files have 
versioning, or revision, information associated with them.  This can be 
muxed into the file name/path, but it also seems like potentially useful 
metadata, and being able to handle this generically in a consistent way 
might be beneficial.

As an example, perhaps the capability information related to S/W release 
1.2.4, etc.

Thanks,
Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 15:46:19 +0200

On 6/13/2018 5:26 PM, Juergen
Schoenwaelder wrote:

BALAZS:

I
am not against this proposal, I just don't see the use case
for it.

At this point I only see 2 use cases:

Documentation of
config=false data. For this the data store s always operational.

Initial
configuration of config=true data. For this the datastore
would be one of candidate or running. It is often not
possible to know which.  Anyway all we want to sy, that this
is data that can be(should be)  loaded into the running
directly or via candidate.

I
do not see the use case for defining config=true
operational-state data?

Who would use it?

In which case would you handle data differently depending on the
the datastore for config=true data?

Maybe if there will be dynamic datastores it
will be more meaningful.  Could you please describe the use case
you are thinking about!

BALAZS: The anydata statement could be called
data instead of instance-data. I used instance-data because its
more specific, and I like that, but I can change it.

I like to keep the file and the data-set separate. In my mind
these are two different concepts just as a YANG module and a YANG
file are separate. I use the term set because internally it can
contain a multiple related pieces of data.

BALAZS: OK, XML preamble will be added.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 15:52:32 +0200

On Tue, Jun 26, 2018 at 02:37:21PM +0100, Robert Wilton wrote:
> Of course, this could also be achieved using a meta YANG module (e.g. the
> top level module could have a list of linecard types, which each linecard
> type contains the capabilities for that linecard).  Whether this make sense
> probably depends on the underlying YANG modules and how they are
> constructed.
> 
> Of just using separate files, in which case the meta information can just be
> managed into the file name, and the file can be provided as a zip.
>

I am left puzzled. There is instance data (in a datastore) and you
serialize (perhaps filtered) the instance data into a file. Instance
data in general has data that conforms to multiple YANG modules, in
particular also due to augments. I think we need to solve the general
problem, not an isolated linecard problem.

>    defined by the encoding rules.

I thought the 2nd and 3rd sentence would be not needed but checking
RFC 7951 I see no mentioning that values must be in canonical format.
I guess this is an omission of RFC 7951 - perhaps I should open an
errata. RFC 7950 says this clearly in section 9.1:

   When a server sends XML-encoded data, it MUST use the canonical form
   defined in this section.

Looks like an omission in RFC 7951.

> Probably I don't mean semantic version.  But often files have versioning, or
> revision, information associated with them.  This can be muxed into the file
> name/path, but it also seems like potentially useful metadata, and being
> able to handle this generically in a consistent way might be beneficial.
> 

We need to separate a version number of the instance data from the a
version number (or version context) that may be needed in order to
understand what a YANG (module, path) tuple means if we move to a
different YANG versioning scheme. The later I agree would be needed,
the former I am less sure of - at least if we talk semantic version
numbers.

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 15:58:27 +0200

Hello Lada,

I don't insist on using yang-data-ext, but I like it.  Isn't this
the exact use case for it: defining yang structured data that will
never be loaded into a datastore. In this case the structure of
the instance-data-set fits.

If I would remove the
yd:yang-data instance-data-format  statement it
would not affect the actual file content. It just serves as  an
indication that this is not  a datastore definition.

regards Balazs

On 6/15/2018 9:41 AM, Ladislav Lhotka
wrote:

Hi,

Lada

Hello,

Changes:

regards Balazs

-------- Forwarded Message --------

Abstract:

The IETF Secretariat

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 16:00:12 +0200

Any hints what you would like to see in the server capabilities
definition?

Balazs

On 6/19/2018 2:38 AM, Alexander Clemm
wrote:

Hi
Balazs,

I
think the problem that this addresses is valid and having an
interoperable solution for this makes sense.  (The server
capabilities is still underspecified, but is straightforward
to add.)  So, I will be happy to support this.

---
Alex

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 16:05:16 +0200

Hello Martin,

IMHO it would be good to recommend as a general practice that
YANG servers SHOULD document their capabilities using instance
data. Even though "the
set of server capabilities to be documented will be defined by
other standards and specifications ..."   it
would still be good to make the general recommendation to do this.

If the group thinks this general recommnedation is a bad idea, I
think this chapter should be merged with 2.2 Use case 1.

On 6/19/2018 5:10 PM, Martin Bjorklund
wrote:

Hi,

/martin

Hello,

Changes:

regards Balazs

-------- Forwarded Message --------

Abstract:

The IETF Secretariat

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 15:07:16 +0100

> problem, not an isolated linecard problem.
OK, so I wasn't assuming that instance data necessarily corresponds to 
instance data coming from a datastore (or an entire datastore). I was 
thinking that it can be any data that has a well defined YANG schema 
associated with it.  E.g. perhaps it could use to represent the YANG 
data sent or received in a YANG encoded RPC.

> the former I am less sure of - at least if we talk semantic version
Yes, I agree with the need for the latter, that may entail listing the 
versions of the modules in the meta-data.

But what I was actually referring to was the former, and thinking more 
of it is just being a string field in the meta-data with a well defined 
name, that is optional to populate.  Actually, I see the current 
definition already has a revision with a date and description string.  
This is roughly along the lines of what I was thinking of for versioning 
(although I'm not sure why this should be a list rather than just a pair 
of leaves).

Thanks,
Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 16:23:59 +0200

Hello Einar,

I answered  most comments in other mails. But see one below!

regards Balazs

On 6/25/2018 3:32 PM, Einar
Nilsen-Nygaard (einarnn) wrote:

Server capabilities as mentioned by Alex;
specifically, it’s not clear to me yet how the correct versions
of the models used inside instance data are defined.

BALAZS:

I do not want to make a strong connection between the
instance-data-set and the individual model's revision/version.
Obviously the same instance-data-set can be used with many module
versions even if those versions are incompatible.

Without semver in the YANG Modules (YAMs) I see no formal solution
at all. Connecting the instance-data-set to a strict revision-date
of the YAM would be extremely tedious and require continuous
updates.

IMHO the problem is similar to the import-by-version in the
module-update/versioning draft.  Maybe I can reuse that solution.
E.g. Include a set of used YAMs and allowed semantic-versions as
metadata under container
instance-data-set.

My proposal is to list this as an open issue and see what the
versioning draft comes up with. Still I fear this might end up as a
warning and a statement that it must be solved by other means.

regards Balazs

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 16:55:33 +0200

On 6/26/2018 2:11 PM, Juergen
Schoenwaelder wrote:

Hi,

BALAZS:
https://tools.ietf.org/html/rfc7950#section-5.2 states:

YANG modules and submodules are typically stored in files, one
"module" or "submodule" statement per file.

To me this means it is allowed to have
multiple module statements in a file, multiple YANG modules in a
file. AM I wrong?

BALAZS: "stuff" in this case would be an
instance-data-set formatted according to this draft and used as an
example in some other draft/RFC. As I understand the use case:
this could be extracted by some tool and validated against this
draft for the format of the instance-data-set and validated
against the YANG modules used by the instance data inside. See
attachment as an example. However the use case came from Rob, so
he might know better.

BALAZS: OK. How about:

BALAZS: Please explain. In the normal case an instance-data-set is a
standalone instance-data-file that is not part of any artwork. Where
can I see the artwork wrapping solution?

I just wanted to be liberal, to make writing and reading easy, so I
would allow both

<myleaf>23.3</myleaf>

and

<myleaf>

23.3

</myleaf>

unless the data is of type string in which case the whitespace has
an actual meaning.

BALAZS: Maybe, please help here. If I have a leaf defined as an
integer, is the following XML correct as a YANG based XML
representation?

<myleaf>

23.3

</myleaf>

There is whitespace before and after the number. I did not find in
RFC7950 whether this is allowed.

BALAZS: Ask Rob, it was his idea :-)

But seriously we would first need to define what backwards
compatibility means in this case and who would use the version
number. I think its worth thinking about, but at this point I don't
have a good use case or solution.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 16:58:53 +0200

On Tue, Jun 26, 2018 at 04:05:16PM +0200, Balazs Lengyel wrote:
>    Hello Martin,
> 
>    IMHO it would be good to recommend as a general practice that YANG servers
>    SHOULD document their capabilities using instance data. Even though "the
>    set of server capabilities to be documented will be defined by other
>    standards and specifications ..."   it would still be good to make the
>    general recommendation to do this.
> 
>    If the group thinks this general recommnedation is a bad idea, I think
>    this chapter should be merged with 2.2 Use case 1.
>

Why would server capabilities not be more state data? Why would a
client have to fetch files (how?) to obtain knowledge about server
capabilities?

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 17:09:56 +0200

On 6/26/2018 3:52 PM, Juergen
Schoenwaelder wrote:

Hi,

BALAZS: The point of this draft is to allow us
to document instance-data in files. The full content of the
datastore may be (will be) broken up into multiple
instance-data-sets to allow different groups to work on each.  One
group might be defining access control rules while the other will
be defining documentation for the implemented modules
(ietf-yang-library). Each will define its own instance-data-set.
The question is: Shall we allow two of these sets to be in one
file?

Naturally you can put anything that follows the models into a
single data-set, but if you decide to use multiple separate sets
IMHO you should put each of these into a separate file (or maybe
allow multiple sets in a single file).

BALAZS: I did not find anything about
leading/trailing whitespace e.g. for an integer in RFC 7950
either. Is it allowed/prohibited?

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 17:20:27 +0200

On 6/26/2018 4:07 PM, Robert Wilton
wrote:

7) It
might want to include a semantic version number for an

instance-data-set, depending on whether the YANG
versioning discussions

ends up.

BALAZS: Yes I would like to. However I am not exactly
clear on what does

What does the version number mean? Every change of instance
data in an

instacne-data-set leads to a new version number? What is a
bug fix in

this sense? What is a non-backwards compatible change of
instance data?

I am left a bit puzzled.

versioning, or

revision, information associated with them.  This can be muxed
into the file

name/path, but it also seems like potentially useful metadata,
and being

able to handle this generically in a consistent way might be
beneficial.

As an example, perhaps the capability information related to
S/W release

1.2.4, etc.

We need to separate a version number of the instance data from
the a

version number (or version context) that may be needed in order
to

understand what a YANG (module, path) tuple means if we move to
a

different YANG versioning scheme. The later I agree would be
needed,

the former I am less sure of - at least if we talk semantic
version

numbers.

Yes, I agree with the need for the latter, that may entail listing
the versions of the modules in the meta-data.

But what I was actually referring to was the former, and thinking
more of it is just being a string field in the meta-data with a
well defined name, that is optional to populate.  Actually, I see
the current definition already has a revision with a date and
description string.  This is roughly along the lines of what I was
thinking of for versioning (although I'm not sure why this should
be a list rather than just a pair of leaves).

Thanks,

Rob

BALAZS:  IMHO if we want to use versioning
(semver) to version the instance-data-set itself we first need to
understand what backwards compatibility means for an instance data
set.

Revision is a list because as you develop your instance-data-set
you may go through multiple revisions. Just as you may have
multiple revision statements in a YANG Module (YAM) the same way
you may need multiple revision list entries in an instance data
set; to keep history.

(And following your advice, that is one very good reason to define
the metadata about the set as normal YANG instead of
yang-meta-data which does not have the concept of meta-data-array)

regards Balazs

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 26 Jun 2018 17:30:15 +0200

On Tue, 2018-06-26 at 15:58 +0200, Balazs Lengyel wrote:
> Hello Lada,
> I don't insist on using yang-data-ext, but I like it.  Isn't this the exact
> use case for it: defining yang structured data that will never be loaded into
> a datastore. In this case the structure of the instance-data-set fits.

On the other hand, if it's never loaded into a datastore, there is no need to
encapsulate the data and break tools that don't support yang-data-ext.

The encapsulation is really needed only if such data is mixed with "real" YANG
data node definitions in the same module - for example, if error-message schemas
are defined along with datastore contents, operations etc. 

> If I would remove the yd:yang-data instance-data-format  statement it would
> not affect the actual file content. It just serves as  an indication that this
> is not  a datastore definition.

A comment in the module should perfecty suffice. Andy argued with machine
readability, but I don't see how it can be useful here.

And, after all, if a server implementor for whatever weird reason decides to
implement this module, what's wrong on doing so?

Lada

> regards Balazs
> 
> On 6/15/2018 9:41 AM, Ladislav Lhotka wrote:
> > Hi,
> > 
> > > comments from the last

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 16:31:17 +0100

On 26/06/2018 16:20, Balazs Lengyel wrote:
>
>
>
> On 6/26/2018 4:07 PM, Robert Wilton wrote:
>> more of it is just being a string field in the meta-data with a well 
>> defined name, that is optional to populate.  Actually, I see the 
>> current definition already has a revision with a date and description 
>> string.  This is roughly along the lines of what I was thinking of 
>> for versioning (although I'm not sure why this should be a list 
>> rather than just a pair of leaves).
>>
>> Thanks,
>> Rob
> BALAZS:  IMHO if we want to use versioning (semver) to version the 
> instance-data-set itself we first need to understand what backwards 
> compatibility means for an instance data set.
So, I'm suggesting versioning, but not semver.  Just a string version 
field.  E.g. for XR I would just put in the XR release number "R4.5.1" 
or similar.

>
> Revision is a list because as you develop your instance-data-set you 
> may go through multiple revisions. Just as you may have multiple 
> revision statements in a YANG Module (YAM) the same way you may need 
> multiple revision list entries in an instance data set; to keep history.
But I don't see that every instance data document wants to necessarily 
publish that history, although of course it could just publish a list 
containing a single (the latest) entry.

Thanks,
Rob

>
> (And following your advice, that is one very good reason to define the 
> metadata about the set as normal YANG instead of yang-meta-data which 
> does not have the concept of meta-data-array)
> regards Balazs
> -- 
> .

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 17:31:27 +0200

Hello Juergen,

Sorry the wording was misleading. I want these capabilities both as 
state data AND as instance-data-files, because
there is a need to know this information before you ever see the real 
network node. How about the following?

"YANG servers SHOULD document server capabilities that are available via Netconf/Restconf (as YANG defined data) also using instance-data-files."

regards Balazs

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 17:34:58 +0200

Hello Lada,

Maybe you are right. It is probably only important in case of mixed 
modules.  However as Rob proposed the usage of yang-data-ext I will put 
it up as an open issue in Montreal. OK?

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 17:37:02 +0200

My plain text email reader fails on the quoting and this is usually
where I drop out of discussions since I can't follow anymore.

On Tue, Jun 26, 2018 at 05:09:56PM +0200, Balazs Lengyel wrote:
> 
>    BALAZS: I did not find anything about leading/trailing whitespace e.g. for
>    an integer in RFC 7950 either. Is it allowed/prohibited?
>

7.5.7.  XML Encoding Rules

   [...]

   Any whitespace between the subelements to the container is
   insignificant, i.e., an implementation MAY insert whitespace
   characters between subelements.

7.6.6.  XML Encoding Rules

   The value of the leaf node is encoded to XML according to the type
   and is sent as character data in the element.

Note that there is no text that arbitrary whitespace may be added by a
writer and removed by a reader. Hence, I believe for values contained
in leafs, extra whitespace is not allowed. However, between containers
and leafs whitespace is insignificant. The simple reason is that for
string values, you can't simply strip leading/trailing whitespace and
in order to treat all leafs the same, you do not strip
leading/trailing whitespace in general.

That said, some parsers may (following Postel's principle) accept
<foo> +1</foo> if the YANG definition of foo says it is an int32 but
writers should generate <foo>1</foo> (the canonical format without
added whitespace). Note that if foo is defined to be a string, then
clearly the white space belongs to the string value.

If we define a file serialization format, then the format should be
the natural canonical serialization format (and if the definition of
the serialization formats is not clear enough, then we have to fix
these definitions by filing errata).

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 26 Jun 2018 17:38:10 +0200

Any opinions on Rob's suggestion about a free-text versioning
string?

I am neutral on this.

regards Balazs

On 6/26/2018 5:31 PM, Robert Wilton
wrote:

On 26/06/2018 16:20, Balazs Lengyel
wrote:

7) It might want to include a semantic version number
for an

instance-data-set, depending on whether the
YANG versioning discussions

ends up.

BALAZS: Yes I would like to. However I am not
exactly clear on what does

Data MAY NOT be removed or changed only added.
???

What does the version number mean? Every change of
instance data in an

instacne-data-set leads to a new version number? What is
a bug fix in

I am left a bit puzzled.

Probably I don't mean semantic version.  But often files
have versioning, or

revision, information associated with them.  This can be
muxed into the file

name/path, but it also seems like potentially useful
metadata, and being

able to handle this generically in a consistent way might
be beneficial.

As an example, perhaps the capability information related
to S/W release

1.2.4, etc.

We need to separate a version number of the instance data
from the a

version number (or version context) that may be needed in
order to

understand what a YANG (module, path) tuple means if we move
to a

numbers.

Yes, I agree with the need for the latter, that may entail
listing the versions of the modules in the meta-data.

But what I was actually referring to was the former, and
thinking more of it is just being a string field in the
meta-data with a well defined name, that is optional to
populate.  Actually, I see the current definition already has
a revision with a date and description string.  This is
roughly along the lines of what I was thinking of for
versioning (although I'm not sure why this should be a list
rather than just a pair of leaves).

Thanks,

Rob

BALAZS:  IMHO if we want to use versioning
(semver) to version the instance-data-set itself we first need
to understand what backwards compatibility means for an
instance data set.

So, I'm suggesting versioning, but not semver.  Just a string
version field.  E.g. for XR I would just put in the XR release
number "R4.5.1" or similar.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 17:41:55 +0200

On Tue, Jun 26, 2018 at 05:38:10PM +0200, Balazs Lengyel wrote:
>    Any opinions on Rob's suggestion about a free-text versioning string?
>    I am neutral on this.
>

It needs to be clear _what_ is versioned. I have seen conflicting
views. I have heard so far:

- the YANG version context once (module, path) is not sufficient anymore
- the instance data version
- a version number refering to a specific software release of a server

/js

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 16:44:16 +0100

Note, adding it to the meta-data YANG definition does not mean that 
everyone has to populate this, it just ensures that it has a consistent 
name and semantics for clients/servers that do want to use it.

Thanks,
Rob

On 26/06/2018 16:38, Balazs Lengyel wrote:
> On 6/26/2018 5:31 PM, Robert Wilton wrote:
>> field.  E.g. for XR I would just put in the XR release number 
>> "R4.5.1" or similar.
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 17:44:30 +0200

On Tue, Jun 26, 2018 at 05:31:27PM +0200, Balazs Lengyel wrote:
> Hello Juergen,
> 
> Sorry the wording was misleading. I want these capabilities both as state
> data AND as instance-data-files, because

I am against this. I think we should standardize the format and not
how the format is used. And it remains unclear why this would be a
SHOULD or how one implements this SHOULD and in which cases one can
ignore it. Again, I do not like to mix specification of mechanisms
with the specification of policies how mechanisms are to be used.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 26 Jun 2018 17:51:15 +0200

> it up as an open issue in Montreal. OK?

Sure, this is only a marginal issue.

Thanks, Lada

> > > > > URL:            https://www.ietf.org/internet-drafts/draft-lengyel-net
> > > > > mod-
> > > > > yang-instance-data-01.txt
> > > > > Status:         https://datatracker.ietf.org/doc/draft-lengyel-netmod-
> > > > > yang
> > > > > -instance-data/
> > > > > Htmlized:       https://tools.ietf.org/html/draft-lengyel-netmod-yang-
> > > > > inst
> > > > > ance-data-01
> > > > > Htmlized:       https://datatracker.ietf.org/doc/html/draft-lengyel-ne
> > > > > tmod
> > > > > -yang-instance-data
> > > > > Diff:           https://www.ietf.org/rfcdiff?url2=draft-lengyel-netmod
> > > > > -yan
> > > > > g-instance-data-01
> > > > > 
> > > > > Abstract:

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 16:55:32 +0100

> - the YANG version context once (module, path) is not sufficient anymore
I agree with Juergen, that depending on where YANG versioning goes, that 
a mechanism to provide this information is required (e.g. a list of 
modules + semvers for the schema used in the instance data).  It should 
be optional to publishers whether they populate this information.

> - the instance data version
The draft already has instance-data revisions.  I regard that as a 
mechanism for versioning instance data.  I'm not saying that this is 
necessary the right approach.

> - a version number refering to a specific software release of a server
I see this "version" as file level meta-data information, in the same 
category as name, contact, description, organization meta-data fields 
that the draft currently provides.  Another field that may be 
generically useful is the time/date stamp of when the instance data was 
generated.  Although perhaps the timestamp of the file is sufficient for 
this purpose.

Thanks,
Rob

---

From: Robert Wilton <[email-masked]>
Date: Tue, 26 Jun 2018 16:57:23 +0100

> with the specification of policies how mechanisms are to be used.
+1.

I think that the draft should just give examples of how it may be used, 
probably in an appendix.  Or if we want to standardize capabilities then 
that should be a separate draft that depends on this one.

Thanks,
Rob

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 26 Jun 2018 18:10:39 +0200 (CEST)

> with the specification of policies how mechanisms are to be used.

+1

This is what I tried to say as well in my comments on this document.

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 26 Jun 2018 19:25:10 +0200

On Tue, Jun 26, 2018 at 04:55:32PM +0100, Robert Wilton wrote:
> 
> Another field that may be generically useful is the time/date stamp
> of when the instance data was generated. Although perhaps the
> timestamp of the file is sufficient for this purpose.

I support adding a time/date stamp. (The time/date stamp of the file
is easily lost if you are not extremely careful with preserving file
metadata.)

/js

---

From: Joe Clarke <[email-masked]>
Date: Tue, 26 Jun 2018 15:42:20 -0400

> Any opinions on Rob's suggestion about a free-text versioning string?

Like I mentioned, I would use this for YANG Catalog input, and I would
want MD around yang-library instance data.  That MD would include the
vendor, platform, and version of software.

I'm not asking for all of these to be standardized, though.  I would
just want a way to extend the MD as needed.

Joe

>>>> current definition already has a revision with a date and
>>>> thinking of for versioning (although I'm not sure why this should be
>>>> a list rather than just a pair of leaves).
>>>>
>>>> Thanks,
>>>> Rob

---

From: Balazs Lengyel <[email-masked]>
Date: Wed, 27 Jun 2018 10:09:25 +0200

On 6/26/2018 5:55 PM, Robert Wilton wrote:

- a version number
refering to a specific software release of a server

I see this "version" as file level meta-data information, in the
same category as name, contact, description, organization
meta-data fields that the draft currently provides.  Another field
that may be generically useful is the time/date stamp of when the
instance data was generated.  Although perhaps the timestamp of
the file is sufficient for this purpose.

BALAZS: Any meta-data defined tin the draft (including the
revision-date) is about the instance-data-set. The file is only a
mechanism to store the instance-data-set.

If you meant the file-system level timestamp of the file I think
that's unreliable.

Balazs

---

From: Balazs Lengyel <[email-masked]>
Date: Wed, 27 Jun 2018 10:15:10 +0200

On 6/26/2018 5:44 PM, Juergen Schoenwaelder wrote:

Hello Juergen,

/js

BALAZS: The current draft really says two things:

this is the format for instance data

instance-data SHOULD be used to document server capabilities

IMHO both are important. I fear that if we exclude the second one
from this draft it will never get documented, even though it is an
important statement. Or would you support a 2 page draft stating
that you SHOULD document ietf-yang-library content with
instance-data?

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 27 Jun 2018 11:16:21 +0200

On Wed, Jun 27, 2018 at 10:15:10AM +0200, Balazs Lengyel wrote:
>     1. this is the format for instance data
>     2. instance-data SHOULD be used to document server capabilities
> 
>    IMHO both are important. I fear that if we exclude the second one from
>    this draft it will never get documented, even though it is an important
>    statement. Or would you support a 2 page draft stating that you SHOULD
>    document ietf-yang-library content with instance-data?

I support 1. and I do not support 2.

(And the first thing we need fro 2. is a YANG data model for server
capabilities.)

/js

---

From: Robert Wilton <[email-masked]>
Date: Wed, 27 Jun 2018 10:56:28 +0100

On 27/06/2018 09:09, Balazs Lengyel wrote:
>> generically useful is the time/date stamp of when the instance data 
>> was generated.  Although perhaps the timestamp of the file is 
>> sufficient for this purpose.
I'm still envisaging a single YANG instance data file containing 
multiple instances of YANG data.  In this scenario some of the meta data 
may be at the file level, and some of the meta-data may be at the per 
instance level.  I was suggesting that a time/date stamp of when the 
data was generated would be at the file level rather than at the 
instance level.

Thanks,
Rob