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

From: Balazs Lengyel <[email-masked]>
Date: Thu, 8 Feb 2018 10:17:25 +0100

Hello,

With Benoit I prepared a draft about how to document and use YANG
defined instance data. It could be useful for documenting  server
capabilities or preloading data defined in implementation time and
probably for other purposes as well.

regards Balazs

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

Subject:

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

Date:

Wed, 7 Feb 2018 09:28:50 -0800

From:

[email-masked]

To:

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

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

Name: draft-lengyel-netmod-yang-instance-data
Revision: 00
Title: YANG Instance Data Files and their use for Documenting Server Capabilities
Document date: 2018-02-06
Group: Individual Submission
Pages: 10
URL: https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-00.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-00
Htmlized: https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data-00

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: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 8 Feb 2018 10:24:08 +0100

[Removing NETCONF since the I-D says -netmod-.]

I flipped through the I-D yesterday and I think a common format for
instance data trees should be NMDA aware these days.

/js

On Thu, Feb 08, 2018 at 10:17:25AM +0100, Balazs Lengyel wrote:
>    Hello,
> 
>    With Benoit I prepared a draft about how to document and use YANG defined
>    instance data. It could be useful for documenting  server capabilities or
>    preloading data defined in implementation time and probably for other
>    purposes as well.
> 
>    regards Balazs
> 
>    Subject: New Version Notification for
>       Date: Wed, 7 Feb 2018 09:28:50 -0800
>       From: [1][email-masked]
>         To: Benoit Claise [2]<[email-masked]>, Balazs Lengyel
>             [3]<[email-masked]>
> 
>  URL:            [4]https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-00.txt
>  Status:         [5]https://datatracker.ietf.org/doc/draft-lengyel-netmod-yang-instance-data/
>  Htmlized:       [6]https://tools.ietf.org/html/draft-lengyel-netmod-yang-instance-data-00
>  Htmlized:       [7]https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data-00
> 
> 
>  Abstract:
>  Mobile: +36-70-330-7909              email: [8][email-masked]
> 
> References
> 
>    Visible links
>    1. mailto:[email-masked]
>    2. mailto:[email-masked]
>    3. mailto:[email-masked]
>    4. https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-00.txt
>    5. https://datatracker.ietf.org/doc/draft-lengyel-netmod-yang-instance-data/
>    6. https://tools.ietf.org/html/draft-lengyel-netmod-yang-instance-data-00
>    7. https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data-00
>    8. mailto:[email-masked]

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

-- 
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: Balazs Lengyel <[email-masked]>
Date: Fri, 9 Feb 2018 16:07:11 +0100

Hello Jurgen,

I will gladly add NMDA to the draft. However could you please be more 
specific. Which part of NMDA are you missing?
Is it the example of yanglib that you would like updated?

As the instance-data can be used to document and/or load    both 
config=true and false data it is IMHO relevant to the 
candidate/running/operational datastores. However whether it should be 
used to just document data or also to load data, and how exactly such a 
load should be implemented  is out of scope. And yes using one SW kit 
config=false data can be loaded from file too.

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 9 Feb 2018 17:25:26 +0100

How do I know which datastore the data belongs to? Would it not make
sense to carry that information inline? If we do not carry this
information inline, how is that information supposed to be provided
if for example this format is used to validate examples included in
documentation?

/js

On Fri, Feb 09, 2018 at 04:07:11PM +0100, Balazs Lengyel wrote:
> As the instance-data can be used to document and/or load    both config=true
> and false data it is IMHO relevant to the candidate/running/operational
> datastores. However whether it should be used to just document data or also
> to load data, and how exactly such a load should be implemented  is out of
> scope. And yes using one SW kit config=false data can be loaded from file
> too.
> 
> regards Balazs
> 
>

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 12 Feb 2018 10:49:48 +0100

Hello Jurgen,

IMHO once we know whether the data is config=false or true and
know the datastores the server supports the datastore the instance
data is relevant to is fixed. One exception is the possible
loading of dynamic datastores. However as I do not have a use-case
for these and we do not have any dynamic datastores defined, IMHO
we can leave the usage of these datastores out of scope. If I
added the following paragraphs would that help?

"If the instance data specifies config false (state data) and
the server support the operational datastore, the instance data
documents the operational datastore. If  the operational
datastore is not supported the data documents additional state
data that is stored outside the configuration datastores. The
instance data MAY be used to load the relevant datastore or it
MAY just be used to document its content.

If the instance data specifies config true
(configuration data)  the instance data documents the running
datastore.  The instance data MAY be used to load the running
datastore or it MAY just be used to document its content. While
the instance data format MAY be used to load other e.g. dynamic
datastores that is out of scope for this specification."

Also further clarification may be provided for each use-case
in the relevant document.

regards Balazs

On 2/9/2018 5:25 PM, Juergen
Schoenwaelder wrote:

/js

Hello Jurgen,

regards Balazs

/js

Hello,

regards Balazs

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

Abstract:

The IETF Secretariat

References

Visible links

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 12 Feb 2018 11:47:20 +0100

On Mon, Feb 12, 2018 at 10:49:48AM +0100, Balazs Lengyel wrote:
>    Hello Jurgen,
> 
>    IMHO once we know whether the data is config=false or true and know the
>    datastores the server supports the datastore the instance data is relevant
>    to is fixed. One exception is the possible loading of dynamic datastores.
>    However as I do not have a use-case for these and we do not have any
>    dynamic datastores defined, IMHO we can leave the usage of these
>    datastores out of scope. If I added the following paragraphs would that
>    help?
> 
>    "If the instance data specifies config false (state data) and the server
>    support the operational datastore, the instance data documents the
>    operational datastore. If  the operational datastore is not supported the
>    data documents additional state data that is stored outside the
>    configuration datastores. The instance data MAY be used to load the
>    relevant datastore or it MAY just be used to document its content.

Having to guess the datastore from the instance data feels wrong to
me. It is not robust.

>    If the instance data specifies config true (configuration data)  the
>    instance data documents the running datastore.  The instance data MAY be
>    used to load the running  datastore or it MAY just be used to document its
>    content. While the instance data format MAY be used to load other e.g.
>    dynamic datastores that is out of scope for this specification."
> 
>    Also further clarification may be provided for each use-case in the
>    relevant document.

Why not make the data format robust? What speaks against indicating
explicitly to which datastore data belongs?

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 12 Feb 2018 12:14:11 +0100

> explicitly to which datastore data belongs?
BALAZS:  Sorry but where is the guessing?
The YANG model explicitly states whether data is config=false or true.
For config=true data it is always the running datastore
For config=false data it only depends on the NMDA support. E.g. the 
yanglib model will be used on new and old servers too.
Also it is an explicit aim of the draft that we should allow mixing of 
config=true and config=false data in the same instance data set.

Would you prefer that I add as metadata "ida:config-datastore=XXX" ? 
Here XXX could be running or some dynamic (e.g. SDN) with default being 
running. Or do you see any use case for documenting/loading candidate, 
startup, intended or operational data for config=true ? If so please 
describe.

Config=false data it will always go into operational or "other" in case 
of a preNMDA server; so I don't see a need for any extra selector here.

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 12 Feb 2018 12:40:58 +0100

> BALAZS:  Sorry but where is the guessing?

If there is no config false instance, how do I decide?

> For config=false data it only depends on the NMDA support. E.g. the yanglib
> model will be used on new and old servers too.
> Would you prefer that I add as metadata "ida:config-datastore=XXX" ? Here
> XXX could be running or some dynamic (e.g. SDN) with default being running.
> Or do you see any use case for documenting/loading candidate, startup,
> intended or operational data for config=true ? If so please describe.
> 
> Config=false data it will always go into operational or "other" in case of a
> preNMDA server; so I don't see a need for any extra selector here.

I see a use case of having examples in documents (which likely are not
even complete) and I think tools prefer to know upfront which
datastore the example belongs to without first doing complex
processing.

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 12 Feb 2018 13:51:30 +0100

Hello Jurgen,
OK, I will add some text about:

datastore selection, default being running/operational for config 
true/false data, mentioning NMDA.

I will add a ida:datastore metadata that can placed on any any data-node (?)

A section about a use case of having examples in documents

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 12 Feb 2018 14:15:29 +0100

On Mon, Feb 12, 2018 at 01:51:30PM +0100, Balazs Lengyel wrote:
> datastore selection, default being running/operational for config true/false
> data, mentioning NMDA.
>

Once again, this is ambiguous.

> I will add a ida:datastore metadata that can placed on any any data-node (?)

On any data node???

/js

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 12 Feb 2018 15:09:08 +0100

Hello Jurgen,

What would be your preference? How should we specify datastore? Could 
you please provide some description.

regards Balazs

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 12 Feb 2018 15:26:40 +0100

Since you already have several attributes for the instance-data
element (ida:instance-data-set, ida:revision, ida:description,
ida:contact), adding ida:datastore may do the work (but not on a per
node basis, it needs to be restricted to be used only on the
instance-data element.

Note that some of these attributes are not well defined. I do not
understand "The annotation SHALL only be used on the top level <data>
element in RFC XXXX defined YANG Instance Data files." Perhaps you
want to restrict them to be only used on instance-data? (Which
namespace does this live in if any?) It is kind of unclear why you
define the attributes listed above in YANG but you do not define
instance-data itself in YANG. It seems you either define everything
about this format in YANG or nothing. But yes, this is a -00 so I
assume all of this can be improved.

/js

On Mon, Feb 12, 2018 at 03:09:08PM +0100, Balazs Lengyel wrote:
> Hello Jurgen,
> 
> What would be your preference? How should we specify datastore? Could you
> please provide some description.
> 
> regards Balazs
> 
>

---

From: Kent Watsen <[email-masked]>
Date: Mon, 12 Feb 2018 17:20:48 +0000

Hi Balazs,

I'm unclear about the scope of the problem.  Is it limited to server capabilities?    It seems that the idea is to move from having a stateful connection to a live server to having a way to pass the equivalent state even when not connected to the server.

Related, but probably not what you're angling for, I've been having issues with validating RESTCONF examples.  The issue is that the RESTCONF documents are context specific.  For instance, GET /widgets/ returns a document that might have an outermost element called "widgets", whereas GET /widgets/widget=foo returns a document that might have an outermost element called "widget".   In order to validate the second document, my code first wraps the "widget" element with a "widgets" element, and then the validation tools work.

Perhaps a more generalized instance data mechanism could include where in the tree the data is situated?   For example, it would be helpful if an action's instance data could provide more context (e.g., the input/output documents could indicate the name of the action, the object that the action was invoked on, etc.).

Generally, there is some state being held by the protocols that complicates examining instance data outside of the protocol, as extra bits of state need to be passed around separately.  It would be nice if the documents were (or at least could be) more self-contained.

Kent // contributor

On 2/8/18, 4:17 AM, "netmod on behalf of Balazs Lengyel" <[email-masked]<mailto:[email-masked]> on behalf of [email-masked]<mailto:[email-masked]>> wrote:

Hello,

With Benoit I prepared a draft about how to document and use YANG defined instance data. It could be useful for documenting  server capabilities or preloading data defined in implementation time and probably for other purposes as well.

regards Balazs

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

New Version Notification for draft-lengyel-netmod-yang-instance-data-00.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:      00

Pages:         10

URL:            https://www.ietf.org/internet-drafts/draft-lengyel-netmod-yang-instance-data-00.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_internet-2Ddrafts_draft-2Dlengyel-2Dnetmod-2Dyang-2Dinstance-2Ddata-2D00.txt&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=hnU9-LLpaIzWowZefBxYfrcvaEILD8Bz2n6gSTHI5WQ&s=-cx3SgYxfmIlRWYz3RLb81BDCoJZy2ViqIAI8Cq0dlk&e=>

Status:         https://datatracker.ietf.org/doc/draft-lengyel-netmod-yang-instance-data/<https://urldefense.proofpoint.com/v2/url?u=https-3A__datatracker.ietf.org_doc_draft-2Dlengyel-2Dnetmod-2Dyang-2Dinstance-2Ddata_&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=hnU9-LLpaIzWowZefBxYfrcvaEILD8Bz2n6gSTHI5WQ&s=veCJKfYZs8V9krZOIZlMR1HS6jmmO0nk5FCXwYengSQ&e=>

Htmlized:       https://tools.ietf.org/html/draft-lengyel-netmod-yang-instance-data-00<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dlengyel-2Dnetmod-2Dyang-2Dinstance-2Ddata-2D00&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=hnU9-LLpaIzWowZefBxYfrcvaEILD8Bz2n6gSTHI5WQ&s=Ro0Lzr3-CMLj03kjq2WVcZCUbBBUqrWPls1ZES0GbnY&e=>

Htmlized:       https://datatracker.ietf.org/doc/html/draft-lengyel-netmod-yang-instance-data-00<https://urldefense.proofpoint.com/v2/url?u=https-3A__datatracker.ietf.org_doc_html_draft-2Dlengyel-2Dnetmod-2Dyang-2Dinstance-2Ddata-2D00&d=DwMDaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=hnU9-LLpaIzWowZefBxYfrcvaEILD8Bz2n6gSTHI5WQ&s=PTQT_O1Yp9WGYa2aodkOfVe5l0DFPkKfeodj4y5ptH0&e=>

Abstract:

   files.

The IETF Secretariat

--

Senior Specialist

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