Hi,
I would like the XML Directorate to review the NETCONF Protocol draft
for any XML issues. The current version is:
draft-ietf-netconf-prot-06.txt
This protocol provides network configuration features and uses XML
encoding.
Comments:
1.
[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."
3.1 a URN is a URI, so sentence needs work.
3.2 DTD does not stand for Document Type Declaration. The statement
makes sense (no Document Type Declaration) but the "(DTDs)" should be
removed.
4.1
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)
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).
[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.]
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.
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.
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.
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"/>
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.
[Section 8 is largely unreviewed as it's very app-specific]