Subject: [netmod] rfc 6087bis - stress importance of instance examples

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 3 Mar 2017 20:13:48 +0100

Hi,

my experience is that when writing YANG modules it is tremendously
helpful to focus on the instance documents. I find it essential to
write down example snippets of instance documents to see whether they
look elegant or clumsy. This is often not easy to determine from just
reading a YANG model, in particular if groupings are involved. Examples
help so much - you can easily spot whether the usage of singular or
plural is reasonable in your names, whether you have redundancy in
your names, whether the overall organization is effective. Even better,
we have tools that can validate the examples so we can even be sure
the examples are correct. (And if you do not know whether you got
your pattern statement right, well, one way is to write examples.)

I think we should encourage authors to write examples. It will help
them to create better models and it will help reviewers tremendously
while reviewing models. Good examples will also help users to get
started.

/js (who apparently is doing some heavy YANG reviewing work today)

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

---

From: Phil Shafer <[email-masked]>
Date: Fri, 3 Mar 2017 15:05:10 -0500

+1.

As someone who does internal code review for Juniper changes, having
an example is a huge help to the reviewer (me).  It also helps to
convince the module author (them) that what they are advocating
will look horrible.

Thanks,
 Phil

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

---

From: "Joel M. Halpern" <[email-masked]>
Date: Fri, 3 Mar 2017 16:08:28 -0500

I would have to agree that examples are very useful.

they are useful for comprehensibility even in cases the YANG structure 
may be unwieldly.  For example, if the XML / JSON is expected to be 
generated (as well as consumed) by programmatic processes.

Yours,
Joel

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 07 Mar 2017 18:59:11 +0100 (CET)

Juergen Schoenwaelder <[email-masked]> wrote:
> I think we should encourage authors to write examples.

+1  And also encourage authors to validate the examples using their
favorite YANG instance validation tool.

/martin

> It will help

---

From: Kent Watsen <[email-masked]>
Date: Wed, 8 Mar 2017 17:40:44 +0000

> +1  And also encourage authors to validate the examples 
> using their favorite YANG instance validation tool.

Please note this from the latest 6087bis update:

   4.12.  Module Usage Examples

   Each specification that defines one or more modules SHOULD contain
   usage examples, either throughout the document or in an appendix.
   This includes example XML instance document snippets to demonstrate
   the intended usage of the YANG module(s).

and I already wrote this:

  Nice addition, but should it say something about JSON, in addition to XML?
  Perhaps that, unless there is a reason to only pick one encoding, examples
  should be split between the two?  - just throwing it out there to see if this is
  something we might want to recommend...thoughts?

  https://mailarchive.ietf.org/arch/msg/netmod/dOpSYzM_J05Sdmgt-MyYmqJIUz0

K.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 8 Mar 2017 20:47:56 +0100

>   https://mailarchive.ietf.org/arch/msg/netmod/dOpSYzM_J05Sdmgt-MyYmqJIUz0

I think the purpose of section 4.12 is to encourage people to check
that their definitions lead to reasonable instance documents. It is
easy to choose identifiers in the schema that look reasonable in the
schema but horrible in instance documents. The purpose of the examples
should in general not be to showcase that YANG can have different
instance representation formats. I would leave it to the WG to decide
whether they prefer examples in JSON or XML. In LMAP, I once had
examples in both XML and JSON and that was not useful (lots of
additional pages with no real added value).

All that said, you likely end up naming things slightly different
depending on whether you look primarily at a JSON encoded instance
document or an XML encoded instance document. But I do not care much
as long as identifiers are reasonably consistent.

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 9 Mar 2017 08:41:36 +0100

> On 8 Mar 2017, at 18:40, Kent Watsen <[email-masked]> wrote:
> 
> 
> 

I'd suggest:

"This includes example instance documents or snippets in an appropriate encoding to demonstrate the intended usage of the YANG module(s)."

Lada

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