Subject: Re: [CCAMP] FW: New Version Notification for draft-ietf-ccamp-flexigrid-yang-05.txt

From: Zhenghaomian <[email-masked]>
Date: Sat, 11 Jan 2020 02:37:04 +0000

Thank you Dan for the update, and Adrian for the comments. 

Some more comments from my review as below: 

---------- comments start here-------------

draft-ietf-ccamp-flexigrid-yang-05

1. Global types changes will be needed according to the module prefix change in ietf-layer0-types: layer0-types->l0-types; 

2. Section 3, the following text looks not necessary, suggest to remove (usually no need to prove the necessity of models): 
A YANG model has also been proposed in [I-D.draft-dharini-ccamp-dwdm-if-yang] to manage single channel optical interface parameters of DWDM applications, and in [I-D.draft-ietf-ccamp-wson-yang] another model has been specified for the routing and wavelength assignment TE topology in wavelength switched optical networks (WSONs). None of them are specific for flexi-grid technology.

3. usage of term 'transponder': 
(section 1)This document presents a YANG [RFC7950] model for flexi-grid objects in the dynamic optical network, including the nodes, transponders and links between them, as well as how such links interconnect nodes and transponders.
(section 3)In order to be compatible with existing proposals, we augment the definitions contained in [RFC8345] and [TE-TOPO], by defining the different elements we can find in a flexi-grid network: a node, a transponder and a link.

It is misleading to have 'node' and 'transponder' in parallel, transponder is a part of the node. The topology model does not need to have the transponder information, instead we use 'TE node' in the base model (ietf-te-topology), which includes the transponder, ROADM, etc.. 
There is transponder info in RBNF but not in YANG. It is suggested to remove transponder related parameters. Probably impairment-topology would be a candidate home for those parameters. 

4. Section 3, 'For that, each of those elements is defined as a container that includes a group of attributes.' We don't have container of transponder in the YANG model...

5. In section 3, No need to mention the Flexi-grid-tunnel YANG document, as there is no strong connection. The progress of tunnel would delay the progress of this one. Both WSON/OTN decoupled the topology document and the tunnel document. 

6. Section 4, it is useful to have RBNF model, but some of the non-RBNF content are in RBNF format, for example: 
    <flexi-grid-node>: This element designates a node in the network.
It is proposed to have such parts in separate places, and remove the RBNF symbol like '<>' and "::="; 
May turn to more detailed guidance in Adrian's email...

7. Section 4, regarding the RBNF, it is suggested to focus on flexi-grid specific terminologies, such as flexi-grid-node. Some common terms have already been specified in other documents, for example connectivity-matrix, numbered/unnumbered-interface, etc. These terms, at least for their explanation, are suggested to be removed. 

8. Section 4, suggest to rename: <link> -> <flexi-grid-link>, to keep consistency with node. 

9. The 'flexi-grid TED YANG model' is not clear on TED. I assume it to be Traffic-engineering Database. But looking at the context, changing to 'flexi-grid topology YANG model' should be better. In both section 5 and title of section 6. 

10. Section 5, figure 1 would be misleading as the separation of node and transponder. See #4 for more detailed comments. 

11. It is suggested to have the model prefix as 'flexi-grid-topology' rather than 'flexi-grid'. 

Models would be reviewed after we agreed on the issues above...

-------------- comments end here -------------------

Best wishes,
Haomian

-----邮件原件-----
发件人: CCAMP [mailto:[email-masked]] 代表 Adrian Farrel
发送时间: 2020年1月11日 0:03
收件人: 'King, Daniel' <[email-masked]>; 'CCAMP' <[email-masked]>
主题: Re: [CCAMP] FW: New Version Notification for draft-ietf-ccamp-flexigrid-yang-05.txt

That's timely Dan, thanks.

But I've just been reviewing the previous version so here are my comments on that.

Apologies if you've already picked up any of these points.

Best,
Adrian

===

Update Young Lee's coordinates on the document and in the YANG module

---

Abstract should come first

---

Abstract

OLD
   This document defines a YANG model for managing flexi-grid optical
   Networks. The model described in this document defines a flexi-grid
   traffic engineering database. A complementary module is referenced
   to detail the flexi-grid media channels.

   This module is grounded on other defined YANG abstract models.
NEW
   This document defines a YANG module for managing flexi-grid optical
   networks. The model defined in this document specifies a flexi-grid
   traffic engineering database that is used to describe the topology of
   a flexi-grid network. It is based on and augments existing YANG 
   models that describe network and traffic engineering topologies. 

   A partner document defines a second YANG module for flexi-grid media
   channels, i.e., the paths from source to destination through a number
   of intermediate nodes.
END

---

Please capitalise all section headings

---

The table of contents appears to be missing most of the page numbers.

---

Section 1 reads a bit like a marketing statement for flexi-grid, rather than introducing this document. How about:

OLD
   Internet-based traffic is dramatically increasing every year.
   Moreover, such traffic is also becoming more dynamic. Thus,
   transport networks need to evolve from current DWDM systems towards
   elastic optical networks, based on flexi-grid transmission and
   switching technologies [RFC7698]. This technology aims at increasing
   both transport network scalability and flexibility, allowing the
   optimization of bandwidth usage.

   This document presents a YANG [RFC7950] model for flexi-grid objects 
   in the dynamic optical network, including the nodes, transponders 
   and links between them, as well as how such links interconnect nodes 
   and transponders.

   The YANG model for flexi-grid networks allows the representation of
   the flexi-grid optical layer of a network, combined with the
   underlying physical layer.

   This document identifies the flexi-grid components, parameters and
   their values, characterizes the features and the performances of the
   flexi-grid elements. An application example is provided towards the
   end of the document to better understand their utility.
NEW
   The flexible grid (flexi-grid) optical network technology defined by
   the International Telecommunication Union Telecommunication
   Standardization Sector (ITU-T) and documented in Recommendation 
   G.694.1 and G.872 [G.694.1] [G.872] provides an enhanced Dense
   Wavelength Division Multiplexing (DWDM) grid by defining a set of
   nominal central frequencies, channel spacings, and the concept of the
   "frequency slot".  In such an environment, a data-plane connection is
   switched based on allocated, variable-sized frequency ranges within
   the optical spectrum, creating what is known as a flexible grid
   (flexi-grid).  This technology increases both transport network 
   scalability and flexibility, allowing the optimization of bandwidth
   usage.

   [RFC7698] provides a framework GMPLS-Based control of flexi-grid DWDM
   networks while [RFC7699] defines generalized labels for the use in
   flexi-grid in GMPLS networks.

   This document presents a YANG [RFC7950] model for flexi-grid objects 
   in the dynamic optical network, including the nodes, transponders 
   and links between them, as well as how such links interconnect nodes 
   and transponders.

   The YANG model for flexi-grid networks allows the representation of
   the flexi-grid optical layer of a network, combined with the
   underlying physical layer.

   This document identifies the flexi-grid components, parameters and
   their values, characterizes the features and the performances of the
   flexi-grid elements. An application example is provided towards the
   end of the document to better understand their utility.

   A partner document defines a second YANG module that described flexi-
   grid media channels, i.e., the paths from source to destination
   through a number of intermediate nodes
   [I-D.draft-ietf-ccamp-flexigrid-media-channel-yang].
END

---

Section 2 has a lot of stuff that can be dropped. I think:

OLD
   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   In this document, these words will appear with that interpretation
   only when in ALL CAPS. Lower case uses of these words are not to be
   interpreted as carrying RFC-2119 significance.

   In this document, the characters ">>" preceding an indented line(s)
   indicates a compliance requirement statement using the key words
   listed above. This convention aids reviewers in quickly identifying
   or finding the explicit compliance requirements of this RFC.
NEW
   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.
END

---

2.1

s/chapter 6/Section 6/

---

2.3

OLD
   Note: The RFC Editor will replace XXXX with the number assigned to
   the RFC once this draft becomes an RFC.
NEW
   RFC Editor Note: Please replace XXXX with the RFC number assigned to
   this document when it is published.  Please remove this note.
END

---

3.

s/proposed/defined/   (twice)
s/propose/define/
s/proposals/specifications/

---

4.
OLD
   This section details the defined YANG module. It is listed below in
   section 6.
NEW
   This section describes the YANG module. It is specified in Ssection
   6.
END

---

Section 4 uses notation that looks a bit like BNF. Can you add a note at the top of this section to point to where the notation is defined, or to define the notation if it is new.

Whoah! I found the answer in Section 4.1. Just kill that section and move the text to the top of Section 4. Although, are you sure you are using ABNF from RFC 5234? That spec does not define "::=" for example.
What you actually have looks a lot more like RBNF per RFC 5511.

---

In Section 4, please pay attention to the need for additional blank lines between elements to provide clarity and make it easier to read.
Also consider the alignment of continuation lines.

For example (but there are many others)

OLD
           <config>: Contains the configuration of a node.
           <flexi-grid-node-attributes-config> ::= <list-interface>
           <connectivity_matrix>
NEW
           <config>: Contains the configuration of a node.

           <flexi-grid-node-attributes-config> ::= <list-interface>
                                                   <connectivity_matrix> END

---

Section 4

s/A interface/An interface/

---

While Figure 1 is structurally correct for the example, it might help the reader if you showed the traffic source and sink on the figure.

---

Section 5 is really helpful, but I think it needs to be enhanced to say which bits of which models/modules are used for the steps described.

---

Section 6.1 could also benefit from a lot more blank lines. I think, at least, you could put one before each "augment".

---

6.2
Maybe put <CODE BEGINS> on its own line

---

Section 6.2

Please clean up the instructions to the RFC Editor about inserting RFC numbers as follows:

- Start the section (before the YANG model) with the following text

  RFC Editor Note: Please replace the string "ZZZZ" in the YANG model
  definition below with the RFC number assigned to
  draft-ietf-ccamp-wson-yang when it is published as an RFC. Please
  replace the string "YYYY" in the YANG model definition below with the
  RFC number assigned to draft-ietf-teas-yang-te-topo when it is
  published as an RFC. Please remove this note.

- Replace your use of XXXX in this section with ZZZZ (Note you have
  already used XXXX to mean something else in Section 2.3.

-- Remove the two notes embedded in comments in the YANG model

---

6.2
You have commented out some YANG in a number of places. For example:

  /* Augment maximum LSP bandwidth of TE link template */
  augment "/nw:networks/tet:te/tet:templates/"
        + "tet:link-template/tet:te-link-attributes/"
        + "tet:interface-switching-capability/"
        + "tet:max-lsp-bandwidth/"
        + "tet:te-bandwidth/tet:technology" {
/*
    when "../../../../../../nw:network-types/tet:te-topology/"
       + "flexi-grid:flexi-grid-topology" {
      description "flexi-grid TE bandwidth.";
    }
*/
    description "flexi-grid bandwidth.";
    case flexi-grid {
      uses layer0-types:flexi-grid-path-bandwidth;
    }
  }

What's that all about?

---

6.2
Some of the comment-wraps need to be correctly indented

---

6.3 Why is this section present? I think it is wrong.

---

Section 8 looks wrong to me. Maybe:

OLD
   The namespace used in the defined model has to register a URI in
   the IETF XML registry [RFC3688], as well as in the YANG Module
   Names registry [RFC6020].
NEW
   IANA is requested to assigned a new URI from the "IETF XML Registry"
   [RFC3688] as follows:

      URI: urn:ietf:params:xml:ns:yang:ietf-flexi-grid-topology
      Registrant Contact: The IESG
      XML: N/A; the requested URI is an XML namespace.

   IANA is requested to assign a new YANG module name in the "YANG
   Module Names" registry [RFC6020] as follows:

      Name: ietf-l3vpn-svc
      Namespace: urn:ietf:params:xml:ns:yang:ietf-flexi-grid-topology
      Prefix: flexi-grid-topology
      Reference: [This.I-D]
END

---

9.2

draft-ietf-ccamp-wson-yang should be a normative reference for how it is used in import ietf-layer0-types.

draft-ietf-teas-yang-te-topo should be a normative reference for how it is used in import ietf-te-topology

-----Original Message-----
From: CCAMP <[email-masked]> On Behalf Of King, Daniel
Sent: 09 January 2020 21:45
To: CCAMP ([email-masked]) <[email-masked]>
Subject: [CCAMP] FW: New Version Notification for draft-ietf-ccamp-flexigrid-yang-05.txt

Dear CCAMP'rs, 

Please note that the new version of draft-ietf-ccamp-flexigrid-yang (version 5). The new I-D has minimal updates (affiliation changes). 

Several YANG errors exist which will be fixed shortly. In the meantime, WG participants are most welcome to review and comment on the I-D. 

BR, Dan. 

-----Original Message-----
From: [email-masked] <[email-masked]>
Sent: 09 January 2020 21:32
To: Haomian Zheng <[email-masked]>; Jorge E. Lopez de Vergara <[email-masked]>; Universidad de Madrid <[email-masked]>; King, Daniel <[email-masked]>; Young Lee <[email-masked]>; Daniel Perdices <[email-masked]>; Victor Lopezalvarez <[email-masked]>; Victor Lopez <[email-masked]>
Subject: [External] New Version Notification for draft-ietf-ccamp-flexigrid-yang-05.txt

This email originated outside the University. Check before clicking links or attachments.

A new version of I-D, draft-ietf-ccamp-flexigrid-yang-05.txt
has been successfully submitted by Daniel King and posted to the IETF repository.

Name:           draft-ietf-ccamp-flexigrid-yang
Revision:       05
Title:          YANG data model for Flexi-Grid Optical Networks
Document date:  2020-01-08
Group:          ccamp
Pages:          75

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-ccamp-flexigrid-yang/

There are also htmlized versions available at:
https://tools.ietf.org/html/draft-ietf-ccamp-flexigrid-yang-05
https://datatracker.ietf.org/doc/html/draft-ietf-ccamp-flexigrid-yang-05

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-ietf-ccamp-flexigrid-yang-05

Please note that it may take a couple of minutes from the time of submission until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

Abstract:
   This document defines a YANG model for managing flexi-grid optical
   Networks. The model described in this document defines a flexi-grid
   traffic engineering database. A complementary module is referenced
   to detail the flexi-grid media channels.

   This module is grounded on other defined YANG abstract models.

Please note that it may take a couple of minutes from the time of submission until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat

_______________________________________________
CCAMP mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ccamp

_______________________________________________
CCAMP mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/ccamp