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

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Wed, 08 March 2017 19:47 UTC

Return-Path: <j.schoenwaelder@jacobs-university.de>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id C800812946E for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 11:47:54 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.201
X-Spam-Level:
X-Spam-Status: No, score=-4.201 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, RP_MATCHES_RCVD=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id FBW90LCtpuWb for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 11:47:53 -0800 (PST)
Received: from atlas3.jacobs-university.de (atlas3.jacobs-university.de [212.201.44.18]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 56249120725 for <netmod@ietf.org>; Wed, 8 Mar 2017 11:47:53 -0800 (PST)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas3.jacobs-university.de (Postfix) with ESMTP id 24FBF15CF; Wed, 8 Mar 2017 20:47:52 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas3.jacobs-university.de ([10.70.0.205]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10030) with ESMTP id 7yDsDzIcm02t; Wed, 8 Mar 2017 20:47:51 +0100 (CET)
Received: from hermes.jacobs-university.de (hermes.jacobs-university.de [212.201.44.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "hermes.jacobs-university.de", Issuer "Jacobs University CA - G01" (verified OK)) by atlas3.jacobs-university.de (Postfix) with ESMTPS; Wed, 8 Mar 2017 20:47:51 +0100 (CET)
Received: from localhost (demetrius4.jacobs-university.de [212.201.44.49]) by hermes.jacobs-university.de (Postfix) with ESMTP id B82A920039; Wed, 8 Mar 2017 20:47:51 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius4.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id BFXOsA0e4heI; Wed, 8 Mar 2017 20:47:50 +0100 (CET)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id A4AB420035; Wed, 8 Mar 2017 20:47:50 +0100 (CET)
Received: by elstar.local (Postfix, from userid 501) id 20B963E9C434; Wed, 8 Mar 2017 20:47:56 +0100 (CET)
Date: Wed, 8 Mar 2017 20:47:56 +0100
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: Kent Watsen <kwatsen@juniper.net>
Message-ID: <20170308194756.GB10080@elstar.local>
Mail-Followup-To: Kent Watsen <kwatsen@juniper.net>, Martin Bjorklund <mbj@tail-f.com>, "netmod@ietf.org" <netmod@ietf.org>
References: <20170303191348.GA3570@elstar.local> <20170307.185911.779366639761395028.mbj@tail-f.com> <F01E2727-F1BA-40E6-AAA7-F7842BF21B0C@juniper.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <F01E2727-F1BA-40E6-AAA7-F7842BF21B0C@juniper.net>
User-Agent: Mutt/1.6.0 (2016-04-01)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/qwO0deBcd2wUZfK7DXXpoml_76I>
Cc: "netmod@ietf.org" <netmod@ietf.org>
Subject: Re: [netmod] rfc 6087bis - stress importance of instance examples
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
Precedence: list
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 08 Mar 2017 19:47:54 -0000

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/>