Re: [netmod] kw review of draft-ietf-netmod-yang-instance-file-format-02
Balázs Lengyel <balazs.lengyel@ericsson.com> Mon, 25 March 2019 21:52 UTC
Return-Path: <balazs.lengyel@ericsson.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 90BE3120100 for <netmod@ietfa.amsl.com>; Mon, 25 Mar 2019 14:52:14 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: 3.036
X-Spam-Level: ***
X-Spam-Status: No, score=3.036 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FROM_EXCESS_BASE64=0.979, HTML_MESSAGE=0.001, MIME_HTML_ONLY=0.723, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_SBL_CSS=3.335, SPF_PASS=-0.001] autolearn=no autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=ericsson.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id emfQA9fX1oXq for <netmod@ietfa.amsl.com>; Mon, 25 Mar 2019 14:52:11 -0700 (PDT)
Received: from EUR04-VI1-obe.outbound.protection.outlook.com (mail-eopbgr80083.outbound.protection.outlook.com [40.107.8.83]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id E13AB1200F8 for <netmod@ietf.org>; Mon, 25 Mar 2019 14:52:10 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericsson.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=pb36/m05A6s313QhI/YUMp485E1joITnPFUf0g7fYco=; b=Wcs2UITMOoYp+jQn8t/qPQiJWNp7lSgPt6RgXVigNO1aB6PiKGZbl0PbUnCIO+/28UNdLDh6XT1Upha0ld3T+ufbaGGx1agVWp4D+AqMNKnBnxIuU5xj5ruYqakRhjNa/c56Ex1z7WuxwnNGi73uSrtj2ac0UXcahu6wq+9emDM=
Received: from AM6PR07MB3847.eurprd07.prod.outlook.com (52.134.115.144) by AM6PR07MB5989.eurprd07.prod.outlook.com (20.178.94.214) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1750.13; Mon, 25 Mar 2019 21:52:07 +0000
Received: from AM6PR07MB3847.eurprd07.prod.outlook.com ([fe80::39a5:6b6d:a86f:721c]) by AM6PR07MB3847.eurprd07.prod.outlook.com ([fe80::39a5:6b6d:a86f:721c%2]) with mapi id 15.20.1730.013; Mon, 25 Mar 2019 21:52:07 +0000
From: Balázs Lengyel <balazs.lengyel@ericsson.com>
To: Kent Watsen <kent@watsen.net>, "netmod@ietf.org" <netmod@ietf.org>
Thread-Topic: [netmod] kw review of draft-ietf-netmod-yang-instance-file-format-02
Thread-Index: AQHU41T9cAp4skHIuUKo+OEAvF9g/w==
Date: Mon, 25 Mar 2019 21:52:07 +0000
Message-ID: <c18c0b21-2a41-305d-6462-6169ea44cd3d@ericsson.com>
References: <01000169b3a90fd0-04979928-b059-43aa-81b3-fa40acb5be00-000000@email.amazonses.com>
In-Reply-To: <01000169b3a90fd0-04979928-b059-43aa-81b3-fa40acb5be00-000000@email.amazonses.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach: yes
X-MS-TNEF-Correlator:
x-originating-ip: [192.176.1.93]
user-agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:60.0) Gecko/20100101 Thunderbird/60.6.0
x-clientproxiedby: AM6PR10CA0046.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:80::23) To AM6PR07MB3847.eurprd07.prod.outlook.com (2603:10a6:209:31::16)
authentication-results: spf=none (sender IP is ) smtp.mailfrom=balazs.lengyel@ericsson.com;
x-ms-exchange-messagesentrepresentingtype: 1
x-ms-publictraffictype: Email
x-ms-office365-filtering-correlation-id: ccc1e446-3f3a-440f-4baf-08d6b16c2010
x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(5600127)(711020)(4605104)(2017052603328)(7153060)(49563074)(7193020); SRVR:AM6PR07MB5989;
x-ms-traffictypediagnostic: AM6PR07MB5989:
x-microsoft-antispam-prvs: <AM6PR07MB5989299D9AA576E30BAE5968F05E0@AM6PR07MB5989.eurprd07.prod.outlook.com>
x-forefront-prvs: 0987ACA2E2
x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(39860400002)(136003)(396003)(346002)(376002)(366004)(189003)(199004)(51914003)(52116002)(6486002)(6246003)(6436002)(6506007)(106356001)(478600001)(14444005)(76176011)(229853002)(105586002)(316002)(966005)(2501003)(65826007)(31696002)(65806001)(256004)(606006)(110136005)(65956001)(5660300002)(486006)(86362001)(64126003)(66066001)(53936002)(186003)(99286004)(7736002)(236005)(71190400001)(85182001)(6512007)(31686004)(6306002)(54896002)(446003)(99936001)(58126008)(68736007)(2906002)(476003)(26005)(71200400001)(2616005)(25786009)(85202003)(6116002)(3846002)(11346002)(386003)(36756003)(14454004)(102836004)(97736004)(8676002)(8936002)(81156014)(81166006); DIR:OUT; SFP:1101; SCL:1; SRVR:AM6PR07MB5989; H:AM6PR07MB3847.eurprd07.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; MX:1; A:1;
received-spf: None (protection.outlook.com: ericsson.com does not designate permitted sender hosts)
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam-message-info: fplk1w1MMXY0C8qhiXDHLXfz8qK/y2z3sv2Rz/OLhw6wkt0LCuvzc659trK4Sv04o2HkHkKo3CGvGrBoDYGHLRFnSEj74fyMXgJ/TlgOh1SvaDFJlKwKUjYs5l0ZFJUHICfzu+63tErPbOkUNdncsttASmrmL/yD7koaCfmEyO3G6gJRPYlWCqotrQr/HrLsJiYCV3eorB/OsSYnkUGauCz2sUADbWXaneymmmtn3OoNILMK5bLgsxruoJXRQmGpf2AF5E8ArcXEBkun2Sk9xDR67lUYm0UvpwXkjhDWWUwUuJx180waKj1UWjPp8RptAzf+umyxW3Ty0DaKOASdwq/6RYOg/KdYV8vmH5YBALKtL2XB7pkbSmHKki4TmVmVnjP759wHQSAMn2Y/OZbvUETP77JXzHr/hcmz02WE/74=
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg="sha-256"; boundary="------------ms020407040304060702050402"
MIME-Version: 1.0
X-OriginatorOrg: ericsson.com
X-MS-Exchange-CrossTenant-Network-Message-Id: ccc1e446-3f3a-440f-4baf-08d6b16c2010
X-MS-Exchange-CrossTenant-originalarrivaltime: 25 Mar 2019 21:52:07.5309 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 92e84ceb-fbfd-47ab-be52-080c6b87953f
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM6PR07MB5989
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/c7GRupuygjCC71DYXnrxZGi4M7Q>
Subject: Re: [netmod] kw review of draft-ietf-netmod-yang-instance-file-format-02
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: Mon, 25 Mar 2019 21:52:15 -0000
Thanks for the comments, see below. Balazs
BALAZS: Restconf does have a get method. I thought I could refer to it as a get request.
The Abstract says “re-using the same format as the reply to a <get> operation/request”. At first, I was going to suggest replacing <get> with <get-data>, but I question if this is correct since the draft supports JSON, which neither NETCONF RPC is able to return.
BALAZS: https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-1" rel="nofollow">https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-1 second definition is instance data set
The Terminology section is missing an entry for “instance data set”.
BALAZS: https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-3" rel="nofollow">https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-3 paragraph starting with "Metadata, information about the data set itself SHALL be included ..." explains it. Shall I add a cross-reference?
I don’t understand what P3 means. Add info text to draft.
BALAZS: The relationship is 1-to-1. You don't know how often I got the question: can I put multiple YANG modules into a file?
Re: P4, if file == 1 “set”, then the distinction becomes unclear (see earlier comment about missing “set” term). I understand that it’s intended to mean instance data for a set of modules but, if there’s a 1:1 relationship between file and set, then just pick one term for the draft.
Others commented, that instance data sets may be used without a file e.g. transfered on the wire e.g. as part of some IPC mechanism, so separating the set from the file seems like a good idea.
BALAZS: Explained in https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-3" rel="nofollow">https://tools.ietf.org/html/draft-ietf-netmod-yang-instance-file-format-02#section-3
I don’t understand what P7 means. Add more text to draft.
Instance data files MAY contain partial data sets. This means mandatory, min-elements or require-instance=true constrains MAY be violated. So if you have a module with 2 mandatory subtrees, you are free to specify data only for one of them.
BALAZS: See separate mail.
Section 3 says this about Content data: “It MAY include entity-tags and timestamps as defined in [https://tools.ietf.org/html/rfc8040" title='"RESTCONF Protocol"' rel="nofollow">RFC8040]”. How is this possible? RFC 8040 only returns such data in HTTP headers; there’s no defined encoding for putting the data into instance data.
BALAZS: yes, and I will update the text.
Section 3 also says “It MAY include an explicit tag for default values as defined in
[https://tools.ietf.org/html/rfc6243" title='"With-defaults Capability for NETCONF"' rel="nofollow">RFC6243] and [https://tools.ietf.org/html/rfc8040" title='"RESTCONF Protocol"' rel="nofollow">RFC8040]”. Do you mean, the “default” attribute defined in Section 6 in RFC 6243 and Section 4.8.9 in RFC 8040? The text should be more explicit.
BALAZS: OK
Section 3 also contains paragraphs beginning with: “It MAY include implementation specific metadata.” and “It MAY include implementation specific XML attributes.” I think these two paragraphs should be merged and a sentence added noting how metadata is encoded for JSON and XML.
BALAZS: OKs/A single instance data set/An instance data set/ (since already there is only one)
BALAZS:
Section 3 says: “Instance data files MAY contain partial data sets. This means mandatory, min-elements or require-instance=true constrains MAY be violated.” Why? This means validations may fail.
E.g. If you want to document the module set a server supports, you may omit the namespace. THe name/revision clearly identifies each YAM. While the namespace is mandatory in the module it is not needed to document the module set.
E.g. if you want interface statistics as diagnostics data, it may be enough to document the counters, but not the if-index.
E.g. Configuration to be preloaded may be
provided partially by a file, and partially by the system
itself, or in more additional files.
BALAZS: In the previous version I used that kind of definition. However Jurgen and Rob W. objected strongly against defining the returned data using the get-data/get.
Generally, I feel that the part of Section 3 describing the content should be replaced with a statement that any valid response for <get-data> or GET on a top-level resource is okay. If this is not the case, then the draft should still start with this statement and them list out any exceptions.
We might also have partial-data set, we might have a mix of config and state data, which might not be valid get-data replies.
BALAZS: Sorry, I am missing something. Where do you see the metadata node in the module? Or which module do you mean?
“Metadata” is a general term, please use another term in Section 3, or spell out what is intended. BTW, there isn’t a node in the YANG module called “metadata”, leading the extra confusion.
Metadata means data about the data. IMHO this is exactly the case for the data listed in section 3. It is data about the content-data.
What other term would you prefer?
BALAZS: Sorry, I will add it.
Where is the tree diagram? All drafts defining YANG modules should include a YANG tree diagram for each module.
BALAZS: I will reduce duplication, however IMHO
Actually, reverting on my comment above, I recommend replacing Section 3 with the familiar 3-tuple: tree-diagram, example, YANG module. In particular, I would delete all the text that can be described (and better at that) by the YANG module. This eliminates duplication of content, which is both less to read and eliminates possibly conflicting information.
- some overview text is useful,
- text about file-name, single-set in a file, json/xml encoding etc. should not be in the module
- the target pointer needs some explanation, better kept in the text, then in the module
Stopping my review before section 3.1.
Kent // contributor
_______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod" rel="nofollow">https://www.ietf.org/mailman/listinfo/netmod
-- Balazs Lengyel Ericsson Hungary Ltd. Senior Specialist Mobile: +36-70-330-7909 email: Balazs.Lengyel@ericsson.com
- [netmod] kw review of draft-ietf-netmod-yang-inst… Kent Watsen
- Re: [netmod] kw review of draft-ietf-netmod-yang-… Balázs Lengyel
- Re: [netmod] kw review of draft-ietf-netmod-yang-… Balázs Lengyel