abierman
commented
8 years ago - Section 3.4.1.1: This section has "SHOULD maintain last-modified timestamps for descendant resources", and section 3.5 (data resource) has "the server MAY maintain a last-modified timestamp for the resource". I assume that a descendant resource is a data resource, so the MAY/SHOULD are somewhat contradictory. One solution would be to remove the conformance requirement for descendants from 3.4.1.1, and change 3.5 to a SHOULD. The same issue applies to entity tag.
AB: changed MAY to SHOULD; s/resource/data resource/
- Section 3.7: Since support for YANG module retrieval is optional, should we provide a capability for it?
AB: not changed; server not required to have all-or-none YANG modules available for retrieval. Each entry will have a schema leaf if is is available for retrieval
- Section 4.8.1: This has "The default value is determined by the "config" statement value of the requested data nodes." What if the requested data node is a container with a mixture of "config false" leafs and "config true" leafs? It seems like this could be replaced with "The default value is "all"."
AB: clarified this text
- Sections 4.8.4 and 4.8.5: What if my server only supports modules that use the default ordering exclusively (system order)? If so, mandating "insert" and "point" is cumbersome. I tend to think that these should be grouped into a capability like other query parameters. If there is concern about this, we could state that "If the server implements a module with data nodes that specify user ordering, then the server MUST support this capability."
AB: If the server has only ordered-by system data then these query parameters are not allowed to be used. The server will just return an error. The real issue is that modules with ordered-by user have to be fully supported. (no text changed)
Typos/nits:
- Section 3, last paragraph: The first sentence states "The RESTCONF protocol does not include a resource discovery mechanism.", but the next section 3.1 specifies a resource discovery mechanism for the root. I know what you mean (i.e. RESTCONF doesn't discover YANG data nodes), but this threw me a bit when I first read it. For clarity I think you could remove this sentence, and the "Instead, " of the following sentence, and merge that that sentence into the preceding paragraph.
AB: s/resource/data resource/
- Section 3.5.1: Change "If there are multiple key leaf values, the value of each leaf" to "If there are multiple key leaf values, the path segment is constructed by having the list name followed by an "=" followed by the leaf values. The value of each leaf". In other words, clarify that the "=" applies for both.
AB: rewritten
- Section 3.7: This has "The server can optionally support retrieval of the YANG modules it supports, using the "ietf-yang-library" module, defined in [I-D.ietf-netconf-yang-library]. To retrieve a YANG module, a client first needs to get the URL for retrieving the schema." On first read this sounds like ietf-yang-library is optional (which it isn't, Section 10). Another wording: "The server can optionally support retrieval of the YANG modules it supports. To retrieve a YANG module, a client first needs to get the URL for retrieving the schema using the "ietf-yang-library" module (Section 10)."
AB: clarified text
- Section 4: In "The PATCH method is equivalent to a "merge" operation when using a plain patch (see Section 4.6.1), other media-types may provide more granular control.", replace the comma with a semicolon.
AB: done
- Section 4.4.1: In "The data-model for the child tree is the subtree is defined by YANG for the child resource.", replace the 2nd "is" with "as".
AB: done
- Section 4.4.1: This has "The "insert" and "point" query parameters are supported by the POST method for datastore and data resource types, as specified in the YANG definition in Section 8.". The reference to Section 8 seems out of place. Should this be phrased like section 4.5 (PUT), with "The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query parameters are supported by the POST method for for datastore and data resource types."?
AB: used PUT as template
Section 5.3: In "If there was no request input, then the default output encoding is XML or JSON, depending or server preference.", replace the 2nd "or" with "on".
AB: done
From Rodney Cummimgs
https://www.ietf.org/mail-archive/web/netconf/current/msg10844.html