Re: [netmod] Yangdoctors last call review of draft-ietf-netmod-yang-instance-file-format-04
"Acee Lindem (acee)" <acee@cisco.com> Fri, 15 November 2019 10:26 UTC
Return-Path: <acee@cisco.com>
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 CFE82120271; Fri, 15 Nov 2019 02:26:10 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -11.165
X-Spam-Level:
X-Spam-Status: No, score=-11.165 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_SBL_CSS=3.335, 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=jEwJiugQ; dkim=pass (1024-bit key) header.d=cisco.onmicrosoft.com header.b=TRb0FWjs
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 UIV6pheL6Tmf; Fri, 15 Nov 2019 02:26:06 -0800 (PST)
Received: from alln-iport-7.cisco.com (alln-iport-7.cisco.com [173.37.142.94]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 156CA12021D; Fri, 15 Nov 2019 02:26:06 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=55414; q=dns/txt; s=iport; t=1573813566; x=1575023166; h=from:to:cc:subject:date:message-id:references: in-reply-to:content-id:content-transfer-encoding: mime-version; bh=jlXzZ9eAMEbe8J+KjwfZEM/jIIa4oTqfPJ/Jf7ezC6c=; b=jEwJiugQD9QfZVKWeXLf9UMQbW4mIHK7kLGNdRmPaRBnpQJy9ZOAve5o J+taqOIlvVoUPAvj+d127GtVtvJ5dIdqharG1+1LuUjx/FLzhPWzsdsVb lIvr8HPbULrwUtFxlEzSFAOIh7J9zNUQo1kIV05Z5kKR4ro82vXG7f/LR 8=;
IronPort-PHdr: 9a23:BoIi6R/Gx0YZX/9uRHGN82YQeigqvan1NQcJ650hzqhDabmn44+/YR7E/fs4iljPUM2b8P9Ch+fM+4HYEW0bqdfJq3UeaNpJXh4Bh98RmlkpC8OIIUb6N/XtKSc9GZcKWQ==
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: A0DvAAA7fM5d/5BdJa1bAQkaAQEBAQEBAQEBAwEBAQERAQEBAgIBAQEBgX6BS1AFbFggBAsqCoQfg0YDinSCOSV/lwGBQoEQA1QJAQEBDAEBIwoCAQGEQAIXggskOBMCAwsBAQQBAQECAQUEbYULAQEEAiQMhVEBAQEBAxIIAQgRDAEBJRIBCwQCAQgRAwEBAQMCJgICAjAVCAgCBAENBRkCB4MAAYJGAy4BAgykbwKBOIgRGjV1gTKCfgEBBYUXGIIXAwaBDiiFG4Z6GIF/gREnDBOCFzU+gmICgR0ZARIBARYXgnkyggoijQQgCggiAoI5hWeJIY4ebgqCKocZhSWEe4QUFAeCPodnhDqGcoQ8jkiBQYZ3jk2DAgIEAgQFAg4BAQWBaSKBWHAVOyoBgkFQERSCd4JsgVqJXQcxSgGCcIUUhT90DIEcjieBDQGBDgEB
X-IronPort-AV: E=Sophos;i="5.68,308,1569283200"; d="scan'208";a="363989989"
Received: from rcdn-core-8.cisco.com ([173.37.93.144]) by alln-iport-7.cisco.com with ESMTP/TLS/DHE-RSA-SEED-SHA; 15 Nov 2019 10:26:04 +0000
Received: from XCH-ALN-010.cisco.com (xch-aln-010.cisco.com [173.36.7.20]) by rcdn-core-8.cisco.com (8.15.2/8.15.2) with ESMTPS id xAFAQ4XM010842 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=FAIL); Fri, 15 Nov 2019 10:26:04 GMT
Received: from xhs-rtp-001.cisco.com (64.101.210.228) by XCH-ALN-010.cisco.com (173.36.7.20) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Fri, 15 Nov 2019 04:26:03 -0600
Received: from xhs-rtp-002.cisco.com (64.101.210.229) by xhs-rtp-001.cisco.com (64.101.210.228) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Fri, 15 Nov 2019 05:26:02 -0500
Received: from NAM02-CY1-obe.outbound.protection.outlook.com (64.101.32.56) by xhs-rtp-002.cisco.com (64.101.210.229) with Microsoft SMTP Server (TLS) id 15.0.1473.3 via Frontend Transport; Fri, 15 Nov 2019 05:26:02 -0500
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=RRvVUK2VdHsMQNl2zroX2clr/3hckoT8jogXRvMrKNjMMF2EsJ1A1qgAPZXKUUC63g0qM3Z8qwRy+nBKEdI1gY2dxofsFXM1RK60uD2XRfG9FpUjfEM+nXxlX+2rqLApyKLxDfnJo0OupBQyCLgQkq+N2dqbelKUOhcAXQlkUwzsM57SeZ7dPFnNGSd5KbTuP1rdocA/oCI5ot0Wqyh/YDJpMJTv5R6Q7CBgoQbcd6bXSvZPnpKwdmyRwaVFEDSQ22DFhX2hwt3S6jhR39CXvhSo7n5t9UFMK66HZ7bnbfm/3aJe0IIHpdFovsQD5lG3yLUzs/+CFLyBIh5WklLcNA==
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=jlXzZ9eAMEbe8J+KjwfZEM/jIIa4oTqfPJ/Jf7ezC6c=; b=H24ATynrbZXRN2F2FebZMW96CxAfW/4alptO3L0nVmO0uqpaxnI/iKfp506SZB8BzslH4EavHTaW7g5BoGFoHWLmKOWBKUONAKCN3hGb92nc1nXmB7IiuyoJj7uu54Cu9ChY9JPzFzkbmitAGsF3Ej5GOPszwU6lL0zodk9/tG3icdqA3x6JPgTC4uxYX5NwyNgtNMQzlqu57eb4MKhAzGhfGuhhuIMoHo1tG3WGi4REyg4icZr01vc0rUjoA5fcfwjfLy/N9LuJwjbwr8FBvbUl016aMqRy18Y+vy4GA7RLD+onaBsOysR1YA/ghke6wdejKuIwyhEpaGPNnv3alA==
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=jlXzZ9eAMEbe8J+KjwfZEM/jIIa4oTqfPJ/Jf7ezC6c=; b=TRb0FWjse8vG0Tws4zYQ1JLlvTL8M59AI+h6WBQ+2wC3NS2criYsRkmcHIgH6KdfYPMOWetoeEMwUDu7d4Y3e1/ptiHLoWiurrTmPDF1w8YHpXfH2V5SMY9nerBLAWbQ21/49WfrzPKspDkvaYEXeMOcDR6u2PEFNEJSTMBkxmM=
Received: from MN2PR11MB4221.namprd11.prod.outlook.com (52.135.38.14) by MN2PR11MB3551.namprd11.prod.outlook.com (20.178.250.140) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2451.23; Fri, 15 Nov 2019 10:26:01 +0000
Received: from MN2PR11MB4221.namprd11.prod.outlook.com ([fe80::218b:2d04:e653:105]) by MN2PR11MB4221.namprd11.prod.outlook.com ([fe80::218b:2d04:e653:105%7]) with mapi id 15.20.2451.027; Fri, 15 Nov 2019 10:26:01 +0000
From: "Acee Lindem (acee)" <acee@cisco.com>
To: Balázs Lengyel <balazs.lengyel@ericsson.com>, "yang-doctors@ietf.org" <yang-doctors@ietf.org>
CC: "draft-ietf-netmod-yang-instance-file-format.all@ietf.org" <draft-ietf-netmod-yang-instance-file-format.all@ietf.org>, "last-call@ietf.org" <last-call@ietf.org>, "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: Yangdoctors last call review of draft-ietf-netmod-yang-instance-file-format-04
Thread-Index: AQHVlL55Fr7iGQ5RjUSt1zPH5CgnyaeLwNcA
Date: Fri, 15 Nov 2019 10:26:01 +0000
Message-ID: <E20E8F07-0334-4325-A120-26CA6243617E@cisco.com>
References: <157244032507.32557.17312231788474200661@ietfa.amsl.com> <AM7PR07MB62149C0B74845516E4832129F0790@AM7PR07MB6214.eurprd07.prod.outlook.com>
In-Reply-To: <AM7PR07MB62149C0B74845516E4832129F0790@AM7PR07MB6214.eurprd07.prod.outlook.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
authentication-results: spf=none (sender IP is ) smtp.mailfrom=acee@cisco.com;
x-originating-ip: [4.7.227.146]
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: 6985c7f1-ff7c-4717-1e2a-08d769b63662
x-ms-traffictypediagnostic: MN2PR11MB3551:
x-microsoft-antispam-prvs: <MN2PR11MB3551636F914676DA1785BAADC2700@MN2PR11MB3551.namprd11.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:8273;
x-forefront-prvs: 02229A4115
x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(979002)(4636009)(39860400002)(366004)(396003)(376002)(346002)(136003)(13464003)(51914003)(189003)(199004)(26005)(6116002)(99286004)(6436002)(6486002)(102836004)(2616005)(25786009)(11346002)(446003)(6246003)(66066001)(476003)(2501003)(8676002)(6306002)(86362001)(6512007)(486006)(81156014)(81166006)(8936002)(4326008)(5660300002)(36756003)(7736002)(6506007)(305945005)(966005)(66574012)(14454004)(76176011)(33656002)(2906002)(186003)(316002)(14444005)(256004)(71200400001)(71190400001)(3846002)(110136005)(76116006)(91956017)(229853002)(66946007)(66476007)(66556008)(64756008)(66446008)(53546011)(478600001)(54906003)(30864003)(959014)(559001)(569006); DIR:OUT; SFP:1101; SCL:1; SRVR:MN2PR11MB3551; H:MN2PR11MB4221.namprd11.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1;
received-spf: None (protection.outlook.com: cisco.com does not designate permitted sender hosts)
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: m8KEwEL+C2jD2KNy7tuvfLQcfGHGNVJ7UyOMlOSb5uxzxGi5XmduOTuzeRGrGI5jaNXDHeNCtSJKTTF6oOfHZnDfULPWfxG0D59esO9ajYQBpWpplpp3AC0kVq+aVYHNpqANOc9FtYLfT+cvuH1CBLZTN5H2puE0ptwx5dN4GuW222k323PoKG5uSwUK0vNhBYuWXEaTEdTIlhSxaxHC5Mtc3dDTS5nKwevQFlOwK9WTHgoq/MjWioAmBXO9X5stokldXpOQ64XCBEkEVRZuKIdgnDwrBx9wizwAXpwEFV33QbmWRjJ3SjFxzhjYSn8c571MWbfLFhaQentvW3xCByeUuSnyNDEvypLP8r7QspwwbmFRz+Ffc8gH63cY4ByjpmVK6jsnysp6SsoDHjiNerC3cSgTWiXgv4nzLo3ewmKnE+RQsq9zegU4oE0OC5kc
x-ms-exchange-transport-forked: True
Content-Type: text/plain; charset="utf-8"
Content-ID: <15AD02C6B4DC4949A1501270F5E34123@namprd11.prod.outlook.com>
Content-Transfer-Encoding: base64
MIME-Version: 1.0
X-MS-Exchange-CrossTenant-Network-Message-Id: 6985c7f1-ff7c-4717-1e2a-08d769b63662
X-MS-Exchange-CrossTenant-originalarrivaltime: 15 Nov 2019 10:26:01.1360 (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: wWMbqbCCaNbgHBtVjr4TgTblnZvb8uJkBF2wrksE5XfN0ZIcCWthUh8IpYj76FHc
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR11MB3551
X-OriginatorOrg: cisco.com
X-Outbound-SMTP-Client: 173.36.7.20, xch-aln-010.cisco.com
X-Outbound-Node: rcdn-core-8.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/PlXPizjzKFE9tKohsQbe_8-7ZuY>
Subject: Re: [netmod] Yangdoctors last call review of draft-ietf-netmod-yang-instance-file-format-04
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.29
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: Fri, 15 Nov 2019 10:26:11 -0000
Hi Balazs, I think this satisfies all my comments. Please upload the -05 version and I will complete the YANG doctors review. Thanks, Acee On 11/6/19, 11:23 AM, "Balázs Lengyel" <balazs.lengyel@ericsson.com> wrote: Hello, Thanks for the comments and the updated file accordingly. See below. Regards Balazs -----Original Message----- From: Acee Lindem via Datatracker <noreply@ietf.org> Sent: 2019. október 30., szerda 13:59 To: yang-doctors@ietf.org Cc: draft-ietf-netmod-yang-instance-file-format.all@ietf.org; last-call@ietf.org; netmod@ietf.org Subject: Yangdoctors last call review of draft-ietf-netmod-yang-instance-file-format-04 Reviewer: Acee Lindem Review result: Ready with Issues Document: draft-ietf-netmod-yang-instance-file-format-04.txt Reviewer: Acee Lindem Review Date: Oct 30st, 2019 Review Type: Working Group Last Call Intended Status: Standards Track Summary: Ready with Issues Modules: "ietf-yang-instance-data@2019-07-04.yang" Tech Summary: The model describes mechanisms and statically specifying instance data (XML or JSON) for YANG models. Use cases are also discussed although not in normative text. The document is relatively straight forward but could benefit from some editorial cleanup. Major Comments: None Minor Comments: 1. The "Security Considerations" in section 8 do not conform to the recommended template in https://trac.ietf.org/trac/ops/wiki/yang-security- guidelines>. The considerations may be completely dependent on the included instance Data Set or some of the information in the model may also be sensitive. However, it needs to be better described. BALAZS: Updated security considerations, tried to make it more detailed. However the template is mostly not applicable to this draft. This draft contains very little own data, most of the instance data is as you sad completely dependent on the included instance Data Set. It is also planned to be accessed as a file, not via Netconf/Restconf. 2. I feel it would be helpful to explicitly state that the both read-only and read-write instance data may be included in the instance data set. BALAZS: OK. Chapter 3. Instance Data File Format will include the following: " Config=true and config=false data MAY be mixed in the instance data file." 3. The document could requires some editorial cleanup. For example, use complete sentenses for principles in section 2.1 and punctuate. Do not begin sentenses with "E.g. ...". BALAZS: Principles reworded. Nits: See diff below. *** draft-ietf-netmod-yang-instance-file-format-04.txt.orig 2019-10-29 16:36:22.000000000 -0400 --- draft-ietf-netmod-yang-instance-file-format-04.txt 2019-10-29 21:40:06.000000000 -0400 *************** *** 20,26 **** running server available. This document specifies a standard file format for YANG instance data (which follows the syntax and semantic from existing YANG models, re-using the same format as the reply to a ! <get> operation/request) and decorates it with metadata. Status of This Memo --- 20,26 ---- running server available. This document specifies a standard file format for YANG instance data (which follows the syntax and semantic from existing YANG models, re-using the same format as the reply to a ! <get> operation/request) and annotates it with metadata. BALAZS: OK Status of This Memo *************** *** 114,127 **** Internet-Draft YANG Instance Data August 2019 ! Instance Data Set: A named set of data items decorated with metadata that can be used as instance data in a YANG data tree. Instance Data File: A file containing an instance data set formatted according to the rules described in this document. ! Content-schema: A set of YANG modules with their revision,suupported ! features and deviations for which the instance data set contains instance data Content defining Yang module(s): YANG module(s) that make up the --- 114,127 ---- Internet-Draft YANG Instance Data August 2019 ! Instance Data Set: A named set of data items annotated with metadata BALAZS: OK that can be used as instance data in a YANG data tree. Instance Data File: A file containing an instance data set formatted according to the rules described in this document. ! Content-schema: A set of YANG modules with their revision, supported BALAZS: OK ! features, and deviations for which the instance data set contains BALAZS: OK instance data Content defining Yang module(s): YANG module(s) that make up the *************** *** 138,145 **** There is a need to document data defined in YANG models when a live server is not available. Data is often needed already at design or implementation time or needed by groups that do not have a live ! running server available. To facilitate this off-line delivery of ! data this document specifies a standard format for YANG instance data sets and YANG instance data files. The following is a list of already implemented and potential use --- 138,145 ---- There is a need to document data defined in YANG models when a live server is not available. Data is often needed already at design or implementation time or needed by groups that do not have a live ! running server available. To facilitate this offline delivery of BALAZS: OK ! data, this document specifies a standard format for YANG instance data BALAZS: OK sets and YANG instance data files. The following is a list of already implemented and potential use *************** *** 153,159 **** UC4 Instance data used as backup ! UC5 Storing the configuration of a device, e.g. for archive or audit purposes UC6 Storing diagnostics data --- 153,159 ---- UC4 Instance data used as backup ! UC5 Storing the configuration of a device, e.g., for archive or audit Purposes BALAZS: OK UC6 Storing diagnostics data *************** *** 186,201 **** The following is a list of the basic principles of the instance data format: ! P1 Two standard formats are based on the XML and the JSON encoding ! P2 Re-use existing formats similar to the response to a <get> operation/request P3 Add metadata about the instance data set (Section 3, Paragraph 9) P4 A YANG instance data set may contain data for many YANG modules ! P5 Instance data may include configuration data, state data or a mix of the two P6 Partial data sets are allowed --- 186,201 ---- The following is a list of the basic principles of the instance data format: ! P1 Two standard formats are based on the XML and JSON encodings BALAZS: OK ! P2 Reuse existing formats similar to the response to a <get> BALAZS: OK operation/request P3 Add metadata about the instance data set (Section 3, Paragraph 9) P4 A YANG instance data set may contain data for many YANG modules ! P5 Instance data may include configuration data, state data, or a mix BALAZS: OK of the two P6 Partial data sets are allowed *************** *** 227,233 **** Two formats are specified based on the XML and JSON YANG encodings. ! Later as other YANG encodings (e.g. CBOR) are defined further instance data formats may be specified. The content-data part SHALL follow the encoding rules defined in --- 227,233 ---- Two formats are specified based on the XML and JSON YANG encodings. ! Later as other YANG encodings (e.g., CBOR) are defined, further BALAZS: OK instance data formats may be specified. The content-data part SHALL follow the encoding rules defined in *************** *** 245,251 **** ignored by users of YANG instance data, allowing it to be used later for other purposes. ! in the XML format implementation specific XML attributes. Unknown attributes MUST be ignored by users of YANG instance data, allowing them to be used later for other purposes. --- 245,251 ---- ignored by users of YANG instance data, allowing it to be used later for other purposes. ! in the XML format implementation specific XML attributes, unknown BALAZS: OK attributes MUST be ignored by users of YANG instance data, allowing them to be used later for other purposes. *************** *** 271,277 **** * instance-data-set-name ['@' revision-date] '.filetype' ! * E.g. acme-router-modules@2018-01-25.xml --- 271,277 ---- * instance-data-set-name ['@' revision-date] '.filetype' ! * E.g., acme-router-modules@2018-01-25.xml BALAZS: OK *************** *** 282,288 **** Internet-Draft YANG Instance Data August 2019 ! If the leaf name is present in the instance data header this MUST be used. Revision-date MUST be set to the latest revision date inside the instance data set. --- 282,288 ---- Internet-Draft YANG Instance Data August 2019 ! If the leaf name is present in the instance data header, this MUST BALAZS: OK be used. Revision-date MUST be set to the latest revision date inside the instance data set. *************** *** 290,301 **** * instance-data-set-name ['@' timestamp] '.filetype' ! * E.g. acme-router-modules@2018-01-25T15_06_34_3+01_00.json ! If the leaf name is present in the instance data header this MUST be used. If the leaf timestamp is present in the instance data ! header this MUST be used; the semicolons and the decimal point if ! present shall be replaced by underscores. The revision date or timestamp is optional. ".filetype" SHALL be ".json" or ".xml" according to the format used. --- 290,301 ---- * instance-data-set-name ['@' timestamp] '.filetype' ! * E.g,. acme-router-modules@2018-01-25T15_06_34_3+01_00.json BALAZS: OK ! If the leaf name is present in the instance data header, this MUST BALAZS: OK be used. If the leaf timestamp is present in the instance data ! header, this MUST be used; the semicolons and the decimal point, if BALAZS: OK ! present shall, be replaced by underscores. BALAZS: OK The revision date or timestamp is optional. ".filetype" SHALL be ".json" or ".xml" according to the format used. *************** *** 315,321 **** 3.1. Specifying the Content Schema ! To properly understand and use an instance data set the user needs to know the content-schema. One of the following methods SHOULD be used: --- 315,321 ---- 3.1. Specifying the Content Schema ! To properly understand and use an instance data set, the user needs to BALAZS: OK know the content-schema. One of the following methods SHOULD be used: *************** *** 342,359 **** already known, or the information is available through external documents. ! Additional methods e.g. a YANG-package based solution may be added later. Note, the specified content-schema only indicates the set of modules that were used to define this YANG instance data set. Sometimes instance data may be used for a server supporting a different YANG ! module set. (e.g. for "UC2 Preloading Data" the instance data set may not be updated every time the YANG modules on the server are updated) Whether the instance data set is usable for a possibly different real-life YANG module set depends on many factors including the ! compatibility between the specified and the real-life YANG module set ! (considering modules, revisions, features, deviations), the scope of the instance data, etc. 3.1.1. Inline Method --- 342,359 ---- already known, or the information is available through external documents. ! Additional methods, e.g., a YANG-package based solution may be added BALAZS: OK later. Note, the specified content-schema only indicates the set of modules that were used to define this YANG instance data set. Sometimes instance data may be used for a server supporting a different YANG ! module set. (e.g., for "UC2 Preloading Data" the instance data set may BALAZS: OK not be updated every time the YANG modules on the server are updated) Whether the instance data set is usable for a possibly different real-life YANG module set depends on many factors including the ! compatibility between the specified and the real-life YANG module set, BALAZS: OK ! considering modules, revisions, features, deviations, the scope of BALAZS: OK the instance data, etc. 3.1.1. Inline Method *************** *** 361,372 **** One or more inline-target-spec elements define YANG module(s) used to specify the content defining YANG modules. ! E.g. ietf-yang-library@2016-06-21.yang The anydata inline-content-schema carries instance data (conforming to the inline-target-spec modules) that actually specifies the content defining YANG modules including revision, supported features, ! deviations and any relevant additional data (e.g. version labels) 3.1.2. Simplified-Inline Method --- 361,372 ---- One or more inline-target-spec elements define YANG module(s) used to specify the content defining YANG modules. ! E.g., ietf-yang-library@2016-06-21.yang BALAZS: OK The anydata inline-content-schema carries instance data (conforming to the inline-target-spec modules) that actually specifies the content defining YANG modules including revision, supported features, ! deviations and any relevant additional data (e.g., version labels) BALAZS: OK 3.1.2. Simplified-Inline Method *************** *** 384,390 **** The referenced instance data file MAY have no content-data if it is used solely for specifying the content-schema. The referenced YANG instance data file might use the INLINE method or might use the URI ! method to reference further instance data file(s). However at the --- 384,390 ---- The referenced instance data file MAY have no content-data if it is used solely for specifying the content-schema. The referenced YANG instance data file might use the INLINE method or might use the URI ! method to reference further instance data file(s). However, at the BALAZS: OK *************** *** 397,416 **** end of this reference chain there MUST be an instance data file using the INLINE method. ! If a referenced instance data file is not available the revision ! data, supported features and deviations for the target YANG modules are unknown. The URI method is advantageous when the user wants to avoid the overhead of specifying the content-schema in each instance data file: ! E.g. In Use Case 6, when the system creates a diagnostic file every minute to document the state of the server. 3.2. Examples The following example is based on "UC1, Documenting Server Capabilities". It provides (a shortened) list of supported YANG ! modules and Netconf capabilities for a server. It uses the inline method to specify the content-schema. <?xml version="1.0" encoding="UTF-8"?> --- 397,416 ---- end of this reference chain there MUST be an instance data file using the INLINE method. ! If a referenced instance data file is not available, the revision BALAZS: OK ! data, supported features, and deviations for the target YANG modules BALAZS: OK are unknown. The URI method is advantageous when the user wants to avoid the overhead of specifying the content-schema in each instance data file: ! E.g., in Use Case 6, when the system creates a diagnostic file every BALAZS: OK minute to document the state of the server. 3.2. Examples The following example is based on "UC1, Documenting Server Capabilities". It provides (a shortened) list of supported YANG ! modules and NETCCONF capabilities for a server. It uses the inline BALAZS: OK method to specify the content-schema. <?xml version="1.0" encoding="UTF-8"?> *************** *** 624,630 **** "schema-uri": "file:///acme-netconf-diagnostics-yanglib.json", "timestamp": "2018-01-25T17:00:38Z", "description": ! "Netconf statistics", "content-data": { "ietf-netconf-monitoring:netconf-state": { "statistics": { --- 624,630 ---- "schema-uri": "file:///acme-netconf-diagnostics-yanglib.json", "timestamp": "2018-01-25T17:00:38Z", "description": ! "NETCONF statistics", BALAZS: OK "content-data": { "ietf-netconf-monitoring:netconf-state": { "statistics": { *************** *** 647,661 **** 4. Data Life cycle ! In UC2 "Preloading default configuration data" the loaded data may be ! changed later e.g. by management operations. In UC6 "Storing ! Diagnostics data" the diagnostics values may change on device every second. ! YANG instance data is a snap-shot of information at a specific point ! of time. If the data changes afterwards this is not represented in ! the instance data set anymore. The valid values can be retrieved in ! run-time via NETCONF/RESTCONF or received e.g. in Yang-Push notifications. Whether the instance data changes and if so, when and how, SHOULD be --- 647,661 ---- 4. Data Life cycle ! In UC2 "Preloading default configuration data", the loaded data may be BALAZS: OK ! changed later, e.g., by management operations. In UC6 "Storing BALAZS: OK ! Diagnostics data", the diagnostics values may change on the device every BALAZS: OK second. ! YANG instance data is a snapshot of information at a specific point BALAZS: OK ! of time. If the data changes afterwards, this is not represented in BALAZS: OK ! the instance data set anymore. The valid values can be retrieved at BALAZS: OK ! run-time via NETCONF/RESTCONF or received, e.g., in YANG-Push BALAZS: OK notifications. Whether the instance data changes and if so, when and how, SHOULD be *************** *** 678,688 **** Instance data sets that are produced as a result of some sort of specification or design effort SHOULD be available without the need ! for a live server e.g. via download from the vendor's website, or in ! any other way product documentation is distributed. Other instance data sets may be read from or produced by the YANG ! server itself e.g. UC6 documenting diagnostic data. 6. Backwards Compatibility --- 678,688 ---- Instance data sets that are produced as a result of some sort of specification or design effort SHOULD be available without the need ! for a live server, e.g., via download from the vendor's website, or in BALAZS: OK ! any other way that product documentation is distributed. BALAZS: OK Other instance data sets may be read from or produced by the YANG ! server itself, e.g., UC6 documenting diagnostic data. BALAZS: OK 6. Backwards Compatibility *************** *** 691,714 **** dependent on the specific use case and the content-schema. For instance data that is the result of a design or specification ! activity some changes that may be good to avoid are listed. YANG uses the concept of managed entities identified by key values; if the connection between the represented entity and the key value is not ! preserved during an update this may lead to problems. o If the key value of a list entry that represents the same managed entity as before is changed, the user may mistakenly identify the list entry as new. o If the meaning of a list entry is changed, but the key values are ! not (e.g. redefining an alarm-type but not changing its alarm- type-id) the change may not be noticed. o If the key value of a previously removed list entry is reused for ! a different entity, the change may be mis-interpreted as reintroducing the previous entity. ! 7. Yang Instance Data Model 7.1. Tree Diagram --- 691,714 ---- dependent on the specific use case and the content-schema. For instance data that is the result of a design or specification ! activity, some changes that may be good to avoid are listed. YANG BALAZS: OK uses the concept of managed entities identified by key values; if the connection between the represented entity and the key value is not ! preserved during an update, this may lead to problems. BALAZS: OK o If the key value of a list entry that represents the same managed entity as before is changed, the user may mistakenly identify the list entry as new. o If the meaning of a list entry is changed, but the key values are ! not (e.g., redefining an alarm-type but not changing its alarm- BALAZS: OK type-id) the change may not be noticed. o If the key value of a previously removed list entry is reused for ! a different entity, the change may be misinterpreted as BALAZS: OK reintroducing the previous entity. ! 7. YANG Instance Data Model 7.1. Tree Diagram *************** *** 812,818 **** sx:structure instance-data-set { description "A data structure to define a format for a ! YANG instance data set.Consists of meta-data about the instance data set and the real content-data."; leaf name { --- 812,818 ---- sx:structure instance-data-set { description "A data structure to define a format for a ! YANG instance data sets. Consists of meta-data about BALAZS: OK the instance data set and the real content-data."; leaf name { *************** *** 851,866 **** min-elements 1; ordered-by user; description ! "Indicates that content defining Yang modules ! are specified inline. Each value MUST be a YANG Module name including the revision-date as defined for YANG file names in RFC7950. ! E.g. ietf-yang-library@2016-06-21.yang The first item is either ietf-yang-library or some other YANG module that contains a list of YANG modules with ! their name, revision-date, supported-features and deviations. As some versions of ietf-yang-library MAY contain different module-sets for different datastores, if --- 851,866 ---- min-elements 1; ordered-by user; description ! "Indicates that content defining YANG modules ! are specified inline. BALAZS: OK Each value MUST be a YANG Module name including the revision-date as defined for YANG file names in RFC7950. ! E.g., ietf-yang-library@2016-06-21.yang BALAZS: OK The first item is either ietf-yang-library or some other YANG module that contains a list of YANG modules with ! their name, revision-date, supported-features, and BALAZS: OK deviations. As some versions of ietf-yang-library MAY contain different module-sets for different datastores, if *************** *** 871,883 **** datastore. Subsequent items MAY specify YANG modules augmenting the ! first module with useful data (e.g. a version label)."; } anydata inline-content-schema { mandatory true; description "Instance data corresponding to the YANG modules specified in the inline-spec nodes defining the set ! of content defining Yang YANG modules for this instance-data-set."; } } --- 871,883 ---- datastore. Subsequent items MAY specify YANG modules augmenting the ! first module with useful data (e.g., a version label)."; BALAZS: OK } anydata inline-content-schema { mandatory true; description "Instance data corresponding to the YANG modules specified in the inline-spec nodes defining the set ! of content defining YANG modules for this BALAZS: OK instance-data-set."; } } *************** *** 888,894 **** description "A reference to another YANG instance data file. This instance data file will use the same set of target ! YANG modules, revisions, supported features and deviations as the referenced YANG instance data file."; --- 888,894 ---- description "A reference to another YANG instance data file. This instance data file will use the same set of target ! YANG modules, revisions, supported features, and deviations as the referenced YANG instance data file."; BALAZS: OK *************** *** 923,932 **** leaf datastore { type ds:datastore-ref; description "The identity of the datastore with which the ! instance data set is associated e.g. the datastore from ! where the data was read or the datastore where the data could be loaded or the datastore which is being documented. ! If a single specific datastore can not be specified, the leaf MUST be absent. If this leaf is absent, then the datastore to which the --- 923,932 ---- leaf datastore { type ds:datastore-ref; description "The identity of the datastore with which the ! instance data set is associated, e.g., the datastore from BALAZS: OK ! where the data was read or the datastore from which the data BALAZS: the second part really should mean "a data store where I can push the data into". So I changed it to " or the datastore into which the data may be loaded" could be loaded or the datastore which is being documented. ! If a single specific datastore cannot be specified, the leaf MUST be absent. BALAZS: OK If this leaf is absent, then the datastore to which the *************** *** 1222,1228 **** A server has a number of server-capabilities that are defined in YANG modules and can be retrieved from the server using protocols like ! NETCONF or RESTCONF. server capabilities include --- 1222,1228 ---- A server has a number of server-capabilities that are defined in YANG modules and can be retrieved from the server using protocols like ! NETCONF or RESTCONF. Server capabilities include: BALAZS: OK *************** *** 1235,1246 **** o data defined in ietf-yang-library: YANG modules, submodules, ! features, deviations, schema-mounts, datastores supported ([I-D.ietf-netconf-rfc7895bis]) o alarms supported ([I-D.ietf-ccamp-alarm-module]) ! o data nodes, subtrees that support or do not support on-change notifications ([I-D.ietf-netconf-yang-push]) o netconf-capabilities in ietf-netconf-monitoring --- 1235,1246 ---- o data defined in ietf-yang-library: YANG modules, submodules, ! features, deviations, schema-mounts, and datastores supported BALAZS: OK ([I-D.ietf-netconf-rfc7895bis]) o alarms supported ([I-D.ietf-ccamp-alarm-module]) ! o data nodes and subtrees that support or do not support on-change BALAZS: OK notifications ([I-D.ietf-netconf-yang-push]) o netconf-capabilities in ietf-netconf-monitoring *************** *** 1248,1280 **** While it is good practice to allow a client to query these capabilities from the live server, that is often not possible. ! Often when a network node is released an associated NMS (network management system) is also released with it. The NMS depends on the ! capabilities of the server. During NMS implementation information about server capabilities is needed. If the information is not ! available early in some off-line document, but only as instance data from the live network node, the NMS implementation will be delayed, ! because it has to wait for the network node to be ready. Also assuming that all NMS implementors will have a correctly configured ! network node available to retrieve data from, is a very expensive proposition. (An NMS may handle dozens of node types.) Network operators often build their own home-grown NMS systems that ! needs to be integrated with a vendor's network node. The operator needs to know the network node's server capabilities in order to do ! this. Moreover the network operator's decision to buy a vendor's product may even be influenced by the network node's OAM feature set ! documented as the Server's capabilities. Beside NMS implementors, system integrators and many others also need the same information early. Examples could be model driven testing, generating documentation, etc. Most server-capabilities are relatively stable and change only during ! upgrade or due to licensing or addition or removal of HW. They are ! usually defined by a vendor at design time, before the product is ! released. It feasible and advantageous to define/document them early ! e.g. in a YANG instance data File. It is anticipated that a separate IETF document will define in detail how and which set of server capabilities should be documented. --- 1248,1280 ---- While it is good practice to allow a client to query these capabilities from the live server, that is often not possible. ! Often when a network node is released, an associated NMS (network BALAZS: OK management system) is also released with it. The NMS depends on the ! capabilities of the server. During NMS implementation, information BALAZS: OK about server capabilities is needed. If the information is not ! available early in some offline document, but only as instance data BALAZS: OK from the live network node, the NMS implementation will be delayed, ! because it has to wait until the network node is ready. Also BALAZS: OK assuming that all NMS implementors will have a correctly configured ! network nodes from whic data is to be retrieved, is a very expensive BALAZS: OK proposition. (An NMS may handle dozens of node types.) Network operators often build their own home-grown NMS systems that ! need to be integrated with a vendor's network node. The operator BALAZS: OK needs to know the network node's server capabilities in order to do ! this. Moreover, the network operator's decision to buy a vendor's BALAZS: OK product may even be influenced by the network node's OAM feature set ! documented as the server's capabilities. BALAZS: OK Beside NMS implementors, system integrators and many others also need the same information early. Examples could be model driven testing, generating documentation, etc. Most server-capabilities are relatively stable and change only during ! upgrade or due to licensing or the addition or removal of hardware. They ! are usually defined by a vendor at design time, before the product is ! released. It feasible and advantageous to define/document them early, ! e.g., in a YANG instance data File. BALAZS: OK It is anticipated that a separate IETF document will define in detail how and which set of server capabilities should be documented. *************** *** 1293,1310 **** C.1.2. Use Case 2: Preloading Data There are parts of the configuration that must be fully configurable ! by the operator, however for which often a simple default ! configuration will be sufficient. One example is access control groups/roles and related rules. While ! a sophisticated operator may define dozens of different groups often a basic (read-only operator, read-write system administrator, security-administrator) triplet will be enough. Vendors will often provide such default configuration data to make device configuration easier for an operator. ! Defining Access control data is a complex task. To help the device ! vendor pre-defines a set of default groups (/nacm:nacm/groups) and rules for these groups to access specific parts of common models (/nacm:nacm/rule-list/rule). --- 1293,1310 ---- C.1.2. Use Case 2: Preloading Data There are parts of the configuration that must be fully configurable ! by the operator. However, often a simple default configuration will ! be sufficient. BALAZS: OK One example is access control groups/roles and related rules. While ! a sophisticated operator may define dozens of different groups, often a basic (read-only operator, read-write system administrator, security-administrator) triplet will be enough. Vendors will often provide such default configuration data to make device configuration easier for an operator. BALAZS: OK ! Defining access control data is a complex task. To help, the device ! vendor predefines a set of default groups (/nacm:nacm/groups) and rules for these groups to access specific parts of common models (/nacm:nacm/rule-list/rule). BALAZS: OK *************** *** 1315,1330 **** Nearly every server has a factory default configuration. If the system is really badly misconfigured or if the current configuration ! is to be abandoned the system can be reset to this default. ! In Netconf the <delete-config> operation can already be used to reset the startup datastore. There are ongoing efforts to introduce a new, more generic reset-datastore operation for the same purpose ! [I-D.wu-netconf-restconf-factory-restore] The operator currently has no way to know what the default ! configuration actually contains. YANG instance data can be used to ! document the factory default configuration. Authors' Addresses --- 1315,1331 ---- Nearly every server has a factory default configuration. If the system is really badly misconfigured or if the current configuration ! is to be abandoned the, system can be reset to the default factory ! configuration. BALAZS: OK ! In NETCONF, the <delete-config> operation can already be used to reset the startup datastore. There are ongoing efforts to introduce a new, more generic reset-datastore operation for the same purpose ! [I-D.wu-netconf-restconf-factory-restore]. BALAZS: OK, but the draft was renamed so that's updated too. The operator currently has no way to know what the default ! configuration actually contains. YANG instance data can also be used ! to document the factory default configuration. BALAZS: OK Authors' Addresses
- [netmod] Yangdoctors last call review of draft-ie… Acee Lindem via Datatracker
- Re: [netmod] Yangdoctors last call review of draf… Balázs Lengyel
- Re: [netmod] Yangdoctors last call review of draf… Acee Lindem (acee)
- Re: [netmod] [Last-Call] Yangdoctors last call re… Kent Watsen