Subject: Re: [xml-dir] request review of NETCONF protocol

From: Andy Bierman <[email-masked]>
Date: Wed, 18 May 2005 07:59:40 -0700

Wijnen, Bert (Bert) wrote:

>Thanks Scott, I did also see it on xml-dir list.
>
>Thanks to the reviewer Tim Bray.
>
>I am assuming that WG chairs will follow up on this.
>  
>
Here is a summary of the issues raised in Tim's review:

============================================================

1. term API

[mildly humorous]: When we chartered the Atompub WG, we were told 
sternly that
we had to call it the Atom Publishing Protocol because "The IETF doesn't 
do APIs."

Response: The protocol isn't an API -- it provides operations to manipulate
configuration datastores, which allows for a programmatic interface to be
layered on top.  Such an API will likely impose additional structure
and semantics (meta-schema and data models) on the XML payloads in
NETCONF PDUs.  NETCONF simply requires a well-formed XML payload.

between a manager and agent.  I guess this paragraph should be more clear.

==============================

3.1, 3.2 : URN and DTD clarifications

Response:  Editor will fix the text

==============================

4.1:  XML Encoding Issues

When implementing XML processing software, it is advantageous if the set 
of element and attribute is fixed, and known in advance.  This allows 
them to be predeclared as fixed readonly constants.  NETCONF encodes 
method and argument names as element names, which is very 
unconventional.  While not illegal, it does fly in the face of the 
common vocabulary design idiom for this kind of situation.

Here's the example from 4.1

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <rock-the-house xmlns="http://example.net/rock/1.0">
         <zip-code>27606-0100</zip-code>
       </rock-the-house>
     </rpc>

Most other similar XML vocabularies look like this:

<rpc message-id="101" xmlns="..." >
 <method name="rock-the-house">
  <parm name=zip-code>276-0100</parm>
  </method>
 </rpc>

or

<rpc message-id="101" xmlns="..." method="rock-the-house">
  <parm name="zip-code">27606-0100</parm>
  </rpc>

(the latter if you have a one-method-per-RPC constraint)

Response:  I think this came from Junoscript, and I don't think this
issue was ever seriously discussed.  Phil Shafer is also on xml-dir,
and he strongly advocated this approach. 

One example that was discussed at length was the <config> parameter.
Many people suggested simple strings (e.g., "candidate" or "running")
instead of element names.  I think Phil convinced the WG this element
name approach was better.

I personally don't know how much complexity this adds to implementations
or the importance of this XML style guideline.  ** Needs more discussion.

==============================

I'm also troubled that NETCONF reserves the element "<get>" (and a bunch 
of others, see section 7...) so nobody defining their own methods can 
define one named "get".  This means that it's going to be really tough 
to extend NETCONF in future with new built-in methods because various 
devices out there may have taken those names.

More broadly, it's somewhat troubling that there's no method of 
disambiguating, not only between between NETCONF-defined and 
device-defined names, but between different devices' methods.  That is 
to say, there can be an arbitrary number of "rock-the-vote" methods out 
there in the network... network-management-system DBMS management might 
be easy if NETCONF provided a built-in way to disambiguate between these 
methods. (Mind you, the fact that I don't know the NETCONF application 
is probably showing).

Response: There is the namespace to differentiate method names.
The NETCONF protocol has a fixed set of methods in the NETCONF
namespace.  The document is confusing because it calls standard
methods "protocol operations", but conceptually they are no
different than the "rock-the-house" type of <rpc>, which is
called a method in the draft.

====================================

[section 7.1, but it's related.  See the example at the bottom of p. 33; 
it's perfectly reasonable to have a chunk of device-specific XML in the 
answer to a query, but most XML language designers would require that it 
be in a different namespace, which would also sove the disambiguation 
problems.]

Response: The configuration data models are intended to be
in a different namespace than the NETCONF protocol.

In this example it is http://example.com/schema/1.2/config.

====================================

4.2 - the <data> element which appears here is not specified until 
section 7, a couple dozen pages later.

4.3 - similar contents for things like the content of <error-info>, how 
to maintain collisions between NETCONF-defined and device-defined content?

6.1 it says "XML subtree filtering is a mechanism that allows an 
application to
   select particular XML subtrees ".  XML subtrees of what?  I was 
genuinely baffled.  Then I guessed that the configuration datastores 
introduced in section 5 are in fact XML constructs and you're selecting 
out of them?  Or am I wrong.  Anyhow, some context is badly needed.

Response:  We will try to add clarifying text to provide better context.

======================================

If this were the W3C, this whole subtree-filtering section would be 
bounced instantly on the grounds that it seems to be re-inventing 
XPath.  Particularly since XPath is actually used in NETCONF, for 
<error-path> in 4.3, and then there's a whole section 8.9.

Maybe the requirements of this are app are such that it's sensible to 
re-invent something which has been widely implemented in a variety of 
free high-quality implementations in basically every computer language.

Sorry, I decline to study the details of yet another XML tree extraction 
mechanism.  This problem has been rather well solved, it escapes me why 
it needs to be done again.  Suffice it to say that designing this kind 
of thing is hard and it is very easy to specify things that turn out to 
have unforeseen high cost to implement.

Response:  There doesn't seem to be agreement on xml-dir on
this issue.  (One of them probably designed it ;-)  The WG
compromise is to use both XPATH and this lightweight subtree
thing.  Many in the WG (including me) believe that in time,
XPATH will not be a burden to implement in most embedded devices,
and we can make it mandatory-to-implement instead of optional.

======================================

Grr... section 6.4.4, yes this really smells like a half-baked 
reinvention of XPath.  Sorry for being rude in the case that I missed 
something obvious.

Response:  The section name is misleading because the subtree
filter doesn't really select nodes the same way as XPATH.

Summary:  The point of this subtree filtering is to
provide a very limited set of selection criteria.  XPATH has
way more features than our protocol requires.  The WG was
faced with essentially two choices:

  1) adopt something else that meets our needs
  2) standardize a specific subset of XPATH that meets our needs

The WG debated both approaches extensively and decided on (1).

==========================================

7.

It might be a good idea to reorder the doc and move this up above some 
other sections.  Having read this, I now know the basic high-level shape 
of the dialogue, and this gives context to things like the <data> 
element and the subtree filtering, that were introduced with no 
context.  Purely editorial.

<get-config source="running">

seems way smoother than

<get-config>
 <source>
  <running/>
 </source>

or, in the case where you can ask for more than one source:

<get-config>
 <source name="running"/>
 <source name="other"/>

Response:  I don't see a lot of agreement on this point.
In fact, most of the XML experts I know are saying
attributes are bad for parameters because of namespace issues
and lack of extensibility.

=======================================================

7.2 same comments regarding <edit-config><target><running/></target> - 
in this case the definition says that there's a single target, so why 
not use an attribute?

Basically, the conventional wisdom is that XML markup should label 
something, i.e. say what it is, while names usually go in content or 
attribute values.

Response: Again, I don't see agreement on xml-dir (or wider consensus)
that we should make more extensive use of attributes instead of
elements.

========================================================

There are a couple of problems with the URN+#+name naming scheme in 
section 8.  To start with, per RFC 2141, the #-fragment is not defined 
for URNs, in fact there's a SHOULD NOT.

Second, if you read 3986 and http://www.w3.org/TR/webarch, you'll 
discover that there's a lot of weirdness around #-fragments.  To start 
with, in principle URIs can be dereferenced, and the semantics of the 
#-fragment depend on the media type of what you get back.  Blecch.

It also occurs to me that if I were a device manufacturer and I wanted 
to publish device capabilities, I might want to name them with HTTP URIs 
so that you can actually dereference them to get details on the 
capability.  In which case the #-fragment is even more troubling.

Response:  The vendors are allowed to use friendly HTTP URIs.
We had that for netconf as well, but were told we were in
violation of some RFC because we didn't have extremely
verbose cryptic URNs instead (so we changed it).  I don't
care what the string is -- I just want the XML experts to
agree on something, or agree it's not worth worrying about.

===================================================

thanks,
Andy

--
to unsubscribe send a message to [email-masked] with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>