Re: [yang-doctors] Normative Language in YANG descriptions

"Acee Lindem (acee)" <acee@cisco.com> Thu, 17 September 2020 16:31 UTC

Return-Path: <acee@cisco.com>
X-Original-To: yang-doctors@ietfa.amsl.com
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 822D63A0D89 for <yang-doctors@ietfa.amsl.com>; Thu, 17 Sep 2020 09:31:22 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -9.619
X-Spam-Level:
X-Spam-Status: No, score=-9.619 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_PASS=-0.001, URIBL_BLOCKED=0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.com header.b=WZAI9y+9; dkim=pass (1024-bit key) header.d=cisco.onmicrosoft.com header.b=MzLKQB8C
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 3cY6tmQFp-t9 for <yang-doctors@ietfa.amsl.com>; Thu, 17 Sep 2020 09:31:20 -0700 (PDT)
Received: from rcdn-iport-4.cisco.com (rcdn-iport-4.cisco.com [173.37.86.75]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 015033A0DE4 for <yang-doctors@ietf.org>; Thu, 17 Sep 2020 09:30:59 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=21465; q=dns/txt; s=iport; t=1600360259; x=1601569859; h=from:to:subject:date:message-id:references:in-reply-to: mime-version; bh=iMkYbZ6AKuiWSmw9Uq9JBHamn1IyxBspHE8XP8YSLHk=; b=WZAI9y+9ayF4PlWtOwTZTGqR0Vw3ZNFUc1LOiWfW2UmJyhcJUemh5k1i 1NM9y4+uFY4yNo/K/5NLSC8+hyjX3atoLLD4Nb+vLnSMAmfqiSKJeIqbf v+fjS3uo+tKS2A4/KX7HJSlaHtLKRwSx+Fxvp4Q3JWoO4ClvS6qLDzumw Q=;
IronPort-PHdr: 9a23:dQJMFBa/Kl9Es+qwJmvOHFf/LSx94ef9IxIV55w7irlHbqWk+dH4MVfC4el21QWTD5TG7vtbjPDVqObrXmlTqZqCsXVXdptKWldFjMgNhAUvDYaDDlGzN//laSE2XaEgHF9o9n22Kw5ZTcD5YVCBs2C35CEVABbkcwFyI7e9Fovblc/i0ee09tXaaBlJgzzoZ7R0IV22oAzdu9NQj5FlL/M6ywDCpT1DfOEFyA==
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: A0C4AAA6jmNf/4oNJK1cAxoBAQEBAQEBAQEBAwEBAQESAQEBAQICAQEBAYIPgSMvUQdwWS8sCoQvg0YDjXSKDYl4hG6CUwNVCwEBAQ0BARgBCgoCBAEBhEsCF4IPAiQ4EwIDAQELAQEFAQEBAgEGBG2FXAyFcgEBAQEDAQEQER0BASwMBAkCAgEIEAEDAQIBJwMCAgIZBgYLFAkIAgQBEiKDBAGBfk0DLgEOqmYCgTmIYXaBMoMBAQEFhSINC4IQAwYFgTOCcYNpgQOFTxuCAIE4HIJNPoIaQgEBAgGBcwkBDAkRglAzggsiky+GfZwuUQqCZ4h1jEyFCAMeoH2SdYphgmqSLQIEAgQFAg4BAQWBayOBV3AVOyoBgj5QFwINjh+DcTOEYYUJATh0AjUCBgEJAQEDCXyLHy2BBgGBEAEB
X-IronPort-AV: E=Sophos;i="5.77,271,1596499200"; d="scan'208,217";a="802742948"
Received: from alln-core-5.cisco.com ([173.36.13.138]) by rcdn-iport-4.cisco.com with ESMTP/TLS/DHE-RSA-SEED-SHA; 17 Sep 2020 16:30:55 +0000
Received: from XCH-ALN-005.cisco.com (xch-aln-005.cisco.com [173.36.7.15]) by alln-core-5.cisco.com (8.15.2/8.15.2) with ESMTPS id 08HGUtQk005278 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=FAIL); Thu, 17 Sep 2020 16:30:55 GMT
Received: from xhs-aln-003.cisco.com (173.37.135.120) by XCH-ALN-005.cisco.com (173.36.7.15) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Thu, 17 Sep 2020 11:30:55 -0500
Received: from xhs-rcd-002.cisco.com (173.37.227.247) by xhs-aln-003.cisco.com (173.37.135.120) with Microsoft SMTP Server (TLS) id 15.0.1497.2; Thu, 17 Sep 2020 11:30:54 -0500
Received: from NAM11-CO1-obe.outbound.protection.outlook.com (72.163.14.9) by xhs-rcd-002.cisco.com (173.37.227.247) with Microsoft SMTP Server (TLS) id 15.0.1497.2 via Frontend Transport; Thu, 17 Sep 2020 11:30:54 -0500
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Zl14aN/wHX56S5TyQ2FVQbInHpdjpccU7A1+oWrzxw9+4SNWQsPWQmDxgAy2kfmQqAlRideJEnzWA4lBtp9pjD8Kg49LGaQgQjg7BQclK/N0guEifB6SO0hk5lFJ6e2UM0tABFrPHqZxizA+IfN4eNEzrAtnULknSBsfqeM8N3A3BbxnRWP0RR7yhocGk8wEEtdnCyc8mGK3ceXFyESQ/SeqFiT/EqNzwIFro5Dg1Z1rtW+3LnX1ST5fXMtutygkqbzCZ9hlgmldcBVuyFhhMbU0rBFIrvKkTMUm53brfLtU1gW6u0EX3a0cB+R5XtPpCbywoFuX3JGkY9wLLRL/7A==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=iMkYbZ6AKuiWSmw9Uq9JBHamn1IyxBspHE8XP8YSLHk=; b=Co+srBwKUGjaPxySan3k2Dd2p5L2K3U9bjYnZ4+k1BedTf0J7swc2xgTheIGD7bzkrfU9SObX37b3lGZ6Ao0RA5d2GmrZ4H7ep4STMq7uILR/3KBQDdss/gm2F/8ePcVPY4EcQScQhz/Io73oMUL9JxhEQUkemHm3pgWIX21GbzRKOwBM7ofIcjijLzCOv9BgV6Y/WCCQI+mLE5t3iCifgVrNc+ezqIr4tKkbQNaKzSvf0O1pUmNTj92mNi0cWmXA3m7IO9Yptd1rX9G2LjxbvcWbNSQp2tl4pGBPZotxvvuFQ32V6AYdbypTZoMYwUdAzEdqbUr1RQvYv+jC9bo5A==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=cisco.com; dmarc=pass action=none header.from=cisco.com; dkim=pass header.d=cisco.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cisco.onmicrosoft.com; s=selector2-cisco-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=iMkYbZ6AKuiWSmw9Uq9JBHamn1IyxBspHE8XP8YSLHk=; b=MzLKQB8CkC6oSjTyb9YqclP7GThiMbZiyngG/OfRsZCcDFq1ZC342/dOZlTWdMkxP7XwCTVRFJCEodFHYl5kcyHlyuHBzPvkq3R0j728ABZ1zhFD5t7DVjwy84L4s+Q0527Ugqi45gcY9Z4lgMbocGUo23pNXtKF2f5h0SWjVTY=
Received: from BYAPR11MB2887.namprd11.prod.outlook.com (2603:10b6:a03:89::27) by BYAPR11MB3013.namprd11.prod.outlook.com (2603:10b6:a03:8b::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3391.11; Thu, 17 Sep 2020 16:30:53 +0000
Received: from BYAPR11MB2887.namprd11.prod.outlook.com ([fe80::ed2a:6cdf:3bc4:dbf2]) by BYAPR11MB2887.namprd11.prod.outlook.com ([fe80::ed2a:6cdf:3bc4:dbf2%6]) with mapi id 15.20.3348.019; Thu, 17 Sep 2020 16:30:53 +0000
From: "Acee Lindem (acee)" <acee@cisco.com>
To: Andy Bierman <andy@yumaworks.com>, Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>, Kent Watsen <kent@watsen.net>, Mahesh Jethanandani <mjethanandani@gmail.com>, YANG Doctors <yang-doctors@ietf.org>
Thread-Topic: [yang-doctors] Normative Language in YANG descriptions
Thread-Index: AQHWjCAMcf1RJd0PWEGPEa1KEepLV6lsR/+AgACzfQCAAAX2AIAAA5KA//+/fYA=
Date: Thu, 17 Sep 2020 16:30:53 +0000
Message-ID: <5DBAC92A-2E74-4CEB-92C1-70C9A983E514@cisco.com>
References: <AE8C544D-75B1-44C5-878F-A6B809B8CC2D@cisco.com> <A139C0F3-A398-4F22-8658-822312AFF043@gmail.com> <010001749cbfefbe-a6d2a8e1-b79f-4c4b-8d40-a12a1e14bd48-000000@email.amazonses.com> <20200917160858.tefrbxdo27jiikz7@anna.jacobs.jacobs-university.de> <CABCOCHRXfnmJJaibJ3buAVY0yq3snX10bvjPZPXbTWutYqPNiQ@mail.gmail.com>
In-Reply-To: <CABCOCHRXfnmJJaibJ3buAVY0yq3snX10bvjPZPXbTWutYqPNiQ@mail.gmail.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
user-agent: Microsoft-MacOutlook/16.40.20081000
authentication-results: yumaworks.com; dkim=none (message not signed) header.d=none;yumaworks.com; dmarc=none action=none header.from=cisco.com;
x-originating-ip: [136.56.133.70]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 093c952e-63da-448f-614b-08d85b270c19
x-ms-traffictypediagnostic: BYAPR11MB3013:
x-microsoft-antispam-prvs: <BYAPR11MB30132E29DD173B4FE45E9B73C23E0@BYAPR11MB3013.namprd11.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:9508;
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: yA6IRXdEDv6SBVFAK44t5hZuUuo9n5xLXTnjmB23K6GJzekdNtDTTTLLekQRKFJCruAiL+ACLrFZZS2tKGzZtEO89kUTC9E6CEZA71lFU0nl9TV7p8g0naGe2kIwzCYWWVJSGUDW3Wlf+4ZTMX9NA8k3NaYO1/8ZMRBK30+Er1cKnvgGFU8tvycrIkuSCw9nQoyFYUSMA/qY7NkvUgI2vnoPoMADP02VKs/evfJinhYKYUW95kVES/dnR6yDxR0ltUZFfuoy36+tH9Q/j7eQr0FVt/iQh0Q3INMdfjT9MWzG74gVrzkvB5qZTb5O1CLogzkOov20H7vCdQiSbQjN2c19HhLA/vomul4NDPh5X4/sbD1Vjzp57ut4C7df6hErK7/HLk4KtZtht7yKa0x0hg==
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:BYAPR11MB2887.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(396003)(366004)(136003)(39860400002)(346002)(376002)(8936002)(83080400001)(316002)(33656002)(8676002)(186003)(166002)(76116006)(86362001)(2906002)(36756003)(6512007)(5660300002)(26005)(110136005)(66946007)(64756008)(966005)(6506007)(66446008)(71200400001)(66476007)(66556008)(6486002)(53546011)(478600001)(2616005); DIR:OUT; SFP:1101;
x-ms-exchange-antispam-messagedata: Qnm+2NZgS6V0X7T0ivnbK+5b6yJhATvY9G8OIFjjvUqbxWlFk+iKDFahEqYJqayCCPSN6MuikcB0/0ngz/1jfXboiqA5rQxsjgA4vDI17fLYNpWU55JfcKlCW7HpUHQ7WJDPkKsYUfnC+qj/Rajou8BWl30lYfbGAduvarCusAC6r6b9yc295fXIUcIlpjMkNITtQYTmjrqEO9deTq716szCssZEqBpE+C7z6NLDxYimw5hfEZHASa8BzFNdcFj0pC619GLo1f9ATEvkRBUtLkYjLLrPZXXDHnePMOBas5ZEFG1mEEMTCyLGpCHrrgQ0c7cSRkTjepuDsujpphVZZMXKe0c234JMMzH08aBiud3WfooFvRGrm5BFx8oD9UfnkHpvYpk37ARCoA4QHxDyvkUOkSV7YW9KvuWG9KCMlG1VnTeU6t/1NJZqBSyhm7HDpAJoiiD14/cZpYw+oSsv1Ed5g0VVv064H7TTeUsTET9MvwgrN97jpX/ziDTvh2R2fjS3qQ4iIwI79fhAZie2EmjhDKaPWS1lBbuJUmOTAaLFJ4VQp+g4XctE1vLadggVN//+6EgWcj69BVbXbUd34aLposxwhRe/kJdhKVZsT9efnN5uMXQFCw6AlC2kQ93iQKDCTYU42hWazm+ISNmMoA==
x-ms-exchange-transport-forked: True
Content-Type: multipart/alternative; boundary="_000_5DBAC92A2E744CEB92C170C9A983E514ciscocom_"
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: BYAPR11MB2887.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 093c952e-63da-448f-614b-08d85b270c19
X-MS-Exchange-CrossTenant-originalarrivaltime: 17 Sep 2020 16:30:53.5838 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 5ae1af62-9505-4097-a69a-c1553ef7840e
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: 6yRPe0l/iWAPdMBaBW0JD/grcGaGK+rSFjlDlzm5yd+9HNyYHWY4Caty6r4kr322
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BYAPR11MB3013
X-OriginatorOrg: cisco.com
X-Outbound-SMTP-Client: 173.36.7.15, xch-aln-005.cisco.com
X-Outbound-Node: alln-core-5.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/ddifdd6ZC1gIBalPntj1NWxco_I>
Subject: Re: [yang-doctors] Normative Language in YANG descriptions
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 17 Sep 2020 16:31:22 -0000

I’ve done this in the ietf-routing-policy.yang in draft-ietf-rtgwg-policy-model-24

From: Andy Bierman <andy@yumaworks.com>
Date: Thursday, September 17, 2020 at 12:22 PM
To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>, Kent Watsen <kent@watsen.net>, Mahesh Jethanandani <mjethanandani@gmail.com>, YANG Doctors <yang-doctors@ietf.org>, Acee Lindem <acee@cisco.com>
Subject: Re: [yang-doctors] Normative Language in YANG descriptions



On Thu, Sep 17, 2020 at 9:09 AM Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de<mailto:j.schoenwaelder@jacobs-university.de>> wrote:
Quoting RFC 8174 (BCP 14):

   o  These words can be used as defined here, but using them is not
      required.  Specifically, normative text does not require the use
      of these key words.  They are used for clarity and consistency
      when that is what's wanted, but a lot of normative text does not
      use them and is still normative.


The decision criteria for using 2119 keywords is not different for plain text vs. YANG module description-stmts.
I tend to agree with Kent that they should (or is it SHOULD :-) be used in YANG modules.


/js

Andy

On Thu, Sep 17, 2020 at 03:47:38PM +0000, Kent Watsen wrote:
> I use 2119 language in *all* my YANG modules because I want the YANG module to be the most-normative part of the draft (the single source of truth), with the other normative sections in the draft containing little to no duplicative text.  Thus most, if not all, of the semantics are captured in the YANG description statements.
>
> To do this, I put the 2119 boiler template into the YANG module’s top-level description statement, so the module is understandable even in a standalone context, after being stripped from the final RFC.  For instance, see https://tools.ietf.org/html/rfc8572#section-6.3 <https://tools.ietf.org/html/rfc8572#section-6.3>.
>
> Personally, I think all RFCs used to publish YANG modules should be written using 2119 language this way.
>
> Kent
>
>
>
> > On Sep 17, 2020, at 1:05 AM, Mahesh Jethanandani <mjethanandani@gmail.com<mailto:mjethanandani@gmail.com>> wrote:
> >
> > +1.
> >
> >> On Sep 16, 2020, at 4:53 AM, Acee Lindem (acee) <acee=40cisco.com@dmarc.ietf.org<mailto:40cisco.com@dmarc.ietf.org> <mailto:acee<mailto:acee>=40cisco.com@dmarc.ietf.org<mailto:40cisco.com@dmarc.ietf.org>>> wrote:
> >>
> >> All,
> >>
> >> I just received a comment on validation in a description statement for ietf-routing-policy. The comment was more of a question as whether “should” should be “SHOULD”. I looked at our existing published models and we have not been doing this consistently. Perhaps we SHOULD when it is normative validation.
> >>
> >> Thanks,
> >> Acee
> >> _______________________________________________
> >> yang-doctors mailing list
> >> yang-doctors@ietf.org<mailto:yang-doctors@ietf.org> <mailto:yang-doctors@ietf.org<mailto:yang-doctors@ietf.org>>
> >> https://www.ietf.org/mailman/listinfo/yang-doctors <https://www.ietf.org/mailman/listinfo/yang-doctors>
> > Mahesh Jethanandani
> > mjethanandani@gmail.com<mailto:mjethanandani@gmail.com> <mailto:mjethanandani@gmail.com<mailto:mjethanandani@gmail.com>>
> >
> >
> >
> >
> >
> > _______________________________________________
> > yang-doctors mailing list
> > yang-doctors@ietf.org<mailto:yang-doctors@ietf.org>
> > https://www.ietf.org/mailman/listinfo/yang-doctors
>

> _______________________________________________
> yang-doctors mailing list
> yang-doctors@ietf.org<mailto:yang-doctors@ietf.org>
> https://www.ietf.org/mailman/listinfo/yang-doctors


--
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

_______________________________________________
yang-doctors mailing list
yang-doctors@ietf.org<mailto:yang-doctors@ietf.org>
https://www.ietf.org/mailman/listinfo/yang-doctors