Re: [netmod] Fwd: New Version Notification for draft-ietf-netmod-yang-instance-file-format-01.txt

[Robert Wilton]

Hi Balazs,

I think that every instance data document logically has a YANG schema 
associated with it (i.e. a set of YANG modules, deviations, and enabled 
features).


YANG library defines this schema on a per datastore basis, along with 
other information.


My YANG packages is another attempt to construct these schema in a 
hierarchical way.


Directly embedding the necessary information to facilitate a client 
reading the YANG instance data also makes sense.



Please see inline ...

On 14/02/2019 10:23, Balázs Lengyel wrote:



On 2019. 02. 07. 13:10, Robert Wilton wrote:


Hi Balazs,

Regarding identifying the instance data using a YANG package.

If the YANG packages work is liked by the WG and progresses, then it 
seems plausible that a YANG package could become a better way of 
identifying the set of modules rather than using YANG library for a 
couple of reasons:
 1) It will allow modules to be identified via semantic version 
rather than just revision date.  This will likely be more meaningful 
to readers.


BALAZS: The nice thing about using yang-library is that when the 
semver work augment the library with the module-version it will be 
available for instance-data for free.


RW:

This only works if the reference to the schema includes the semver 
augmentation.  Your current approach of 
"ietf-yang-library@\d{4}-\d{2}-\d{2}\.yang';" doesn't allow this, unless 
the semver work produces a new version of YANG library rather than an 
augmentation.


I have no opposition to YANG library being one of the mechanisms to 
construct the schema, but I think that it should also be possible to 
define the schema inline, or use YANG packages (in future).



 2) It allows for a much more concise definition.  Rather than having 
to try and infer what schema a particular set of YANG modules related 
to from the list of modules, it can instead refer to a single package 
definition and version number.


BALAZS: Using packages would be more, concise however in some cases 
you might not want to declare a package. E.g. we use a modular 
architecture where one design group might be responsible for only one 
YANG module (YAM). They need to deliver some instance-data related to 
that YAM, but they don't want to declare a package that contains just 
one YAM. Also some modules are packaged in so many ways that it is 
easier to define their instance data just for that module. So while 
packages are an interesting idea they will never completely replace 
the module level, hence we need a module level solution too. One 
packages are agreed, I will be happy to expand this specification.


RW:

But if I understand your approach correctly then to handle this case the 
instance data would need to reference a separate instance data file that 
uses YANG library to define the one YANG module that is uses.


If the schema is just a single YANG module then I think that it would be 
better to define that schema inline in the instance data document, and 
avoid the redirection.  Perhaps to keep it simple we restrict the list 
of YANG modules that can be used to define to define the schema inline 
to state that sub-modules cannot be used, and all features are assumed 
to be enabled.  If either of these conditions are not met then an 
external schema definition must be used.



 3) YANG library (certainly RFC7895bis) defines the schema in terms 
of the datastore, so if this version of YANG library is being used 
then it is a bit more confusing as to which datastore is being 
referred to.  I appreciate that there is a datastore leaf in the 
instance data that can help mitigate this.


I also note that the draft currently binds that the only allowed 
inline schema is YANG library, but that seems somewhat overly 
restrictive, and perhaps this could be loosened to a leaf-list of 
inline module@revision definitions?


BALAZS: IMHO ietf-yang-library contains ll the data we need in a well 
defined format (and some we don't always need). So why define a new 
format when we already have one. Also by using YANG library we get for 
free any new data in it e.g.module-version. We also need the info 
about leafs and deviations.


RW:

Because YANG library isn't really the right format, and the goal of YANG 
library isn't to define this instance data file, but actually to define 
the capabilities of a server.


E.g. RFC 7895bis contains the information on how to build multiple 
datastore schema rather than just one.  So, if 7895bis is being used to 
construct a schema, then you also need to identify which datastore in 
YANG library represents the schema associated with the instance data.


I also don't think that you get augmentations from free.  How would a 
client know which augmentations to YANG library are being used unless 
that is defined somewhere?



I also appreciate that you don't want to delay the instance data 
draft for YANG packages, bit I wonder whether the draft can easily 
facilitate using a YANG package definition in future if 

Re: [netmod] Fwd: New Version Notification for draft-ietf-netmod-yang-instance-file-format-01.txt

[Balázs Lengyel]

  
  


On 2019. 02. 07. 13:10, Robert Wilton
  wrote:


  
  Hi Balazs,
  Regarding identifying the instance data using a YANG package.
  If the YANG packages work is liked by the WG and progresses,
then it seems plausible that a YANG package could become a
better way of identifying the set of modules rather than using
YANG library for a couple of reasons:
 1) It will allow modules to be identified via semantic version
rather than just revision date.  This will likely be more
meaningful to readers.
  

BALAZS: The nice thing about using yang-library is that when the
semver work augment the library with the module-version it will be
available for instance-data for free.

    2) It allows for a much more concise definition.  Rather than
having to try and infer what schema a particular set of YANG
modules related to from the list of modules, it can instead
refer to a single package definition and version number.
  

BALAZS: Using packages would be more, concise however in some cases
you might not want to declare a package. E.g. we use a modular
architecture where one design group might be responsible for only
one YANG module (YAM). They need to deliver some instance-data
related to that YAM, but they don't want to declare a package that
contains just one YAM. Also some modules are packaged in so many
ways that it is easier to define their instance data just for that
module. So while packages are an interesting idea they will never
completely replace the module level, hence we need a module level
solution too. One packages are agreed, I will be happy to expand
this specification.

    3) YANG library (certainly RFC7895bis) defines the schema in
terms of the datastore, so if this version of YANG library is
being used then it is a bit more confusing as to which datastore
is being referred to.  I appreciate that there is a datastore
leaf in the instance data that can help mitigate this.
  
  I also note that the draft currently binds that the only
allowed inline schema is YANG library, but that seems somewhat
overly restrictive, and perhaps this could be loosened to a
leaf-list of inline module@revision definitions?
  

BALAZS: IMHO ietf-yang-library contains ll the data we need in a
well defined format (and some we don't always need). So why define a
new format when we already have one. Also by using YANG library we
get for free any new data in it e.g.module-version. We also need the
info about leafs and deviations.

   
  I also appreciate that you don't want to delay the instance
data draft for YANG packages, bit I wonder whether the draft can
easily facilitate using a YANG package definition in future if
required.

BALAZS: As I agree with your comment about choice (see below) that a
package reference can be easily included in that.

  Hence, rather than using a union for the "target pointer", I
wonder whether it wouldn't be better to use a choice statement
instead.
  E.g. the choice statement could be something like this:
  
   choice "schema"
   leaf-list inline {
 type string {
   pattern '\w+@\d{4}-\d{2}-\d{2}\.yang';
 }
   }
   leaf yang-library-ref { type uri } // Points to a
  instance data document YANG library content.
 }
  In future, the package draft could then augment (or update the
revision) with something like this :
     container package-ref {
 leaf "name" { type string; }
 leaf "version" { type yang-semver; }
 leaf-list "url" { type uri; } //
Points to a instance data document containing YANG package
content.
     }

BALAZS: OK, choice maybe a better choice because it is easier
to extend and because it explicitly states the method used. So
how about:
 choice "target-specification"
   leaf inline {
 type string { pattern 'ietf-yang-library@\d{4}-\d{2}-\d{2}\.yang'; }   // I still want to use the library 
   }
   leaf yang-library-ref { type uri } 
 }

Later we can augment this choice with container package-ref.



  Thanks,
Rob

  
  On 06/12/2018 10:15, Balázs Lengyel
wrote:
  
  
Hello,
We uploaded a new version of the instance data draft. We
  tried to address all comments and also to rework the format
  chapter to make it easier to read. We omitted 2 comments:
Rob commented that YANG packages could be used for defining
  the target modules for instance data: I would like to avoid
  that because:

  Packages are 

Re: [netmod] Fwd: New Version Notification for draft-ietf-netmod-yang-instance-file-format-01.txt

[Robert Wilton]

Hi Balazs,

Regarding identifying the instance data using a YANG package.

If the YANG packages work is liked by the WG and progresses, then it 
seems plausible that a YANG package could become a better way of 
identifying the set of modules rather than using YANG library for a 
couple of reasons:
 1) It will allow modules to be identified via semantic version rather 
than just revision date.  This will likely be more meaningful to readers.
 2) It allows for a much more concise definition.  Rather than having 
to try and infer what schema a particular set of YANG modules related to 
from the list of modules, it can instead refer to a single package 
definition and version number.
 3) YANG library (certainly RFC7895bis) defines the schema in terms of 
the datastore, so if this version of YANG library is being used then it 
is a bit more confusing as to which datastore is being referred to.  I 
appreciate that there is a datastore leaf in the instance data that can 
help mitigate this.


I also note that the draft currently binds that the only allowed inline 
schema is YANG library, but that seems somewhat overly restrictive, and 
perhaps this could be loosened to a leaf-list of inline module@revision 
definitions?


I also appreciate that you don't want to delay the instance data draft 
for YANG packages, bit I wonder whether the draft can easily facilitate 
using a YANG package definition in future if required.


Hence, rather than using a union for the "target pointer", I wonder 
whether it wouldn't be better to use a choice statement instead.


E.g. the choice statement could be something like this:

 choice "schema"
   leaf-list inline {
 type string {
   pattern '\w+@\d{4}-\d{2}-\d{2}\.yang';
 }
   }
   leaf yang-library-ref { type uri } // Points to a instance data 
document YANG library content.

 }

In future, the package draft could then augment (or update the revision) 
with something like this :


   container package-ref {
 leaf "name" { type string; }
 leaf "version" { type yang-semver; }
 leaf-list "url" { type uri; }// Points to a instance data document 
containing YANG package content.

   }

Thanks,
Rob

On 06/12/2018 10:15, Balázs Lengyel wrote:


Hello,

We uploaded a new version of the instance data draft. We tried to 
address all comments and also to rework the format chapter to make it 
easier to read. We omitted 2 comments:


Rob commented that YANG packages could be used for defining the target 
modules for instance data: I would like to avoid that because:


  * Packages are not defined for YANG. Currently they are not part of
the versioning solution even though they were discussed and are
generally a good idea.
  * IMHO as deviations/features are set on module level, just
specifying packages would not be enough. If we start using
package+module level deviations/features we may end up with a more
complicated hybrid solution.
  * Module level YANG target definitions as described in the draft are
simple and need no new design

Jürgen stated that it would be better to use the YANG XML/JSON 
encoding as a format instead of referencing the get operation/request. 
I might even agree with him, but for 2 reasons I did not follow his idea:


  * Currently there is no RFC I could reference either for XML or
JSON. AFAIK even RFC7951 does not define how multiple modules
should be encoded side by side.
  * It is not the job of the instance data draft to dictate how to
encode YANG data generally e.g. on the wire.
  * The contents of the get operation/request are well defined

regards Balazs



 Forwarded Message 
Subject: 	New Version Notification for 
draft-ietf-netmod-yang-instance-file-format-01.txt

Date:   Thu, 6 Dec 2018 02:12:12 -0800
From:   internet-dra...@ietf.org
To: 	Benoit Claise , Balazs Lengyel 






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

Name: draft-ietf-netmod-yang-instance-file-format
Revision: 01
Title: YANG Instance Data File Format
Document date: 2018-12-06
Group: netmod
Pages: 21
URL: 
https://www.ietf.org/internet-drafts/draft-ietf-netmod-yang-instance-file-format-01.txt
Status: 
https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-instance-file-format/
Htmlized: 
https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-01
Htmlized: 
https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-instance-file-format
Diff: 
https://www.ietf.org/rfcdiff?url2=draft-ietf-netmod-yang-instance-file-format-01


Abstract:
There is a need to document data defined in YANG models when a live
YANG server is not available. Data is often needed already in design
time or needed by groups that do not have a live running YANG server
available. This document specifies a standard file format for YANG
instance data, which follows the syntax and semantic from existing
YANG models, 

Re: [netmod] Fwd: New Version Notification for draft-ietf-netmod-yang-instance-file-format-01.txt

[Martin Bjorklund]

Juergen Schoenwaelder  wrote:
> On Thu, Dec 06, 2018 at 10:15:30AM +, Balázs Lengyel wrote:
> > 
> >Jürgen stated that it would be better to use the YANG XML/JSON encoding 
> > as
> >a format instead of referencing the get operation/request. I might even
> >agree with him, but for 2 reasons I did not follow his idea:
> > 
> >  * Currently there is no RFC I could reference either for XML or JSON.
> >AFAIK even RFC7951 does not define how multiple modules should be
> >encoded side by side.
> >  * It is not the job of the instance data draft to dictate how to encode
> >YANG data generally e.g. on the wire.
> >  * The contents of the get operation/request are well defined
> >
> 
> The first bullet needs to be taken care of but it is not too difficult
> I think.
> 
> I fail to understand what bullet two is about or why it matters. We
> are talking about the instance file format, no more and no less.
> 
> Yes, the contents of the get operation/request are well defined but
> the definitions are not generically applicable to define instance file
> formats and the dependincy of the instance file format on protocols
> is problematic from a maintenance perspective.

I agree.

I'm not even convinced that the current text is clear and correct:

   The content-data part of the XML format SHALL follow the format
   returned for a NETCONF GET operation.  The  anydata
   node SHALL contain all elements that would be inside the 
   wrapper element of a reply to the  operation.

What exactly does "all elements that would be inside the " mean?
Does it mean that if a server supports 10 modules, all 10 modules
MUST be part of all instance files?  Probably not.


Since the "content-data" is of type "anydata", I think that we don't
need much additional text.  Maybe something like:

   The "content-data" part may contain data from multiple modules, in
   any order.  For any node in "content-data", the path from the data
   model root node down to the node, including any elements
   necessary to uniquely identify the node, is included in the
   response message.



/martin

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] Fwd: New Version Notification for draft-ietf-netmod-yang-instance-file-format-01.txt

[Juergen Schoenwaelder]

On Thu, Dec 06, 2018 at 10:15:30AM +, Balázs Lengyel wrote:
> 
>J�rgen stated that it would be better to use the YANG XML/JSON encoding as
>a format instead of referencing the get operation/request. I might even
>agree with him, but for 2 reasons I did not follow his idea:
> 
>  * Currently there is no RFC I could reference either for XML or JSON.
>AFAIK even RFC7951 does not define how multiple modules should be
>encoded side by side.
>  * It is not the job of the instance data draft to dictate how to encode
>YANG data generally e.g. on the wire.
>  * The contents of the get operation/request are well defined
>

The first bullet needs to be taken care of but it is not too difficult
I think.

I fail to understand what bullet two is about or why it matters. We
are talking about the instance file format, no more and no less.

Yes, the contents of the get operation/request are well defined but
the definitions are not generically applicable to define instance file
formats and the dependincy of the instance file format on protocols
is problematic from a maintenance perspective.

/js

-- 
Juergen Schoenwaelder   Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod