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: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany Fax: +49 421 200 3103 <http://www.jacobs-university.de/> _______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
