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

Kent Watsen <kwatsen@juniper.net> Wed, 08 March 2017 17:40 UTC

Return-Path: <kwatsen@juniper.net>
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 1119812942F for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 09:40:48 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.922
X-Spam-Level:
X-Spam-Status: No, score=-1.922 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=junipernetworks.onmicrosoft.com
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 dF8ubrHBTM3u for <netmod@ietfa.amsl.com>; Wed, 8 Mar 2017 09:40:46 -0800 (PST)
Received: from NAM02-CY1-obe.outbound.protection.outlook.com (mail-cys01nam02on0091.outbound.protection.outlook.com [104.47.37.91]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 80F091270B4 for <netmod@ietf.org>; Wed, 8 Mar 2017 09:40:46 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=junipernetworks.onmicrosoft.com; s=selector1-juniper-net; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=vuoHeOy9PuN2+AFEvQccCobMo2YsSnvCRMigp9cRMyg=; b=W18bd4ZgJup3jSLfccLbUNvdVyQ3qh8xD/YrRZtNAeSQ8opuO47WZ/Nud+6Dud3LfngBtN6Wq7RPC2Xaljy1Wa3v386jJm8J7AsM/3167EdfwJbcEzKb3tgXFlKYDkJpZ8JO9UVXmzOfIgdF7MAAHb7kSayfcM6hRWeYFCAerkI=
Received: from BN3PR0501MB1442.namprd05.prod.outlook.com (10.160.117.151) by BN3PR0501MB1442.namprd05.prod.outlook.com (10.160.117.151) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P384) id 15.1.961.8; Wed, 8 Mar 2017 17:40:45 +0000
Received: from BN3PR0501MB1442.namprd05.prod.outlook.com ([10.160.117.151]) by BN3PR0501MB1442.namprd05.prod.outlook.com ([10.160.117.151]) with mapi id 15.01.0961.012; Wed, 8 Mar 2017 17:40:45 +0000
From: Kent Watsen <kwatsen@juniper.net>
To: Martin Bjorklund <mbj@tail-f.com>, "j.schoenwaelder@jacobs-university.de" <j.schoenwaelder@jacobs-university.de>
Thread-Topic: [netmod] rfc 6087bis - stress importance of instance examples
Thread-Index: AQHSlFJL0qY+3T3n+ESw47YUZTv45KGJsGeAgAE5W4A=
Date: Wed, 8 Mar 2017 17:40:44 +0000
Message-ID: <F01E2727-F1BA-40E6-AAA7-F7842BF21B0C@juniper.net>
References: <20170303191348.GA3570@elstar.local> <20170307.185911.779366639761395028.mbj@tail-f.com>
In-Reply-To: <20170307.185911.779366639761395028.mbj@tail-f.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
user-agent: Microsoft-MacOutlook/f.1f.0.170216
authentication-results: tail-f.com; dkim=none (message not signed) header.d=none;tail-f.com; dmarc=none action=none header.from=juniper.net;
x-ms-exchange-messagesentrepresentingtype: 1
x-originating-ip: [66.129.241.13]
x-microsoft-exchange-diagnostics: 1; BN3PR0501MB1442; 7:RKQdmnHB+Q3IW8wA1X6L9crN7D5f6aYb+rWFOQ5W8NE+7gkiIUc//SztNVEyhMiWAqBk9ZTxf/ByRqn3bRd4Zt9Y7cBMdBBOAOeVGf78Lgu6Au/0LtQr5nXEqviiTEIh+w6qHugdIWhN1qVi5wRiI58UieIBO3Aj/XlRrXQDX+wK9S0cIRTbJiuJ8NmWOZQiO129G3Rv6O8ceQ6n/0t92jmdESiJHr28WdjKm8IbmkzO7qTXDHGwwrwasTKuyShRwyZJMOss9t/9/K6bgwO9WVGiGXAkrSvYMDtMa7ELs4hw8yRXojjfFdrg1nZb9vol/AHSfRBSakXsXZGTc3Rj5Q==
x-ms-office365-filtering-correlation-id: 95e76717-9d33-4186-e21d-08d4664a3fd7
x-ms-office365-filtering-ht: Tenant
x-microsoft-antispam: UriScan:; BCL:0; PCL:0; RULEID:(22001)(48565401081); SRVR:BN3PR0501MB1442;
x-microsoft-antispam-prvs: <BN3PR0501MB1442D68B11D687E7B5B943BAA52E0@BN3PR0501MB1442.namprd05.prod.outlook.com>
x-exchange-antispam-report-test: UriScan:;
x-exchange-antispam-report-cfa-test: BCL:0; PCL:0; RULEID:(6040375)(601004)(2401047)(5005006)(8121501046)(10201501046)(3002001)(6055026)(6041248)(20161123560025)(20161123562025)(20161123555025)(20161123558025)(20161123564025)(6072148); SRVR:BN3PR0501MB1442; BCL:0; PCL:0; RULEID:; SRVR:BN3PR0501MB1442;
x-forefront-prvs: 02408926C4
x-forefront-antispam-report: SFV:NSPM; SFS:(10019020)(6009001)(39840400002)(39860400002)(39450400003)(39410400002)(39850400002)(102836003)(77096006)(6506006)(86362001)(6436002)(6486002)(25786008)(6512007)(3846002)(106116001)(122556002)(305945005)(2900100001)(8936002)(81166006)(36756003)(6116002)(8676002)(189998001)(66066001)(99286003)(6306002)(53936002)(2950100002)(83716003)(5660300001)(82746002)(6246003)(83506001)(229853002)(3280700002)(38730400002)(2906002)(54356999)(50986999)(7736002)(4326008)(4001350100001)(3660700001)(76176999)(33656002); DIR:OUT; SFP:1102; SCL:1; SRVR:BN3PR0501MB1442; H:BN3PR0501MB1442.namprd05.prod.outlook.com; FPR:; SPF:None; MLV:sfv; LANG:en;
spamdiagnosticoutput: 1:99
spamdiagnosticmetadata: NSPM
Content-Type: text/plain; charset="utf-8"
Content-ID: <43E73C95617AA240A6E268B4D80B8379@namprd05.prod.outlook.com>
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-OriginatorOrg: juniper.net
X-MS-Exchange-CrossTenant-originalarrivaltime: 08 Mar 2017 17:40:44.9245 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: bea78b3c-4cdb-4130-854a-1d193232e5f4
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN3PR0501MB1442
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/PrO3yxto7GycVxFK-l5KEClctnw>
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: Wed, 08 Mar 2017 17:40:48 -0000


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


K.