Subject: Re: [netmod] XPath document root

From: Martin Bjorklund <[email-masked]>
Date: Mon, 05 Jan 2009 13:00:25 +0100 (CET)

Hi,

How about adding new text after:

   The XPath expression is conceptually evaluated in the following
   context:

   o  The context node is the node in the data tree for which the "must"
      statement is defined.

   o  The accessible tree is made up of all nodes in the data tree, and
      all leafs with default values.

   ...

NEW:

   The accessible data tree depends on the context node:

   o  If the context node represents configuration, the tree is the data
      in one of the datastores <startup/>, <running/>, or <candidate/>.

   o  If the context node represents state data, the tree is all state
      data on the device, and the <running/> datastore.

   o  If the context node represents notification content, the tree is
      the notification XML instance document, with the root node being
      the element representing the notification.

   o  If the context node represents RPC input parameters, the tree is
      the RPC XML instance document, with the root node being the
      element representing the RPC method.

   o  If the context node represents RPC output parameters, the tree is
      the RPC reply instance document, with the root node being the
      <rpc-reply> element.

This would be added to the must and when sections.

Do we need more text?

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

---

From: "tom.petch" <[email-masked]>
Date: Tue, 6 Jan 2009 12:11:00 +0100

----- Original Message -----
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>
Sent: Monday, January 05, 2009 1:00 PM
Subject: Re: [netmod] XPath document root

> This would be added to the must and when sections.
I am struggling with this.  To me, the root node is the one above everything; to
quote the usual source,

"The root node is the root of the tree. A root node does not occur except as the
root of the tree. The element node for the document element is a child of the
root node. The root node also has as children processing instruction and comment
nodes for processing instructions and comments that occur in the prolog and
after the end of the document element."

so are the references to root node (in notification, RPC input, RPC output)
really to the root node or to the document element node that is under the root
node?

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 07 Jan 2009 10:32:46 +0100 (CET)

> really to the root node or to the document element node that is under the root

The references are to the root node, with the definition you quoted.

For example:

  notification event {
      leaf eventClass { ... }
      container reportingEntity { ... }
      leaf severity { 
          must "/eventClass != 'xxx'";    // absolute path
          ...
      }
  }

An instance document could be:

   <notification
      xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
      <eventTime>2007-07-08T00:01:00Z</eventTime>
      <event xmlns="http://example.com/event/1.0">  <!-- root node -->
         <eventClass>fault</eventClass>
         <reportingEntity>
             <card>Ethernet0</card>
         </reportingEntity>
         <severity>major</severity>
       </event>
   </notification>

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 11:09:04 +0100

> really to the root node or to the document element node that is under the root
This is one of the messy parts in XML. In XML 1.0, root element is the
same as document element, XPath 1.0 (which is what you probably cite)
has the root node concept, and XPath 2.0 and XQuery uses "document node"
meaning the same thing as "root node" in XPath 1.0.

The YANG draft should clarify this in the Terminology section and also
elsewhere in a more verbose form.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 11:21:55 +0100

>           must "/eventClass != 'xxx'";    // absolute path

Hmm, this is confusing, IMO the root node (following the terminology of
XPath 1.0) is the invisible location just above <event>, so the XPath
expression should read "/event/eventClass != 'xxx'" (modulo my standard
complaint about null namespace).

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 07 Jan 2009 13:44:22 +0100 (CET)

> complaint about null namespace).

Well, it's up to us to define this.  In my proposal, I defined it to
be the event node itself.  The reason was consistency with rpc
parameters:

  rpc foo {
    input {
      leaf a { ... }
      leaf b {
        must "/a != '1'";
        ...
      }
    }
    output {
      leaf c { ... }
      leaf d { 
        must "/c != '2'";
        ...
      }
    }
  }

  <rpc>
    <foo>         <!-- root node -->
      <a>...</a>
      <b>...</b>
    </foo>
  </rpc>

  <rpc-reply>      <!-- root node -->
    <c>...</c>
    <d>...</d>
  </rpc-reply>

/martin

---

From: Andy Bierman <[email-masked]>
Date: Wed, 07 Jan 2009 05:00:14 -0800

> be the event node itself.  The reason was consistency with rpc

I agree with Martin.
The document roots need to be defined this way
to keep the must/when expressions constrained to
a single XML document (PDU).

This applies to keyref expression too?
That's where it is getting really confusing
and complicated to implement.

Why do we need keyrefs that point inside /rpc/input,
/rpc/output, or /notification?

IMO, keyref should always point at the database,
so the docroot (/) is always associated with the <config> node.

>   <rpc-reply>      <!-- root node -->

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 14:38:36 +0100

> be the event node itself.  The reason was consistency with rpc

The notification statement is in fact a minischema for a separate tree
that clearly has "event" as its root *element* and this element is
defined within the minischema. The root node of XPath 1 is a virtual
entity that does not appear in the XML document at all.

The problem again is that XPath was designed to address parts of an XML
document but here it is hard to tell what the document really is.

Given all the deviations from standard XPath, YANG should perhaps define
its own expressions (YPath?) to avoid confusion.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Phil Shafer <[email-masked]>
Date: Wed, 7 Jan 2009 08:42:33 -0500

>be the event node itself.  The reason was consistency with rpc

All XPath expressions should be relative to the "document"
being shipped as payload inside the NETCONF constructs.  For RPCs,
this means the "root node" is the contents of the <rpc> element,
for notifications, it's the contents of the <notication> element,
and for configuration data, it's the contents of the <config>
element.

The only inconsistency is WRT RPC output, where the rpc name does

>        must "/a != '1'";

"/foo/a != 1" here, but ...

>        must "/c != '2'";

this is "/c != 2" instead of "/foo/c".

This is consistent within the payload, but is confusing in the YANG,
since input has the rpc name and output does not.

Thanks,
 Phil

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 15:11:45 +0100

> and for configuration data, it's the contents of the <config>

I agree with this.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Wed, 07 Jan 2009 06:17:02 -0800

...
> its own expressions (YPath?) to avoid confusion.

The problem is that we are trying to use XPath to
make NETMOD more useful and easier to use,
and there is not always agreement on what that means.

The main dynamic seems to be the view that a NETCONF database
is not n XML document, so various rules in XPath which seem
to get in the way can be implementation-dependent instead
of standard.  (E.g., sec. 5 clearly states which node types
have implementation-specific ordering and which don't.)

I am partially concerned that the IESG will not accept
either NETMOD's adaptation of XPath or something else
called YPath.

Only partially, because I understand that automation
is the way of the future, whether the XPath is 'pure' or not.
Every manager should understand this.  You really want
your 'A team' data model designers putting as much
machine-readable semantics into the YANG file as possible,
especially when the most likely alternative is to
have N junior platform engineers each attempt to interpret
complicated description clauses correctly and consistently.

All of the 'changes' to XPath have been to make it easier
to use by NM-OPS people.  Lower complexity means a lower
rate of 'pilot errors' introduced into the managed system.
(I hope the IESG sees it that way.)

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 7 Jan 2009 09:29:52 -0500

>have implementation-specific ordering and which don't.)

Would this be acceptable:

   YANG's use of XPATH refers to a NETCONF database and the XML
   document that an implementation generates from it.  Where the
   order of that DB->XML ordering has no impact on the configuration
   content, the implementation is free to use an ordering that is
   natural and optimal.  XPath expressions should not include
   dependencies on ordering issues that are not meaningful to the
   configuration content.

   The order in which non-key elements appear within a parent element
   is not specified, allowing implementations to generate this data
   in a natural and optimal way.  No client, server, or XPath
   expression should depend on the order being fixed.

   For example, a module may define a list of user with a name leaf
   as a key, along with a uid, home directory, and shell.  Another
   module may augment this with an expiration time for the account.
   The only constraint placed on the order in which these elements
   appear within the user element is that the key must appear first.
   The order of the other elements, both the initial and augmented
   leafs, is not defined.

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 07 Jan 2009 15:43:53 +0100 (CET)

> its own expressions (YPath?) to avoid confusion.

I don't agree that we define many deviations from standard XPath.

Regarding this particulat issue, the XPath 1.0 spec says:

    XPath operates on the abstract, logical structure of an XML
    document, rather than its surface syntax.

We must of course specify what the (conceptual) XML document that our
XPath expressions operate on look like.  Just b/c NETCONF encodes its
PDUs in XML does not mean that the instance document that the XPath
expressions operate on is the complete NETCONF PDU.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 07 Jan 2009 15:48:49 +0100 (CET)

Phil Shafer <[email-masked]> wrote:
>    in a natural and optimal way.

This would close the door on mapping to XSD.  XSD cannot validate such
flexible ordering.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 16:37:59 +0100

> I don't agree that we define many deviations from standard XPath.

Apart from this root node issue, I see the redefinition of null
namespace as a deviation (or dirty trick at least), and then the
restrictions wrt sibling order - no indexing, probably also the
following-sibling:: and preceding-sibling:: axes, position() and last()
functions.

On the other hand, with YPath we could also get rid of the canonical
forms of datatypes and simply work everywhere with value space values.

>     document, rather than its surface syntax.

Yes, this means that it doesn't work with serialized XML, but the XML
document concept is nonetheless there.

> expressions operate on is the complete NETCONF PDU.

I understand that, but outside of PDUs the notion of an "XML document"
is IMO still quite vague. For example: Does the datastore XML document
contain the elements for configuration values that were not set by the
manager? What about multiple root elements?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 16:40:33 +0100

> This would close the door on mapping to XSD.  XSD cannot validate such

XSD is not in the charter, so it shouldn't be a sine qua non condition.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 07 Jan 2009 16:46:36 +0100 (CET)

> following-sibling:: and preceding-sibling:: axes, position() and last()

But we're not saying that these functions won't work, we're just
saying that since the order is implementation dependant, you cannot
rely on the order being the same accross implementations.

IMO, the only thing that is a bit unclear is if XPath allows multiple
nodes as children to the root node.

/martin

---

From: Phil Shafer <[email-masked]>
Date: Wed, 7 Jan 2009 11:02:39 -0500

>This would close the door on mapping to XSD.  XSD cannot validate such

It's a trade off; we trade flexibility for ordering with a loss of
the {0,1} test.  This is what we did for JUNOS and it's worked fine.

Thanks,
 Phil

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 17:15:15 +0100

> nodes as children to the root node.

It sure does, comments, PIs - but only one element node.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 17:34:04 +0100

>    document that an implementation generates from it.  Where the

Notifications and RPCs are not part of this database.

>    natural and optimal.  XPath expressions should not include

Does it address ordering in both internal datastores and PDUs?

>    expression should depend on the order being fixed.

Except perhaps list items ordered by user.

>    The order of the other elements, both the initial and augmented

How about this:

leaf a { ... }
leaf-list b { ... }

Is <b>...</b><a>...</a><b>...</b> legal or not?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: "tom.petch" <[email-masked]>
Date: Wed, 7 Jan 2009 16:35:48 +0100

--- Original Message -----
From: "Ladislav Lhotka" <[email-masked]>
To: "Phil Shafer" <[email-masked]>
Cc: <[email-masked]>
Sent: Wednesday, January 07, 2009 3:11 PM
Subject: Re: [netmod] XPath document root

> > and for configuration data, it's the contents of the <config>

Weelll sort of.  XPath 1.0 s.5 (which I quoted) does clearly differentiate root
node from element node so I preferred Lada's earlier characterisation
'The root node of XPath 1 is a virtual
entity that does not appear in the XML document at all.'  XPath 1.0 has an
associated datamodel (in s.5).  Some parts of XPath 1.0 I am happy to bend
(floating point:-) but I think the datamodel fundamental to its working and that
we need to be very careful about modifying it.

But I do see us as free to define what our 'XML document' is and then place the
root node of the XPath datamodel invisibly above the document node.  Or else we
make it clear that we are departing from the language of XPath 1.0 with copious
examples so that our choice of terms becomes immaterial.

In passing, RFC5277 says

"An event notification is a complete and well-formed XML
      document.  Note that <notification> is not a Remote Procedure Call
      (RPC) method but rather the top-level element identifying the one-
      way message as a notification."

which for me places the invisible root above <notification>

Tom Petch

---

From: Andy Bierman <[email-masked]>
Date: Wed, 07 Jan 2009 08:51:40 -0800

> It sure does, comments, PIs - but only one element node.

Well, this is not how we want to view a configuration database.
All of our examples use 1 of N top-level elements within a
module as the children of the document root.

e.g., must 'count(/if:interfaces/if:interface) +
             count(/acme:servers/acme:server') > 1';

Where is this rule defined in XPath?
I think the last paragraph of 5.0 in XPath conflicts
with the the first paragraph of 5.1:

5.0:
   Every node other than the root node has exactly one parent,
   which is either an element node or the root node.

5.1:
   The element node for the document element is a child of the
   root node.

5.1 says 'The', not 'An'.  But 5.0 just says nodes have 1 parent.
That does not mean the root has 1 child.

IMO, all the little differences and caveats in XPath are getting
too complicated too remember.  A table somewhere would
help, summarizing all of them.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 17:58:38 +0100

Martin Bjorklund píše v St 07. 01. 2009 v 17:45 +0100:
> Where is it stated that there can be only one element node?

Sec. 5.1 of XPath 1.0: "The element node for the document element is a
child of the root node." It's "a child" since there can be other
children but "the element node for the document element" means there is
exactly one. This of course follows also from XML 1.0 spec.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Wed, 07 Jan 2009 09:15:25 -0800

> exactly one. This of course follows also from XML 1.0 spec.

What if we said that for database XPath expressions,
the document root '/' was a shorthand for /nc:config,
when converting the XPath to be applied to an
external representation (XML doc).  We already
know we need a common top-level element for <copy-config>
to be inter-operable.  We have one -- <nc:config>.

If every single DB expression must begin with /nc:config,
then in reality, none of them do.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 07 Jan 2009 18:23:42 +0100

> module as the children of the document root.

Document root is not the same as root node in XPath. Multiple top-level
containers do not map to a valid XML document - a common parent must be
added, either from the NETCONF vocabulary, or artificial (that's what I
propose for the mapped DSDL).

> with the the first paragraph of 5.1:

Why? The root node has one element node and perhaps other non-element
nodes (comments, PIs) as children. And element nodes can also have
children nodes - other elements, attributes, comments, PIs and text
nodes.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: "tom.petch" <[email-masked]>
Date: Wed, 7 Jan 2009 20:07:06 +0100

----- Original Message -----
From: "Ladislav Lhotka" <[email-masked]>
To: "Andy Bierman" <[email-masked]>
Cc: <[email-masked]>
Sent: Wednesday, January 07, 2009 6:23 PM
Subject: Re: [netmod] XPath document root

> Document root is not the same as root node in XPath.

yes, yes and yes again.  I prefer 'document root element' or some permutation
thereof to stress the difference between the root of the document and the
(virtual) root node - which is not an element node - that is particular to the
XPath 1.0 data model.

The way I think of it, if that virtual node was not there, then you could not
use XPath as a selector for the whole of the document, you would have to start
one level down - or else you would have to change the concept of what a root is.

Multiple top-level
> children nodes - other elements, attributes, comments, PIs and text
and again, yes

Tom Petch