XPath Reference

The XPath 1.0 path specification language is supported in all YumaPro Tools programs, as specified in the YANG language specification. There are also some additional variables and XPath functions, available in all XPath expressions.

A custom XPath implementation is used, which is based on the internal data structures maintained within the program (i.e., object tree or data tree). No CPU or memory is wasted converting these data structures to actual XML documents for XPath processing.

XPath 1.0

All functionality defined in the XPath 1.0 specification is supported.

There are some restrictions, which are specific to the YANG standard:

  • The 'attribute' and 'processing-instruction' axes are always empty.

  • YANG identityref leaf values need to be entered within quotes or they will be interpreted as XML qualified node names.

  • The server may not maintain consistent XML document order for system-ordered data. This affects expressions which rely on XML document order to be precise and completely static. A NETCONF server is only required to maintain XML document order for user-ordered lists and leaf-lists, and only relative to a particular object, not the entire document.

XML Namespaces

The XPath implementation allows a more liberal syntax than the XPath 1.0 specification allows. Refer to section 4.6 of RFC 8407 for XPath usage guidelines.

Note

If XML namespaces are used, they must be used correctly.

Example request using XML namespaces in an XPath expression:

 <?xml version="1.0" encoding="UTF-8"?>
 <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    message-id="2"
    xmlns:sys="http://netconfcentral.org/ns/yuma-system">
    <nc:get>
       <nc:filter type="xpath" select="/sys:system"/>
    </nc:get>
 </nc:rpc>

Note the text with the "sys" prefix which is defined by the "xmlns:sys" attribute. This 'xmlns' attribute does not have to appear exactly as specified, or within the <rpc> element. It can appear in any legal manner. Refer to the XML Namespaces 1.0 specification for more details.

Example request not using XML namespaces in an XPath expression:

 <?xml version="1.0" encoding="UTF-8"?>
 <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    message-id="3">
    <nc:get>
       <nc:filter type="xpath" select="/system"/>
    </nc:get>
 </nc:rpc>

YANG Specific XPath Behavior

The YANG language requires some minor changes and additions to the XPath 1.0 specification:

  • The 'current' function from XPath 2.0 is supported.

  • The NULL XML namespace is mapped to the current YANG module XML namespace, when processing an XPath expression within a YANG module (e.g., must statement).

  • A NETCONF database is treated as a conceptual XML instance document with zero or more top-level elements. This is consistent with XSLT behavior. XML 1.0 requires a single top-level element,so external XML documents representing a NETCONF database always start with the <nc:config> element (config element in the NETCONF XML namespace).

Custom XPath Variables

The XPath specification supports system variables to be accessed within XPath expressions.

Within the yangcli-pro program, all user and system variables available to a script are also available as XPath variables within XPath expression evaluation (e.g., if, eval, and while commands).

For example, a variable named 'myvar' would be accessed within an XPath expression as '$myvar'.

user

An XPath variable called 'user' is supported in the yangcli-pro and netconfd-pro programs. It is equal to the NETCONF user name associated with the session evaluating the XPath expression. It is provided to be used in data rules within the NETCONF Access Control Model (NACM).

Custom XPath Functions

The following XPath functions are added to the XPath 1.0 Function Library, in addition to the 'current' function from XPath 2.0.

module-loaded

The module-loaded function tests whether the specified module is loaded within the program.

boolean module-loaded (module-name [, revision-date])

Parameters:

  • Parameter 1:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the module name to check.

  • Parameter 2:

    • Type: String

    • Usage: Optional

    • Purpose: Specifies the YANG revision date string for module indicated by parameter 1.

Returns: Boolean

  • true: the specified module is loaded

  • false: the specified module is not loaded, possibly not known

Errors:

  • Missing parameter error if no parameters provided.

  • Extra parameters error if more than 2 parameters provided.

  • All unknown parameter values cause a 'false' result.

Example:

yangcli-pro> if "module-loaded('yuma-system', '2009-12-27')"
yangcli-pro> log-info 'correct yuma-system module loaded'
yangcli-pro> else
yangcli-pro> log-error 'Wrong yuma-system module loaded'
yangcli-pro> end

feature-enabled

The feature-enabled function tests whether the specified YANG feature is enabled within the program.

boolean feature-enabled (module-name, feature-name)

Parameters:

  • Parameter 1:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the module name to check.

  • Parameter 2:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the YANG feature name defined within the module indicated by parameter 1.

Returns: Boolean

  • true: the specified feature is enabled

  • false: the specified feature is not enabled, possibly not known

Errors:

  • Missing parameter error if less than 2 parameters provided.

  • Extra parameters error if more than 2 parameters provided.

  • All unknown parameter values cause a 'false' result.

Example:

yangcli-pro> if "feature-enabled('mymodule', 'myfeature')"
yangcli-pro> log-info 'myfeature is enabled'
yangcli-pro> else
yangcli-pro> log-error 'myfeature is not enabled'
yangcli-pro> end