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

[Juergen Schoenwaelder <[e-mail]>]

On Wed, Mar 08, 2017 at 05:40:44PM +0000, Kent Watsen 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.
> 
> 
> 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
>

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

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <http://www.jacobs-university.de/>