Re: [yang-doctors] Use of identityref and enumerations (was RE: [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-layer0-types-03)

Ladislav Lhotka <lhotka@nic.cz> Wed, 29 January 2020 12:51 UTC

Return-Path: <lhotka@nic.cz>
X-Original-To: yang-doctors@ietfa.amsl.com
Delivered-To: yang-doctors@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 90C67120108; Wed, 29 Jan 2020 04:51:30 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.897
X-Spam-Level:
X-Spam-Status: No, score=-1.897 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_NONE=0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
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 rwKQQkz4gMZQ; Wed, 29 Jan 2020 04:51:26 -0800 (PST)
Received: from trail.lhotka.name (trail.lhotka.name [77.48.224.143]) by ietfa.amsl.com (Postfix) with ESMTP id D6E02120088; Wed, 29 Jan 2020 04:51:25 -0800 (PST)
Received: by trail.lhotka.name (Postfix, from userid 109) id F00C2861C07; Wed, 29 Jan 2020 13:54:10 +0100 (CET)
Received: from localhost (nat-1.nic.cz [217.31.205.1]) by trail.lhotka.name (Postfix) with ESMTPSA id A8DB08601A5; Wed, 29 Jan 2020 13:54:02 +0100 (CET)
From: Ladislav Lhotka <lhotka@nic.cz>
To: Italo Busi <Italo.Busi@huawei.com>, "Rob Wilton \(rwilton\)" <rwilton@cisco.com>, Zhenghaomian <zhenghaomian@huawei.com>, Aihua Guo <aihuaguo@futurewei.com>, "yang-doctors\@ietf.org" <yang-doctors@ietf.org>
Cc: "last-call\@ietf.org" <last-call@ietf.org>, "draft-ietf-ccamp-layer0-types.all\@ietf.org" <draft-ietf-ccamp-layer0-types.all@ietf.org>, "ccamp\@ietf.org" <ccamp@ietf.org>
In-Reply-To: <bbeb60bee9094f22bce77e440ee8f631@huawei.com>
References: <bbeb60bee9094f22bce77e440ee8f631@huawei.com>
Date: Wed, 29 Jan 2020 13:51:15 +0100
Message-ID: <871rrih1do.fsf@nic.cz>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://mailarchive.ietf.org/arch/msg/yang-doctors/ZyDbgpXF2Wr3y9Az-iT5dLnCXlw>
Subject: Re: [yang-doctors] Use of identityref and enumerations (was RE: [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-layer0-types-03)
X-BeenThere: yang-doctors@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Email list of the yang-doctors directorate <yang-doctors.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/yang-doctors/>
List-Post: <mailto:yang-doctors@ietf.org>
List-Help: <mailto:yang-doctors-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/yang-doctors>, <mailto:yang-doctors-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 29 Jan 2020 12:51:31 -0000

Italo Busi <Italo.Busi@huawei.com> writes:

> Looking at some YANG doctor review comments, I have the feeling that there is some debate about whether we should use identityref or enumeration types, which requires some broader discussion to understand which guidelines we can follow since it is impacting multiple YANG models we are working on
>
> The key question is about future extensibility.
>
> I have understood that it is possible to extend an enumeration after the data plane standards are updated by revising the YANG model. Therefore possible data plane standard extensions are not a criteria for preferring identities to enumeration.
>
> However, there are some cases where vendor-private extensions are possible.
>
> For technical and political reasons, I would prefer not to add vendor-private values to a standard enumeration especially when dealing with data plane standards not owned by IETF.
>
> I have some concerns with using "deviate replace" for an enumeration since these are more extensions than deviations. Having vendor-private identities extending the standard ones seems a more natural choice to describe an extension and to allow the client understanding that the server supports such an extension.
>
> Moreover, even if two vendors supports similar extensions, there is no guaranteed of interoperability between them. The two vendors can define their own identities within their own namespace so the clients will not be confused.
>
> Therefore, my suggestion is that we should use identities when we think it is possible to have vendor-private extensions

Yes, identities are necessary where distributed extensibility is needed. Enumerations have to be extended in a coordinated fashion, usually by some central authority.

Lada

>
> Just my 2 cents
>
> Italo
>
>> -----Original Message-----
>> From: Rob Wilton (rwilton) [mailto:rwilton@cisco.com]
>> Sent: martedì 21 gennaio 2020 14:35
>> To: Zhenghaomian <zhenghaomian@huawei.com>om>; Aihua Guo
>> <aihuaguo@futurewei.com>om>; yang-doctors@ietf.org
>> Cc: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> ccamp@ietf.org
>> Subject: Re: [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-layer0-
>> types-03
>> 
>> Hi Haomian, Aihua,
>> 
>> For "layer0-bandwidth-type" I think that identities are okay.  It seems quite
>> plausible that there could be augmentations of other types here.  I do wonder
>> whether this is really "layer0-bandwidth-type" or should it be something like
>> "layer0-signal-type"?  E.g. I was just looking at the Wikipedia entry for "Optical
>> Transport Network" and it refers to these as signals rather than bandwidths:
>> https://en.wikipedia.org/wiki/Optical_Transport_Network.
>> 
>> For slot-width and channel-spacing, I think that enumerations would be better
>> than identities.  I.e. if smaller channels are required then I think that it would
>> be better to update this base types YANG module, rather than potentially
>> define them in other YANG modules.
>> 
>> If you concern is about vendors needing smaller channels then there are few
>> options to mitigate:
>> (i) define the smaller slots in the enumeration now (if you know they are
>> coming).
>> (ii) vendors can "deviate replace" on the type of the leafs, e.g. to an
>> enumeration with extra values, or a union of an enumeration and a numerical
>> value.
>> 
>> Thanks,
>> Rob
>> 
>> 
>> > -----Original Message-----
>> > From: Zhenghaomian <zhenghaomian@huawei.com>
>> > Sent: 17 January 2020 12:33
>> > To: Aihua Guo <aihuaguo@futurewei.com>om>; Rob Wilton (rwilton)
>> > <rwilton@cisco.com>om>; yang-doctors@ietf.org
>> > Cc: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> > ccamp@ietf.org
>> > Subject: 答复: Yangdoctors last call review of draft-ietf-ccamp-layer0-
>> > types-03
>> >
>> > Hi, Robert, Aihua,
>> >
>> > Thank you for the feedback, please see inline with [Authors2], we are
>> > getting closer:)
>> >
>> > Best wishes,
>> > Haomian
>> >
>> >
>> > -----邮件原件-----
>> > 发件人: Aihua Guo [mailto:aihuaguo@futurewei.com]
>> > 发送时间: 2020年1月17日 4:07
>> > 收件人: Rob Wilton (rwilton) <rwilton@cisco.com>om>; Zhenghaomian
>> > <zhenghaomian@huawei.com>om>; yang-doctors@ietf.org
>> > 抄送: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> > ccamp@ietf.org
>> > 主题: RE: Yangdoctors last call review of
>> > draft-ietf-ccamp-layer0-types-03
>> >
>> > Hi Rob, Haomian,
>> >
>> > Re: using (floating point) values in a leaf vs. using identityref for
>> > optical bandwidth, spacing, slot-width etc, I'd lean towards using the
>> > identityref. Two main reasons from my point of view:
>> >
>> > a) in optical layer, the value of bandwidth, slot width, channel
>> > spacing etc. are fixed and discrete, and is always determined by the
>> > technologies used underneath, e.g. FEC or modulation format. Those
>> > values are frequently compared/checked by the program. If using
>> > floating points the value comparison is not definitive, which may make
>> > it difficult for the program logic to handle. No such issue if using
>> > identityref. I'd prefer to avoid encoding those fixed values as floating points.
>> >
>> > b) Optical technologies are evolving and new definitions such as new
>> > channel spacing or slot width would mandate changes to be made in the
>> > original model if using the numerical value leaf nodes. It may also
>> > cause backward compatibility issues. With identityref one creates new
>> > definitions in a new and augmented model, rather than making changes
>> > over the original model. YANG validation on the client side can filter
>> > out the new values automatically if it detects that the new values are
>> > not supported by the server (because the augmented model is not
>> implemented).
>> >
>> > Thanks,
>> > Aihua
>> >
>> > -----Original Message-----
>> > From: Rob Wilton (rwilton) <rwilton@cisco.com>
>> > Sent: Thursday, January 16, 2020 5:08 AM
>> > To: Zhenghaomian <zhenghaomian@huawei.com>om>; yang-doctors@ietf.org
>> > Cc: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> > ccamp@ietf.org
>> > Subject: RE: Yangdoctors last call review of draft-ietf-ccamp-layer0-
>> > types-03
>> >
>> > Hi Haomian,
>> >
>> > Sorry, I had missed your email over Christmas.  Replying back to the
>> > original email to capture the other aliases.
>> >
>> > Please see inline ...
>> >
>> >
>> >
>> > > -----Original Message-----
>> > > From: last-call <last-call-bounces@ietf.org> On Behalf Of
>> > > Zhenghaomian
>> > > Sent: 25 December 2019 08:20
>> > > To: Rob Wilton (rwilton) <rwilton@cisco.com>om>; yang-doctors@ietf.org
>> > > Cc: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> > > ccamp@ietf.org
>> > > Subject: Re: [Last-Call] Yangdoctors last call review of
>> > > draft-ietf-ccamp-
>> > > layer0-types-03
>> > >
>> > > Hi, Robert,
>> > >
>> > > Again, thank you very much for your detailed review and comments.
>> > > The authors had a few iterations of discussions and give the update
>> > > for this document as follow.
>> > >
>> > > Model update can be found as the pull request:
>> > > https://nam03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgi
>> > > th
>> > > ub.com%2Fietf-
>> &amp;data=02%7C01%7Caihuaguo%40futurewei.com%7C93555aa
>> > > 03
>> > >
>> 041406a21ec08d79a6bf5dc%7C0fee8ff2a3b240189c753a1d5591fedc%7C1%7
>> C1%7
>> > > C6
>> > >
>> 37147660797808234&amp;sdata=JPWe96JXR556EQk%2FSsaCgVf3QuK%2FGl
>> 0ha1eQ
>> > > qS
>> > > NEfUU%3D&amp;reserved=0
>> > > ccamp-wg/draft-ietf-ccamp-layer0-types/pull/3 ; you (and other
>> > > experts) are welcome to follow up in this thread.
>> > > An updated draft have been locally created, with the diff files
>> > > attached; For detailed comments response/discussion, please see
>> > > inline starting with '[Authors]';
>> > >
>> > > Please help review if the comments are addressed, any
>> > > discussion/calls are welcome and can be arranged by chairs, thank you.
>> > >
>> > > Best wishes,
>> > > Haomian (on behalf of all authors & contributors)
>> > >
>> > > -----邮件原件-----
>> > > 发件人: Robert Wilton via Datatracker [mailto:noreply@ietf.org]
>> > > 发送时间: 2019年12月14日 0:50
>> > > 收件人: yang-doctors@ietf.org
>> > > 抄送: last-call@ietf.org; draft-ietf-ccamp-layer0-types.all@ietf.org;
>> > > ccamp@ietf.org
>> > > 主题: Yangdoctors last call review of draft-ietf-ccamp-layer0-types-03
>> > >
>> > > Reviewer: Robert Wilton
>> > > Review result: Almost Ready
>> > >
>> > > Comments on the document:
>> > >
>> > > 1) I would delete the "overview" paragraph at the top of section 2,
>> > > and just promote section 2.1 as section 2.
>> > > [Authors] done in -04.
>> > >
>> > > 2) 2.1. Layer 0 Types Module Contents:
>> > >
>> > > The descriptions are good, but I would suggest formatting these as a
>> > > table, or more tightly link the definition to it's description.
>> > >
>> > > E.g.
>> > >
>> > > "Operational-mode: A type that represents operational mode as
>> > > defined in [ITU-Tg6982]."
>> > >
>> > > Instead of:
>> > >
>> > > "Operational-mode:
>> > >
>> > > A type that represents operational mode as defined in [ITU-Tg6982]."
>> > > [Authors] Discussion needed: we need to be careful on changing this,
>> > > as currently the layer0-types and layer1-types are in consistent
>> > > format. Need to change in both sides or don't change any of them.
>> > [RW]
>> > I agree that they should be consistent between the two drafts.  My aim
>> > was to make them as readable as possible, but this is purely a
>> > stylistic thing.
>> > [Authors2] Agree on only formatting that technical. Let's keep as it
>> > is, and check again if necessary.
>> >
>> > >
>> > > 3) I would define the module as YANG version "1.1" (because the
>> > > language behaviour is generally better specified) and then reference
>> > > only RFC 7950 in the introduction.
>> > > [Authors] done in -04.
>> > >
>> > > 4) typo in the Security Considerations "layer0 => layer 0", and also
>> > > in the title of section 3.
>> > > [Authors] done in -04.
>> > >
>> > > 5) I have suggested changing the module prefix to "l0-types" rather
>> > > than layer2-types.  If you make this change then the IANA
>> > > considerations would need to be updated, along with section 1.2.
>> > > [Authors] done in -04.
>> > >
>> > > Comments on the YANG module:
>> > >
>> > > 1) I would suggest changing the YANG prefix to "l0-types" to help
>> > > keep it short (particularly for the identities).
>> > > [Authors] done in -04.
>> > >
>> > > 2) I would suggest making the module "yang-version 1.1;", because
>> > > the behaviour of YANG 1.1 is better specified.  In fact, I would
>> > > recommend that all IETF YANG modules are defined as YANG 1.1.
>> > > [Authors] done in -04.
>> > >
>> > > 3) It is actually necessary to define frequency-thz at all?  I think
>> > > that the discussion in the WG suggested that it might be better if
>> > > the frequencies are always defined in Ghz and then converted in the
>> > > client as necessary.
>> > > [Authors] We have checked all the typedef, and agreed on removing
>> > > frequency-thz and frequency-ghz together, as they are not referenced
>> > > in later groupings. Need to further check whether the modules who
>> > > import this type module would use such typedef. May need to add back
>> > > if the answer is yes. Moreover, like flexi-n, another typedef
>> > > flexi-m is added and referenced in this module.
>> > [RW]
>> > I think that defining frequency-ghz is probably still helpful, it was
>> > only frequency-thz that I was suggesting removing, effectively
>> > encouraging everyone to standardize on using frequency-ghz for layer 0
>> > properties/considerations.
>> > [Authors2] Ok, the frequency-ghz will be brought back in upcoming -04.
>> >
>> >
>> > >
>> > > 4) frequency-ghz: Is 3 fraction digits sufficient for future expansion?
>> > > E.g.
>> > > It would seem to support a flex grid 3.125Ghz channel spacing, but
>> > > not
>> > > 1.5625 ...
>> > > [Authors] Discussion needed: currently the channel spacing is
>> > > 6.25GHz, and we reserve the 3.125GHz for proof-of-future.  According
>> > > to Singapore discussion, WG agreed on 3.125 with 3 fraction digits.
>> > > We prefer to keep the current format given the following considerations:
>> > > [Authors] Consideration 1: Technically it won't make much sense for
>> > > Layer
>> > > 0 to come down to 1.5625G, as layer 1 is providing the granularity
>> > > at ODUk
>> > > (<100Gbps) which is make very good use of such spectrums.
>> > > [Authors] Consideration 2: furthermore, if 1.5625G happens in the
>> > > future, can we keep fraction digits as 3 and specify the channel
>> > > spacing as '1.562G'? There should not be difficulties in
>> > > understanding, and we solve the problem forever.
>> > > [Authors] Consideration 3: the channel spacing is not binded with
>> > > the frequency on the grid, but a number... So maybe we can change
>> > > the dependency on the grid as well.
>> > [RW]
>> > Okay, keeping this to 3 dpi is fine.
>> >
>> > >
>> > > 5) We should aim for consistency of the identity names in the
>> > > layer-1 types module.  E.g. perhaps OTU, ODU and OPU should be
>> capitalized.
>> > > [Authors] done in -04.
>> > >
>> > > 6) The models uses identities for bandwidth, but I wonder whether
>> > > defining a numerical typedef might be a better choice (e.g. more
>> > > efficient and perhaps easier for programs to work with).  Here, I
>> > > have constrained the values that are allowed, but they could also be
>> > unconstrained:
>> > >
>> > > E.g.
>> > > typedef channel-bandwidth {
>> > >   type decimal64 {
>> > >     fraction-digits 2;
>> > >     range
>> > >       "2.66|10.70|11.04|11.09|11.27|11.31|43.01|44.57|44.58|100.00 ...
>> > > max"
>> > >     description
>> > >       "Bandwidth carried by a single wavelength channel"
>> > >   }
>> > >   units "Gb/s";
>> > > }
>> > > Or another alternative would be to use Mb/s, which would then allow
>> > > them to be specified as a union of specific values and an arbitrary
>> > > bandwidth value.
>> > >
>> > > [Authors] Discussion needed: we hope this proposal is different with
>> > > the ones on 'identity->enumeration' but maybe push back by
>> > > extensibility, could you please confirm? Gbps is used for data plane
>> > > and should be accurate enough to be described in the YANG module. We
>> > > are open to the proposal, but need to understand the difference and
>> > > how it affects the configuration. After that we can discuss whether
>> > > decimal 64 is good, Gbps or Mbps, etc...
>> > >
>> > [RW]
>> > Identities are just names of things.  So, it if the bandwidth value
>> > that clients and implementations care about, then I would expect them
>> > to need to write code to translate between the identity names and
>> > numerical values.  E.g. what does a client configuring the device
>> > primarily care about here.  Is it that the bandwidth is "otu2" or that
>> > it the bandwidth is "10.70G"?
>> > [Authors2] Refer to the first point raised in Aihua's feedback. On the
>> > perspective of optical network, the bandwidth for layer 0 is discrete
>> > rather than continuous. So when we specify the bandwidth, it's more a
>> > 'type configuration' than a 'value configuration', which I believe is
>> > a main difference between optical and IP. The current understanding
>> > from the authors is that the optical bandwidth is just like 'names of
>> > things' as you said, so we prefer to keep as is. BTW, for
>> > configuration, we think the proposal can reach equivalent
>> > functionality set as the current model in the draft.
>> >
>> >
>> > > 7) Same comment as for bandwidth applies to the channel spacing
>> > > identities.
>> > > I.e. I wonder whether these wouldn't be better defined using a
>> > > decimal64 type.
>> > >
>> > > E.g.
>> > > typedef dwdm-channel-spacing {
>> > >   type decimal64 {
>> > >     fraction-digits 2;
>> > >     range
>> > >       "12.5|25|50|100"
>> > >     description
>> > >       "Bandwidth carried by a single wavelength channel"
>> > >   }
>> > >   units "Ghz";
>> > > }
>> > > [Authors] Discussion needed: probably reject, see the consideration
>> > > about extensibility on layer1-types. 6.25/3.125 GHz is coming...
>> > [RW]
>> > The model can always be extended to support 6.25/3.125 in future.  In
>> > either solution this would require a backwards compatible change to
>> > the model.
>> >
>> > My hunch is that having this as a numerical value is more useful for
>> > clients than having it as a named identity.  I.e. I think that the
>> > argument for using a numerical value here is stronger than for channel
>> > bandwidth above.
>> > [Authors2] Similar as previous comments. Let me use another example here.
>> > In a potential GUI for the system who configure the network, it is
>> > possible to a) make a few options (100, 50, 25, 12.5, ...) in a menu
>> > format; b) leave it purely open to fill with any numbers. Given the
>> > finite values for optical configurations, the option a) would be
>> > easier with less chance to make mistakes.
>> > >
>> > > 8) Same comment as for bandwidth and dwdm-channel-spacing could also
>> > > be applied to flexi-grid-channel-spacing,
>> > > flexi-slot-width-granularity, cwdm- channel-spacing.
>> > > [Authors] Discussion needed: probably reject, see the consideration
>> > > about extensibility on layer1-types.
>> > [RW]
>> > These should be resolved with whatever the conclusion is above.
>> > [Authors2] Agree, this is our pain point now. We think all these
>> > parameters in this comment are a kind of 'type configuration' rather
>> > than 'number configuration'.
>> > >
>> > > 9) In grouping layer0-label-range-info I would rename this grouping
>> > > to l0-layer-range-info, change "layer0" => "layer 0" in the description.
>> > > Also "priority" could do with a more detailed description as to what
>> > > it means, etc.
>> > > [Authors] Confirmation firstly: probably a mis-spelling, propose to
>> > > 'l0- label-range-info'.
>> > [RW]
>> > Yes.
>> > [Authors2] Okay.
>> >
>> >
>> > > [Authors] Discussion secondly: there are multiple identities/typedef
>> > > started with 'layer0-' and it should be better to keep consistency
>> > > in naming format, do we rename all of them or none of them?
>> > [RW]
>> > Yes, I think that I would rename all of them "l0-"
>> > [Authors2] Okay.
>> >
>> > Thanks,
>> > Rob
>> >
>> >
>> > > [Authors] priority updated in -04.
>> > >
>> > > 10) In grouping flexi-grid-label-start-end, I think that the type
>> > > should be "flexi-n" rather than "int16".
>> > > [Authors] done in -04,
>> > >
>> > > Typos: "girds" => "grids", "attrtibutes" => "attributes"
>> > > [Authors] done in -04,
>> > >
>> > > Spacing/indenting needs to be fixed:
>> > >  - In "grouping wson-label-hop", just before case cwdm
>> > >  - In "grouping flexi-grip-label-hop", should have a blank line
>> > > before, and  "case super" block/fields indentation doesn't look
>> > > right. - In some of the  typedef definitions, the "{" should move
>> > > from the start of the following line  to the typedef line. In
>> > > general, as a starting point, after all other markups  have been
>> > > made then it might be a good idea to use pyang to format the YANG
>> > > file for you, e.g., "pyang -f yang --yang- line-length 69", but
>> > > probably with  some more blank lines, otherwise it
>> > is
>> > > a bit dense.
>> > > [Authors] done in -04, probably some compilation problems and will
>> > double
>> > > check per update.
>
> _______________________________________________
> yang-doctors mailing list
> yang-doctors@ietf.org
> https://www.ietf.org/mailman/listinfo/yang-doctors

-- 
Ladislav Lhotka 
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67