Subject: [netmod] AD review of draft-ietf-netmod-dsdl-map

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Thu, 19 Aug 2010 18:56:55 +0200

Please find below my AD review for draft-ietf-netmod-dsdl-map-06.txt. I
believe that a revised I-D is needed before proceeding to IETF Last
Call. Also, you need to answer issue T1 either by moving the reference
to 5013 to Informational, or by specifying the downref in the IETF Last
Call. 

The comments are divided into Technical and Editorial. 

T1. There is a normative reference to RFC 5013 which is Informational.
This is a downref. If this reference must be normative, the downref must
be explicitly mentioned in the IETF Last Call. Is this the intention? 

T2. Introduction 

> The NETMOD Working Group was
   chartered to address this problem by defining a new human-friendly
   modeling language based on SMIng [RFC3216] and called YANG [YANG].

I do not believe that this statement is true. There was no requirement
in the charter to base the YANG on SMIng.

T3. Section 8.4: 

> Each embedded <rng:grammar> element must declare the namespace of
       the corresponding module using the @ns attribute.

Use capitalized MUST. 

T4. Section 10.13

> This statement MAY be ignored.  Otherwise, it is mapped to the DTD
   compatibility element <a:documentation> and ARGUMENT becomes its
   text.

What does the second sentence mean? What to do when mapping or what not
to do? 

T5. Same question as above for 10.47

T6. Section 10.56: 

> Implementations MAY ignore this statement.

Why?

T7. Section 10.60: 

> This statement is not mapped to the output schema.  However, an
   implementation SHOULD check that it is compatible with the YANG
   version declared by the statement (currently version 1).

What should an implementation do if the yang-version is not compatible?
(which may happen in the future)

T8. Section 11:

> In general, the second mapping step has to accomplish the following
   three tasks:

What does 'In general' mean here? Are there exceptions? Which ones? 

E1. Introduction: s/SNMP Management Information Bases (MIBs)/SNMP
Management Information Base (MIB) modules/

E2. Expand acronyms at the first occurrence: DSRL, etc.

E3.In section 3: s/the inverse mapping from DSDL to YANG beyond the
scope of this document/the inverse mapping from DSDL to YANG is beyond
the scope of this document/

E4. Section 4 - reference for ISO/IEC 19757, RelaxNG, Schematron, DSRL
are desirable in the introduction part of the section. 

E5. I see no reason to list the URIs separately and format them
separately then the rest of the Informative references. Actually [XSD]
is also referenced by an URI, although included with the other
references. 

E6. In section 8.2 s/SNMP MIBs/SNMP MIB modules/

E7. The non-usage of quotation marks in the titles of subsections in 10
is confusing. For example should not 10.11 be The 'container' Statement
rather than The container statement - so that the use of the noun
container in the text can be differentiated from the name of the
statement? Or in 10.12 we have The default Statement as the title of the
subsection while the text of the section speaks about the 'default'
statement. 

E8. Section 12: s/we will denote CONTELEM/we will call CONTELEM/

E9. The IANA considerations section mentions registering three namespace
URIs, but then lists only two. 

E10. Make explicit that Appendix D will be removed at document
publication.

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 19 Aug 2010 21:27:50 +0200

Hi Dan,

thank you for the review, I'll roll out the -07 revision soon. Please
see my responses and suggested changes inline.

Lada

> be explicitly mentioned in the IETF Last Call. Is this the intention? 

This reference can be moved to Informational. I just wasn't aware of
this downref issue.

> 
> T2. Introduction 
> 
> The NETMOD Working Group was chartered to address this problem by
> defining a new human-friendly modeling language based on SMIng
> [RFC3216] and called YANG [YANG].
> 

Is this better? (I hope the text will eventually refer to the YANG RFC).

OLD:

The NETMOD Working Group was chartered to address this problem by
defining a new human-friendly modeling language based on SMIng
[RFC3216] and called YANG [YANG].

NEW:

The NETMOD Working Group was chartered to address this problem by
defining a new human-friendly data modeling language called YANG. The
definition of YANG version 1 was published recently [YANG]. Its syntax
is loosely based on SMIng [RFC3216].

Alternatively, the last sentence can be removed.

>        the corresponding module using the @ns attribute.

OK

> compatibility element <a:documentation> and ARGUMENT becomes its text.
> 

OLD

This statement MAY be ignored.  Otherwise, it is mapped to the DTD
compatibility element <a:documentation> and ARGUMENT becomes its text.

NEW

This statement is mapped to the DTD compatibility element
<a:documentation> and ARGUMENT becomes its text.
 
> T5. Same question as above for 10.47

The same change, mutatis mutandis.

> > Implementations MAY ignore this statement.

You are right, I'll remove this sentence.

> (which may happen in the future)

OLD:

This statement is not mapped to the output schema.  However, an
implementation SHOULD check that it is compatible with the YANG version
declared by the statement (currently version 1).

NEW:

This statement is not mapped to the output schema.  However, an
implementation SHOULD check that it is compatible with the YANG version
declared by the statement (currently version 1). In the case of a
mismatch, the implementation SHOULD report an error and terminate.

> What does 'In general' mean here? Are there exceptions? Which ones? 

OLD:

NEW:

The second mapping step has to accomplish the following three general

> Management Information Base (MIB) modules/

OK

> E2. Expand acronyms at the first occurrence: DSRL, etc.

Will do.

> the scope of this document/

OK

> are desirable in the introduction part of the section.

I will put them there.
 
> is also referenced by an URI, although included with the other

This is how xml2rfc handles hyperlinks (<eref>). I don't like it either,
so I will change them to standard informational references.
 
> E6. In section 8.2 s/SNMP MIBs/SNMP MIB modules/

OK

> subsection while the text of the section speaks about the 'default'

I actually thought about this in an early stage but then decided to
follow the suit of the YANG draft where the (double) quotes are omited
in section titles, too. I will add the single quotes to titles.

> E8. Section 12: s/we will denote CONTELEM/we will call CONTELEM/

I suggest this:

OLD:

In the rest of this section, we will denote CONTELEM the name of this
context element properly qualified with its namespace prefix.

NEW:

In the rest of this section, CONTELEM will denote the name of this
context element properly qualified with its namespace prefix.

> URIs, but then lists only two.

I got rid of one between -05 and -06 and forgot to update the count.

> E10. Make explicit that Appendix D will be removed at document

OK, I will add an instruction to the RFC Editor.

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

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 19 Aug 2010 21:59:49 +0200

> is loosely based on SMIng [RFC3216].

Although the syntax of YANG has some heritage of SMIng (and I
generally appreciate references to SMIng for my ego ;-), I do not
consider this important enough to be mentioned. I also do not think
that the YANG version number matters in this context. Here is a quote
of the original charter (which is still in the current charter):

  The WG will define a "human-friendly" modeling language defining
  the semantics of operational data, configuration data,
  notifications, and operations.  This language will focus on
  readability and ease of use.  This language must be able to serve
  as the normative description of NETCONF data models.

So the text should perhaps read like this:

  The NETMOD Working Group was chartered to define a "human-friendly"
  modeling language called YANG [YANG] defining the semantics of
  operational data, configuration data, notifications, and
  operations. This language focuses on readability and ease of use and
  it serves as the normative description of NETCONF data models.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Thu, 19 Aug 2010 13:28:59 -0700

>   it serves as the normative description of NETCONF data models.

I agree.
Actually, YANG has some 'best hits' constructs from
3 different proprietary data modeling languages, plus SMIng.
IMO, the sum is greater than the parts this time. YANG turned
out much better than any one of the 4 individual languages.
(The way standards are supposed to come together ;-)

> /js

Andy

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Sun, 22 Aug 2010 17:10:58 +0200

Hi Lada,

Thank you for your answers. All the changes proposed by you in this mail
are fine with me with the exception of the change in answer to my
comment T2. In that case I would suggest that you make the change
proposed by Juergen. 

Thanks and Regards,

Dan

> -----Original Message-----
> From: Ladislav Lhotka [mailto:[email-masked]] 
> Sent: Thursday, August 19, 2010 10:28 PM
> To: Romascanu, Dan (Dan); NETMOD Working Group
> Subject: Re: [netmod] AD review of draft-ietf-netmod-dsdl-map
> 
> Hi Dan,
> 
> thank you for the review, I'll roll out the -07 revision 
> soon. Please see my responses and suggested changes inline.
> 
> Lada
> 
> > Please find below my AD review for 
> draft-ietf-netmod-dsdl-map-06.txt. 
> > I believe that a revised I-D is needed before proceeding to 
> IETF Last 
> > to 5013 to Informational, or by specifying the downref in the IETF 
> > Last Call.
> > 
> > This is a downref. If this reference must be normative, the downref 
> > must be explicitly mentioned in the IETF Last Call. Is this 
> the intention?
> 
> This reference can be moved to Informational. I just wasn't 
> aware of this downref issue.
> 
> > 
> > T2. Introduction
> > 
> The NETMOD Working Group was chartered to address this 
> problem by defining a new human-friendly modeling language 
> based on SMIng [RFC3216] and called YANG [YANG].
> 
> NEW:
> 
> The NETMOD Working Group was chartered to address this 
> problem by defining a new human-friendly data modeling 
> language called YANG. The definition of YANG version 1 was 
> published recently [YANG]. Its syntax is loosely based on 
> SMIng [RFC3216].
> 
> > What does the second sentence mean? What to do when mapping or what 
> > not to do?
> 
> OLD
> 
> This statement MAY be ignored.  Otherwise, it is mapped to 
> the DTD compatibility element <a:documentation> and ARGUMENT 
> becomes its text.
> 
> NEW
> 
> This statement is not mapped to the output schema.  However, 
> an implementation SHOULD check that it is compatible with the 
> YANG version declared by the statement (currently version 1).
> 
> NEW:
> 
> This statement is not mapped to the output schema.  However, 
> an implementation SHOULD check that it is compatible with the 
> YANG version declared by the statement (currently version 1). 
> In the case of a mismatch, the implementation SHOULD report 
> an error and terminate.
> 
> > 
> > T8. Section 11:
> > 
> In general, the second mapping step has to accomplish the 
> following three tasks:
> 
> NEW:
> 
> This is how xml2rfc handles hyperlinks (<eref>). I don't like 
> it either, so I will change them to standard informational references.
>  
> > 
> > E7. The non-usage of quotation marks in the titles of 
> subsections in 
> > 10 is confusing. For example should not 10.11 be The 'container' 
> > Statement rather than The container statement - so that the 
> use of the 
> > noun container in the text can be differentiated from the 
> name of the 
> > statement? Or in 10.12 we have The default Statement as the 
> title of 
> > the subsection while the text of the section speaks about 
> the 'default'
> > statement.
> 
> I actually thought about this in an early stage but then 
> decided to follow the suit of the YANG draft where the 
> (double) quotes are omited in section titles, too. I will add 
> the single quotes to titles.
> 
> > 
> In the rest of this section, we will denote CONTELEM the name 
> of this context element properly qualified with its namespace prefix.
> 
> NEW:
> 
> In the rest of this section, CONTELEM will denote the name of 
> this context element properly qualified with its namespace prefix.
> 
> > 
> > E9. The IANA considerations section mentions registering three 
> > namespace URIs, but then lists only two.
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 23 Aug 2010 10:17:38 +0200

> comment T2. In that case I would suggest that you make the change

I'd also like to communicate the fact that NETMOD not only was chartered
to deliver but indeed delivered the language. I propose the following
reformulation of Juergen's text:

    The NETMOD Working Group was chartered to design a modeling language
    defining the semantics of operational data, configuration data,
    event notifications and operations, with focus on
    "human-friendliness", i.e., readability and ease of use. The result
    is the YANG data modeling language [YANG], which now serves for the
    normative description of NETCONF data models.

Is this wording acceptable?

Thanks, Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Mon, 23 Aug 2010 13:17:30 +0200

No problem for me with this change of wording. 

Dan

> Sent: Monday, August 23, 2010 11:18 AM
> Subject: RE: [netmod] AD review of draft-ietf-netmod-dsdl-map
> 
> > Thank you for your answers. All the changes proposed by you in this 
> > mail are fine with me with the exception of the change in 
> answer to my 
> I'd also like to communicate the fact that NETMOD not only 
> was chartered to deliver but indeed delivered the language. I 
> propose the following reformulation of Juergen's text:
> 
> > > thank you for the review, I'll roll out the -07 revision soon. 
> > > Please see my responses and suggested changes inline.
> > > 
> > > Lada
> > > 
> > > > This is a downref. If this reference must be normative, the 
> > > > downref must be explicitly mentioned in the IETF Last Call. Is 
> > > > this
> > > the intention?
> > > 
> problem by 
> > > Is this better? (I hope the text will eventually refer to 
> the YANG 
> > > RFC).
> > > 
> > > OLD:
> > > 
> > > defining a new human-friendly data modeling language called YANG. 
> > > The definition of YANG version 1 was published recently 
> [YANG]. Its 
> > > syntax is loosely based on SMIng [RFC3216].
> > > 
> > > > > Each embedded <rng:grammar> element must declare the 
> namespace 
> > > > > of
> > > > What does the second sentence mean? What to do when mapping or 
> > > > what not to do?
> > > 
> > > OLD
> > > 
> > > In the case of a mismatch, the implementation SHOULD 
> report an error 
> > > and terminate.
> > > 
> > > > 
> > > > T8. Section 11:
> > > > 
> following 
> > > > E3.In section 3: s/the inverse mapping from DSDL to YANG beyond 
> > > > the scope of this document/the inverse mapping from DSDL to
> > > YANG is beyond
> > > This is how xml2rfc handles hyperlinks (<eref>). I don't like it 
> > > either, so I will change them to standard informational 
> references.
> > >  
> > > > 
> decided to 
> > > follow the suit of the YANG draft where the
> > > (double) quotes are omited in section titles, too. I will add the 
> > > single quotes to titles.
> > > 
> > > > 
> > > In the rest of this section, we will denote CONTELEM the name of