Subject: [Netmod-ver-dt] Semver and Instance data

From: Balázs Lengyel <[email-masked]>
Date: Thu, 7 Feb 2019 09:04:43 +0000

Hello,

Here is a short chapter about semver and instance-data. IMHO we do not 
need any more. See attachment.

regards Balazs

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 7 Feb 2019 10:46:22 +0100

What is a 'target YANG module'? My terminology would be that instance
data (ideally) conforms to a schema that can be obtained from the YANG
library. Or simply create a one-liner saying 'YANG module version
numbers do not apply to instance data'.

/js

On Thu, Feb 07, 2019 at 09:04:43AM +0000, Balázs Lengyel wrote:
> Hello,
> 
> Here is a short chapter about semver and instance-data. IMHO we do not need
> any more. See attachment.
> 
> regards Balazs
> 
> -- 

> Semver and Instance data
> 
> Assigning a semantic version to Instance data sets is not proposed, because 
> semantic versioning depends on the notion of classifying changes as 
> backwards-compatible or non-backwards-compatible. There is no definition for what 
> backwards-compatible means for instance data. The meaning of backwards-compatible 
> depends on the particular dataset. The compatibility ruleset for YANG models can not be reused  
> for instance data for many reasons e.g. instance data sets are allowed to be incomplete.
> 
> Instance data sets use the ietf-yang-library module to specufy the Target YANG 
> Modules. As this module is augmented with the module-version, the target YANG 
> modules' module-version will also be available in instance data sets.
> 
> Instance data sets contain a list of target YANG modules and their revisions/module-versions 
> that were used when constructing the instance data set. The instance data set 
> is guarranteed to be usable against this set of modules/revisions/module-versions.
> Having semantic versioning and understanding the YANG module compatibility between 
> different versions of the target modules will help a user understand whether 
> the instance data set may be used with different versions of the target modules

> _______________________________________________
> Netmod-ver-dt mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod-ver-dt

-- 
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: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 7 Feb 2019 15:56:40 +0100

On Thu, Feb 07, 2019 at 02:45:54PM +0000, Balázs Lengyel wrote:
>    Hello Jurgen,
> 
>    target YANG module is defined
>    in[1]https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-01#section-1
>    :
> 
>  "A YANG module for which the instance data set contains instance data ..."
>

OK. So I will raise a comment there. I do not like 'target'. And I am
not sure that an 'instance data set' is restricted to a single YANG
module. I am also not sure why 'instance data set' is needed. Also the
definition of design time in that document is weird, tying it to the
implementation time is clearly not applicable for non-vendor YANG
modules where design and implementation time can vary widely. I guess
time to start a thread on instance-file-format terminology.

/js

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 7 Feb 2019 14:45:54 +0000

Hello Jurgen,

target YANG module is defined inhttps://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-01#section-1
:

I think your one liner would be just fine for the first paragraph.
Here I tried to explain why is it not applicable. In the long run your shorter version will be good.

However the other 2 paragraphs have different topics:
para 2) semver will be available for target modules
Actually this should also state that instead of the revision date the version MAY be specified.
para 3) semver helps deciding whether the instance data set is usable if a YANG server implements newer versions of the modules.
IMHO these 2 are needed, maybe with a better wording.

regards Balazs

On 2019. 02. 07. 10:46, Juergen
Schoenwaelder wrote:

/js

Hello,

regards Balazs

Semver and Instance data

---

From: Balázs Lengyel <[email-masked]>
Date: Tue, 12 Feb 2019 17:01:23 +0000

Hello Jurgen,

It is explicitly stated that an instance data set MAY include
data for multiple YANG modules.

The instance data draft defines:

Design time: A time during which a YANG model and the implementation
behind it is created. Sometimes in other documents this period is
divided into design and implementation time.

IMHO separating design and implementation phases is not important for the instance data draft.

Do you have some other/better terminology that could be used? Any help appreciated.

regards Balazs

On 2019. 02. 07. 15:56, Juergen
Schoenwaelder wrote:

Hello Jurgen,

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 12 Feb 2019 18:32:17 +0100

On Tue, Feb 12, 2019 at 05:01:23PM +0000, Balázs Lengyel wrote:
>    Hello Jurgen,
> 
>    It is explicitly stated that an instance data set MAY include data for
>    multiple YANG modules.
> 

My proposal is to not define this term at all. Instead clarify the
two/three uses where necessary.

OLD
   Data is often needed already in design
   time or needed by groups that do not have a live running YANG server
   available.

NEW
   Data is often needed already at design or implementation
   time or needed by groups that do not have a live running YANG server
   available.

OLD
   Data is often needed already in design
   time or needed by groups that do not have a live running YANG server
   available.

NEW
   Data is often needed already at design or implementation
   time or needed by groups that do not have a live running YANG server
   available.

OLD
   They are
   usually defined by a vendor in design time, before the product is
   released.

NEW
   They are
   usually defined by a vendor at design time, before the product is
   released.

Note that all usages are explanatory and hence there is no need to
define a term.

/js

---

From: Balázs Lengyel <[email-masked]>
Date: Wed, 13 Feb 2019 11:53:04 +0000

Hello,

Here is a short updated chapter about semver and instance-data. Thanks 
for Jurgen's comments.  See attachment.
(To all native speakers: IMO the content is fine, but maybe the English 
can be improved.)

regards Balazs

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 10:55:40 -0500

> (To all native speakers: IMO the content is fine, but maybe the English

I found it easily readable.

What I found confusing is that the first paragraph doesn't gel with the
second.  YANG instance data may have a version number of the target
module.  YANG instance data itself will not have a version number.  I
think this is what you're trying to say, but I didn't find it clear.

Maybe changing the order of the first two paragraphs will help, and then
make the new second paragraph read like:

While the target YANG module's version may be present as instance
metadata, YANG instance data sets themselves will not have their own
distinct semantic version numbers.  The concept of backwards
compatibility is not defined for instance data.

In the third paragraph, semver as instance metadata will allow one to
know from which version of a module the instance data comes.  It won't
necessarily help them with backward compatibility.  That is specific to
the target modules themselves.  I guess I'm saying this paragraph isn't
needed, IMHO.

Joe

---

From: Balázs Lengyel <[email-masked]>
Date: Wed, 13 Feb 2019 16:06:33 +0000

Hello Joe,

I tried to say 3 things:

Instance data sets do not have a semantic version as
compatibility for instance data is undefined.

Instance data MAY contain the module-version of target YANG
modules (one of revision-date or module-version MUST be
specified).

Versioning of a target YANG modules makes it easier to decide
if the instance data set may be used with newer versions of the
target modules.

IMHO all 3 statements are needed. This is my preferred order,
but  2,3,1 would also be OK. IMHO 2 and 3 are related.

Is this better?

regards Balazs

On 2019. 02. 13. 16:55, Joe Clarke
wrote:

Hello,

Joe

regards Balazs

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 11:17:41 -0500

On 2/13/19 11:06, Balázs Lengyel wrote:
> Hello Joe,
> 
> I tried to say 3 things:
> 
>  1. Instance data sets do not have a semantic version as compatibility
>     for instance data is undefined.
>  2. Instance data MAY contain the module-version of target YANG modules
>     (one of revision-date or module-version MUST be specified).
>  3. Versioning of a target YANG modules makes it easier to decide if the
>     instance data set may be used with newer versions of the target modules.
> 
> IMHO all 3 statements are needed. This is my preferred order, but  2,3,1
> would also be OK. IMHO 2 and 3 are related.
> 
> Is this better?

I think the 2 then 1 ordering makes things clearer.

I'm not convinced of 3.  That would not be the primary use case of
instance data, nor does it ensure compatibility.  For example, just
because one snapshot of instance data is compatible between two target
module versions doesn't mean that all allowed values will be.

It would still be up to the consumer to use the semantic versioning
rules and other tooling to determine the full level of compatibility
between two versions of a target module with respect to their use cases.

Joe

> 
> regards Balazs
> 
> On 2019. 02. 13. 16:55, Joe Clarke wrote:

---

From: Balázs Lengyel <[email-masked]>
Date: Wed, 13 Feb 2019 16:55:09 +0000

Hello Joe,

If you have a file containing config=true data that you want to
load into the yang server and was produced for
ietf-netconf-acm#1.0.0

AND

if you see that your system has  ietf-netconf-acm#1.3.0  you can
immediately know that the instance data set is usable as the two
versions of the target module are BC.

IMHO this helps, thus I think 3) is valid. Now you can only do
this if following 2), you know the original version of the target
ietf-netconf-acm. So: 2) and 3) are connected. I want them side by
side.

If you have an instance-data file about ietf-alarms#2.0.1 listing
your alarm types, but your system works according to
ietf-alarms#2.0.3 you immediately know that you can interpret the
instance-data set with your SW as the two versions are
functionally the same. IMHO that helps.

I agree that in other cases the situation might not be so
trivial, that's why I only wrote "helps" not something stronger.

Do you agree that  3) is valid?

Do you agree that  that 2) and 3) are connected?

would 2,3,1 be a better order?

regards Balazs

On 2019. 02. 13. 17:17, Joe Clarke
wrote:

Hello Joe,

I tried to say 3 things:

Is this better?

Joe

regards Balazs

Hello,

Joe

regards Balazs

---

From: Robert Wilton <[email-masked]>
Date: Wed, 13 Feb 2019 17:26:53 +0000

The other common case is upgrading the startup configuration of a device 
that has an updated schema due to software update.

A more complicated case would be software downgrade, that in principal 
could be handled in the same way.

Thanks,
Rob

On 13/02/2019 16:55, Balázs Lengyel wrote:
>
> Hello Joe,
>
> If you have a file containing config=true data that you want to load 
> into the yang server and was produced for ietf-netconf-acm#1.0.0
> AND
> IMHO this helps, thus I think 3) is valid. Now you can only do this if 
> following 2), you know the original version of the target 
> ietf-netconf-acm. So: 2) and 3) are connected. I want them side by side.
>
> If you have an instance-data file about ietf-alarms#2.0.1 listing your 
> alarm types, but your system works according to ietf-alarms#2.0.3 you 
> immediately know that you can interpret the instance-data set with 
> your SW as the two versions are functionally the same. IMHO that helps.
>
> I agree that in other cases the situation might not be so trivial, 
> that's why I only wrote "helps" not something stronger.
>
>   * Do you agree that  3) is valid?
>   * Do you agree that  that 2) and 3) are connected?
>   * would 2,3,1 be a better order?
>
> regards Balazs
>
> On 2019. 02. 13. 17:17, Joe Clarke wrote:
>>> Mobile: +36-70-330-7909              email:[email-masked]  
>>>
>>>
> Mobile: +36-70-330-7909              email:[email-masked]  
>

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 12:32:36 -0500

> could be handled in the same way.

I agree that this is a good use case of instance data (plus additional
tooling).  I could then see how my config would change based on the new
schema.  But the key is that tooling.  I don't see how I'd do a config
migration of _my_ instance data otherwise.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Wed, 13 Feb 2019 17:40:53 +0000

> migration of _my_ instance data otherwise.

Some devices may have bespoke methods to achieve this, but this would be 
outside of standardized YANG.

This is another scenario that I think that exactly the same ideas that 
version selection could help with - not surprising because it is really 
the same underlying problem that is being solved.

Thanks,
Rob

> .

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 12:45:10 -0500

> the same underlying problem that is being solved.

I agree it's the same problem, I just don't see how instance data alone
solves this.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Wed, 13 Feb 2019 17:50:39 +0000

> I agree it's the same problem, I just don't see how instance data alone

It doesn't.

For instance data to be meaningful you need to know what schema it is 
associated with (e.g. a YANG package or YANG library datastore schema).  
In either case that schema should represent a specific set of modules at 
specific revisions, and/or versions (if a YANG package is used).

Thanks,
Rob

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 12:51:41 -0500

On 2/13/19 11:55, Balázs Lengyel wrote:
> immediately know that you can interpret the instance-data set with your
> SW as the two versions are functionally the same. IMHO that helps.

I don't doubt that having semver as metadata for instance data is
valuable.  I completely agree with what you say here.

But, if I have instance data for #3.0.0, I don't know for certain if my
code that uses #2.0.3 will work.  If the two instance sets happen to
line up for the data in #3.0.0, that's good.  But I don't know if all
potential data will line up without looking at the node differences in
the schema.

>   * Do you agree that  3) is valid?

In the example you mentioned above it does.  I as a use can assume that
if I have 2.0.1 instance data it will work with a device that supports
2.0.3.  And I know this because instance data metadata has a semver.

For the reverse, instance data doesn't help as much (if at all).

>   * Do you agree that  that 2) and 3) are connected?

Yes insofar as what I mentioned above.

>   * would 2,3,1 be a better order?

Yes.

Joe

---

From: Joe Clarke <[email-masked]>
Date: Wed, 13 Feb 2019 12:52:24 -0500

> specific revisions, and/or versions (if a YANG package is used).

Agree completely.  I think we're all on the same page ultimately.  Maybe
it's just semantics at this point.

Joe

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 14 Feb 2019 09:08:22 +0000

I agree that tooling is need. Still I believe that the 3 statements are 
true. So my last text proposal is:

"Instance data sets do not have a semantic version as compatibility
     for instance data is undefined.

Instance data MAY contain the module-version of target YANG modules
     (one of revision-date or module-version MUST be specified).

Versioning of a target YANG modules makes it easier to decide if an
     instance data set may be used with newer versions of the target modules."

regards Balazs

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 14 Feb 2019 09:11:50 +0000

On 2019. 02. 13. 18:50, Robert Wilton wrote:
> associated with (e.g. a YANG package or YANG library datastore 
> schema).  In either case that schema should represent a specific set 
> of modules at specific revisions, and/or versions (if a YANG package 
> is used).
>
BALAZS: And that is what is stated in 
https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-01#section-3.1
It does not solve complex problems like a downgrade, but provide all 
useful information available.

---

From: Balázs Lengyel <[email-masked]>
Date: Thu, 14 Feb 2019 09:15:25 +0000

"Instance
data sets do not have a semantic version as compatibility

modules

(one of revision-date or module-version MUST be
specified).

In certain cases versioning of a
target YANG modules makes it easier to decide if an

instance data set may be used with newer versions of the
target modules."

Added: in certain cases, to indicate it solves some of the
problems, but not all.

regards Balazs

On 2019. 02. 14. 10:08, Balázs Lengyel
wrote:

I
agree that tooling is need. Still I believe that the 3 statements
are true. So my last text proposal is:

"Instance data sets do not have a semantic version as
compatibility

modules

Versioning of a target YANG modules makes it easier to decide if
an

instance data set may be used with newer versions of the
target modules."

regards Balazs

The other common case is upgrading the
startup configuration of a device

A more complicated case would be software downgrade, that in
principal

I agree that this is a good use case of instance data (plus
additional

tooling).  I could then see how my config would change based on
the new

schema.  But the key is that tooling.  I don't see how I'd do a
config

Joe

Thanks,

Rob

Hello Joe,

If you have a file containing config=true data that you want
to load

into the yang server and was produced for
ietf-netconf-acm#1.0.0

AND

if you see that your system has  ietf-netconf-acm#1.3.0  you
can

immediately know that the instance data set is usable as the
two

IMHO this helps, thus I think 3) is valid. Now you can only
do this if

ietf-netconf-acm. So: 2) and 3) are connected. I want them
side by side.

If you have an instance-data file about ietf-alarms#2.0.1
listing your

alarm types, but your system works according to
ietf-alarms#2.0.3 you

immediately know that you can interpret the instance-data
set with

your SW as the two versions are functionally the same. IMHO
that helps.

trivial,

regards Balazs

On 2/13/19 11:06, Balázs Lengyel
wrote:

Hello Joe,

I tried to say 3 things:

1. Instance data sets do not have a semantic version
as compatibility

2. Instance data MAY contain the module-version of
target YANG modules

(one of revision-date or module-version MUST be
specified).

3. Versioning of a target YANG modules makes it easier
to decide if the

instance data set may be used with newer versions
of the target modules.

IMHO all 3 statements are needed. This is my preferred
order, but  2,3,1

Is this better?

I'm not convinced of 3.  That would not be the primary use
case of

instance data, nor does it ensure compatibility.  For
example, just

because one snapshot of instance data is compatible
between two target

module versions doesn't mean that all allowed values will
be.

It would still be up to the consumer to use the semantic
versioning

rules and other tooling to determine the full level of
compatibility

between two versions of a target module with respect to
their use cases.

Joe

regards Balazs

On 2/13/19 06:53, Balázs Lengyel
wrote:

Hello,

Here is a short updated chapter about semver and
instance-data. Thanks

(To all native speakers: IMO the content is fine,
but maybe the English

can be improved.)

What I found confusing is that the first paragraph
doesn't gel with the

second.  YANG instance data may have a version number
of the target

module.  YANG instance data itself will not have a
version number.  I

think this is what you're trying to say, but I didn't
find it clear.

Maybe changing the order of the first two paragraphs
will help, and then

While the target YANG module's version may be present
as instance

metadata, YANG instance data sets themselves will not
have their own

distinct semantic version numbers.  The concept of
backwards

In the third paragraph, semver as instance metadata
will allow one to

know from which version of a module the instance data
comes.  It won't

necessarily help them with backward compatibility.
That is specific to

the target modules themselves.  I guess I'm saying
this paragraph isn't

needed, IMHO.

Joe

regards Balazs

[email-masked]

--

Balazs Lengyel                       Ericsson Hungary
Ltd.

Senior Specialist

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

[email-masked]

--

Senior Specialist

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

[email-masked]