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: =?us-ascii?q?9a23=3ABoIi6R/Gx0YZX/9uRHGN82YQeigqvan1NQcJ65?= =?us-ascii?q?0hzqhDabmn44+/YR7E/fs4iljPUM2b8P9Ch+fM+4HYEW0bqdfJq3UeaNpJXh?= =?us-ascii?q?4Bh98RmlkpC8OIIUb6N/XtKSc9GZcKWQ=3D=3D?=
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0DvAAA7fM5d/5BdJa1bAQkaAQEBAQE?= =?us-ascii?q?BAQEBAwEBAQERAQEBAgIBAQEBgX6BS1AFbFggBAsqCoQfg0YDinSCOSV/lwG?= =?us-ascii?q?BQoEQA1QJAQEBDAEBIwoCAQGEQAIXggskOBMCAwsBAQQBAQECAQUEbYULAQE?= =?us-ascii?q?EAiQMhVEBAQEBAxIIAQgRDAEBJRIBCwQCAQgRAwEBAQMCJgICAjAVCAgCBAE?= =?us-ascii?q?NBRkCB4MAAYJGAy4BAgykbwKBOIgRGjV1gTKCfgEBBYUXGIIXAwaBDiiFG4Z?= =?us-ascii?q?6GIF/gREnDBOCFzU+gmICgR0ZARIBARYXgnkyggoijQQgCggiAoI5hWeJIY4?= =?us-ascii?q?ebgqCKocZhSWEe4QUFAeCPodnhDqGcoQ8jkiBQYZ3jk2DAgIEAgQFAg4BAQW?= =?us-ascii?q?BaSKBWHAVOyoBgkFQERSCd4JsgVqJXQcxSgGCcIUUhT90DIEcjieBDQGBDgE?= =?us-ascii?q?B?=
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: =?utf-8?B?QmFsw6F6cyBMZW5neWVs?= <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