Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content
draft-ietf-netmod-dsdl-map-10

[Ballot discuss]
This is a discuss-discuss (I'm not asking for any changes - just trying to figure this out)

DSRL can change the validated schema.  The validated schema is the bit that normally would have been sent down the wire from say a client to a server.  From what I've yahoooo!-ed, DSRL can be used to modify the names of elements and fields.  Say a client changes the name of a field called "stop" to "arrêt" - who is the server going to know to undo that change to get back to a validated schema?  Are the all the mappings performed sent along from the client to the server to facilitate this?

The document includes the following text:

While the mapping from YANG to DSDL described in this document may in principle be invertible, the inverse mapping from DSDL to YANG is beyond the scope of this document.

Are we setting ourselves for clients who send stuff to servers and the server can't validate that the response is a validate schema?

[Ballot discuss]
This is a well written document, a pleasure to read.

I have one minor issue that I would like to quickly discuss before recommending approval of this document:


In Section 11.3 (on page 74):

 
 
   
      /nc:rpc-reply/nc:data
      ex6:outer
     
        1
        2


This looks like a cut and paste error (extra text), can you please confirm?

 
 
   
      /nc:rpc-reply/nc:data
      ex6:outer
     
        1
       
          2
       
     
   

[...]

[Ballot comment]
1. Section 10.36 states that the 'namespace' statement is mapped either (a) to the @xmlns:PREFIX attribute of the root  element or (b) to the @ns attribute of PARENT. How does an application determine whether to map the statement to (a) or (b)? Is the trigger here inclusion of the sibling 'prefix' statement? If so, I think the text could be clearer.

2. Section 10.53.2 states that the boolean type is mapped to either "true" or "false" in accordance with the XSD boolean datatype. However, in W3 XML Schema Datatypes, there are two lexical representations of TRUE ("true" and "1") and FALSE ("false" and "0"), respectively. It would help to make it clear that you are using only the non-numeric lexical representations.

3. The IANA can clarify this matter, but to me the XML namespace registrations look incomplete; I think you want registrations like this:

  URI: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1
  Specification: XXXX [ = "&rfc.number;" if you're using xml2rfc ]
  Description: The XML namespace name for NETMOD-specific
                      annotations in the YANG data modeling language.
  Registrant Contact: IETF, NETMOD Working Group,

[Ballot comment]
Section 10.36 states that the 'namespace' statement is mapped either (a) to the @xmlns:PREFIX attribute of the root  element or (b) to the @ns attribute of PARENT. How does an application determine whether to map the statement to (a) or (b)? Is the trigger here inclusion of the sibling 'prefix' statement? If so, I think the text could be clearer.

[Ballot comment]
Nit

Table 2 shows a list of referenced seciton number.
Every time it references section 8.1 is says "Section 8.1" when is
should just say "8.1"

IANA has questions about this document.

IANA understands that there are two actions that must be completed upon
approval.

In both cases, new entries are being added to the namespace ("ns")
registry in the IANA XML Registry located at:

http://www.iana.org/assignments/xml-registry/ns.html

For the first,
the ID is: dsdl-annotations
the URI is: urn:ietf:params:xml:ns:netmod:dsdl-annotations:1
the template is dsdl-annotations
and the reference is: [RFC-to-be]
IANA QUESTION: What should the template for this namespace contain (see
http://www.iana.org/assignments/xml-registry/ns.html)

For the second,
the id is: xpath-extensions
the URI is: urn:ietf:params:xml:ns:netmod:xpath-extensions:1
the template is xpath-extensions
and the reference is: [RFC-to-be]
IANA QUESTION: What should the template for this namespace contain (see
http://www.iana.org/assignments/xml-registry/ns.html)

IANA understands that these are the only actions required upon approval
of this document.

AD Review on draft-06

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  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  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.

Document write-up for draft-ietf-netmod-dsdl-map-06.txt

(1.a)  Who is the Document Shepherd for this document?

        David Partain, NETMOD WG co-chair

        Has the Document Shepherd personally reviewed this version
        of the document and, in particular, does he or she believe
        this version is ready for forwarding to the IESG for
        publication?

        Yes, I have reviewed this document and consider it
        ready for IESG review and publication as a Proposed
        Standard.

(1.b)  Has the document had adequate review both from key WG members
        and from key non-WG members?

        Does the Document Shepherd have any concerns about the
        depth or breadth of the reviews that have been performed?

This document references and makes use of several
external technologies and therefore entails a rather
steep learning curve.

I am concerned that there have only been a few reviews
within the Working Group itself, and only limited review
from outside the Working Group. Requests to get expert
review have not been as successful as the WG chairs would
like.  However, it is quite clear that we have reached
the point in the Working Group itself where further
document cycles will not improve the document further.

(1.c)  Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization, or XML?

The document would be well-served by further review from
the APPS area and others with competence in XML schema
languages (Document Schema Definition Languages and
related technology).

(1.d)  Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of?

        No.

        Has an IPR disclosure related to this document been filed?

        No IPR disclosures have been filed against this document.

(1.e)  How solid is the WG consensus behind this document?  Does it
        represent the strong concurrence of a few individuals, with
        others being silent, or does the WG as a whole understand and
        agree with it?

I believe this document represents consensus of the
working group among those with sufficient background
knowledge to be able to contribute.

(1.f)  Has anyone threatened an appeal or otherwise indicated extreme
        discontent?

        No.

(1.g)  Has the Document Shepherd personally verified that the
        document satisfies all ID nits?  (See
        http://www.ietf.org/ID-Checklist.html and
        http://tools.ietf.org/tools/idnits/.)  Boilerplate checks are
        not enough; this check needs to be thorough.

        The following will need to be fixed:

** Downref: Normative reference to an Informational RFC: RFC 5013

This reference must be changed an informative reference.

        The following are incorrectly noted as nits:

The "unexpected reference format" warnings are not in
fact references.

Other "Downref" warnings point to external references and
appear to be correct.

Has the document met all formal review criteria it needs
to, such as the MIB Doctor, media type, and URI type
reviews?

Yes.

(1.h)  Has the document split its references into normative and
        informative?

Yes.

Are there normative references to documents that are not
ready for advancement or are otherwise in an unclear
state?

The companion NETMOD documents (draft-ietf-netmod-yang
and draft-ietf-netmod-yang-types) are included but will
be going to advancement in parallel.  Both have already
been approved by the IESG.

If such normative references exist, what is the strategy
for their completion?

They are being advanced in parallel.

Are there normative references that are downward
references, as described in [RFC3967]?

No.

(1.i)  Has the Document Shepherd verified that the document's IANA
        Considerations section exists and is consistent with the body
        of the document?

Yes.

If the document specifies protocol
        extensions, are reservations requested in appropriate IANA
        registries?  Are the IANA registries clearly identified?

Yes.

If the document creates a new registry, does it define
the proposed initial contents of the registry and an
allocation procedure for future registrations?

Yes.

Does it suggest a reasonable name for the new registry?

Yes.

(1.j)  Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

Yes.

(1.k)  The IESG approval announcement includes a Document
        Announcement Write-Up.  Please provide such a Document
        Announcement Write-Up.  Recent examples can be found in the
        "Action" announcements for approved documents.  The approval
        announcement contains the following sections:

        Technical Summary

  YANG is a data modeling language used to model
  configuration and state data manipulated by the Network
  Configuration Protocol (NETCONF) protocol, NETCONF
  remote procedure calls, and NETCONF notifications. 

  This document specifies the mapping rules for
  translating YANG data models into Document Schema
  Definition Languages (DSDL), a coordinated set of XML
  schema languages standardized as ISO 19757.  The
  following DSDL schema languages are used by the
  mapping: RELAX NG, Schematron and DSRL.  The mapping
  takes one or more YANG modules and produces a set of
  DSDL schemas for a selected target document type -
  datastore content, NETCONF PDU etc.  Procedures for
  schema-based validation of such documents are also
  discussed.

        Working Group Summary

          Consensus was reached among all interested parties before
          requesting the publication of this document.

        Document Quality

          There is a publicly-available implementation of the
  mapping rules available.  The development of this tool
  has been done in parallel with writing the document,
  so the document reflects the running code.