Paths

Clixon uses paths to navigate in trees. Clixon uses the following three methods:

All three use similar notations to find a path in tree, such as a/b, but differ in some ways.

XPath

Example of XPath in a NETCONF get-config RPC using the XPath capability:

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   <get-config>
      <source>
         <candidate/>
      </source>
      <filter type="xpath" select="/interfaces/interface[name='eth0']/description" />
   </get-config>
</rpc>

XPath is a powerful language for addressing parts of an XML document, including types and expressions. The following is a valid but complex XPath:

/assembly[name="robot_4"]//shape/name[containts(text(),'bolt')]/surface/roughness

Clixon uses XPaths extensively due to their expressive power. However, it is recommended to use instance-identifiers instead if you want optimized access.

Namespaces

XPath uses XML names, requiring an XML namespace context using the xmlns attribute to bind namespaces and prefixes. An XML namespace context can specify both:

  • A default namespace for unprefixed names (/x/), defined by for example: xmlns=”urn:example:default”.
  • An explicit namespace for prefixed names prefix (/ex:x/), defined by for example: xmlns:ex=”urn:example:example”.

Further, XML prefixes are not inherited, each symbol must be prefixed with a prefix or default. That is, /ex:x/y is not the same as /ex:x/ex:y, unless ex is also default.

Example: Assume an XML namespace context:

<a xmlns="urn:example:default" xmlns:ex="urn:example:example">

with an associated XPath:

/x/ex:y/ex:z[ex:i='w']`,

then symbol x belongs to “urn:example:default” and symbols y, z and i belong to “urn:example:example”.

Instance-identifier

Instance-id:s are defined in YANG for some minor usage but appears in for example NACM and provides a useful subset of XPath. The subset is as follows (see Section 9.13 in YANG 1.1):

  • Child paths using slashes: /ex:system/ex:services
  • List entries for one or several keys: /ex:system[ex:ip='192.0.2.1'][ex:port='80']
  • Leaf-list entries for one key: /ex:system/ex:cipher[.='blowfish-cbc']
  • Position in lists: /ex:stats/ex:port[3]

Example of instance-id in NACM:

<path xmlns:acme="http://example.com/ns/itf">
      /acme:interfaces/acme:interface[acme:name='dummy']
</path>

Namespaces in instance-identifiers are the same as in XPaths.

Api-path

RESTCONF defines api-paths as a YANG-based path language. Keys are implicit which make path expressions more concise, but they are also less powerful

Example of Api-path in a restconf GET request:

curl -s -X GET http://localhost/restconf/data/ietf-interfaces:interfaces/interface=eth0/description

Clixon uses Api-paths internally in some cases when accessing xml keys, but more commonly translates Api-paths to XPaths.

Api-path is in comparison to XPaths limited to pure path expressions such as, for example:

a/b=3,4/c

which corresponds to the XPath: a[i=3][j=4]/c. Note that you cannot express any other index variables than the YANG list keys.

Namespaces

In contrast to XPath, Api-path namespaces are defined implicitly by a YANG context using module-names as prefixes. The namespace is defined in the Yang module by the namespace keyword. Api-paths must have a Yang definition whereas XPaths can be compeletely defined in XML.

A prefix/module-name is inherited, such that a child inherits the prefix of a parent, and there are no defaults. For example, /moda:x/y is the same as /moda:a/moda:y.

Further, an Api-path uses a shorthand for defining list indexes. For example, /modx:z=w denotes the element in a list of z:s whose key is the value w. This assumes that z is a Yang list (or leaf-list) and the index value is known.

Example: Assume two YANG modules moda and modx with namespaces “urn:example:default” and “urn:example:example” respectively, with the following Api-path (equivalent to the XPath example above):

/moda:x/modx:y/z=w

where, as above, x belongs to “urn:example:default” and y, and z belong to “urn:example:example”.