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

Ladislav Lhotka <lhotka@nic.cz> Thu, 09 March 2017 07:41 UTC

Return-Path: <lhotka@nic.cz>
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 DD8F9128E18 for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 23:41:38 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -7.02
X-Spam-Level:
X-Spam-Status: No, score=-7.02 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=nic.cz
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 B2PnpGzVpQuA for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 23:41:37 -0800 (PST)
Received: from mail.nic.cz (mail.nic.cz [217.31.204.67]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 32A0C1204D9 for <netmod@ietf.org>; Wed, 8 Mar 2017 23:41:36 -0800 (PST)
Received: from [IPv6:2001:718:1a02:1:b460:39eb:a41b:3316] (unknown [IPv6:2001:718:1a02:1:b460:39eb:a41b:3316]) by mail.nic.cz (Postfix) with ESMTPSA id 0E1D760950; Thu, 9 Mar 2017 08:41:35 +0100 (CET)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=nic.cz; s=default; t=1489045295; bh=MSLmOLVhKVgke/CSxuHQjfHRPgUg5o/QxJjNXax8n3Y=; h=From:Date:To; b=nHNfvu9XuiUMx/RGuxFt5gP8niAxooz3RSBHt7NJhWrW0Ez8sqNDPwJCwpXk81bUR xTRKL5AvYb/7X0TMQ7J0lZ0Q/fT65AL0WGXGSQ4eCsT2+W5dxpU/ZGAA9RCISDAAGb +EtSuzLWEGnSCcvZycXBxvo0LQgzZ3IKky+Scxj0=
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 10.2 \(3259\))
From: Ladislav Lhotka <lhotka@nic.cz>
In-Reply-To: <F01E2727-F1BA-40E6-AAA7-F7842BF21B0C@juniper.net>
Date: Thu, 9 Mar 2017 08:41:36 +0100
Content-Transfer-Encoding: quoted-printable
Message-Id: <25DABE48-94C2-46B5-9DCB-B6F01E8C3BAB@nic.cz>
References: <20170303191348.GA3570@elstar.local> <20170307.185911.779366639761395028.mbj@tail-f.com> <F01E2727-F1BA-40E6-AAA7-F7842BF21B0C@juniper.net>
To: Kent Watsen <kwatsen@juniper.net>
X-Mailer: Apple Mail (2.3259)
X-Virus-Scanned: clamav-milter 0.99.2 at mail
X-Virus-Status: Clean
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/QWLrnZp5dZa6s2RW7ejc35MY_Zs>
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
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: Thu, 09 Mar 2017 07:41:39 -0000

> On 8 Mar 2017, at 18:40, Kent Watsen <kwatsen@juniper.net> 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?

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

>  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.
> 
> 
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

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