XPath Capability

The XPath capability indicates that a device can use XPath expressions as filter criteria in the <filter> element, and the <get> and <get-config> operations can query specified data through an XPath.

XPath — XML Path Language — uses path expressions for the addressing of parts of an XML file. The XPath syntax is similar to the file path in the file management system.

XPath syntax specifications are as follows:

An XPath can only be an absolute path, and steps are separated using slashes (/), for example, /acl:acl/acl:groups/acl:group.
Only predicates in the [node name='value'] format (for example, [genre='Computer']) are supported. There can be multiple predicates, which are in an AND relationship.
XPath supports multiple namespaces, which are separated using colons.

If an XPath expression is used as a filter criterion, the value of the type attribute in the <filter> element is xpath, and the value of the select attribute (which must exist) is the XPath expression.

<filter type="xpath" xmlns:acl="urn:huawei:yang:huawei-acl" select="/acl:acl/acl:groups/acl:group[acl:identity='2000']"/>

XPath expressions cannot be used as filter criteria for such operations as notifications, full synchronization, incremental synchronization, or copy-config.

XPath expressions support the following operations:

Use the specified XPath as a filter criterion to query information about all nodes in the XPath.

For example, query information about all nodes in the /acl:acl/acl:groups/acl:group XPath of the <running/> configuration database.

RPC request

<?xml version="1.0" encoding="utf-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="19">
  <get-config>
    <source>
      <running/>
    </source>
    <filter xmlns:acl="urn:huawei:yang:huawei-acl" type="xpath"
            select="/acl:acl/acl:groups/acl:group"/>
  </get-config>
</rpc>

RPC reply

<?xml version="1.0" encoding="utf-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="6">
  <data>
    <acl xmlns="urn:huawei:yang:huawei-acl">
      <groups>
        <group>
          <identity>2000</identity>
          <type>basic</type>
          <match-order>config</match-order>
          <step>5</step>
        </group>
      </groups>
    </acl>
  </data>
</rpc-reply>

Use the value of a node in the specified XPath as a filter criterion to query information about the node that matches this value in the XPath.

For example, query information about the node for which "identity" is set to 2000 in the /acl:acl/acl:groups/acl:group XPath of the <running/> configuration database.

RPC request

<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <get-config>
    <source>
      <running/>
    </source>
    <filter type="xpath" xmlns:acl="urn:huawei:yang:huawei-acl" 
                         select="/acl:acl/acl:groups/acl:group[acl:identity='2000']"/>
  </get-config>
</rpc>

RPC reply

<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <data>
  <acl xmlns="urn:huawei:yang:huawei-acl">
      <groups>
        <group>
          <identity>2000</identity>
          <type>basic</type>
          <match-order>config</match-order>
          <step>5</step>
        </group>
      </groups>
    </acl>
  </data>
</rpc-reply>

Use two or more XPaths in the OR relationship as filter criteria to query information about the same node in all expressions.

For example, query information about the same node in the /nacm/rule-list/group and /nacm/rule-list/rule XPaths of the <candidate/> configuration database.

RPC request

<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <source>
      <candidate/>
    </source>
    <filter type="xpath" select="/t:nacm/t:rule-list/t:group | /t:nacm/t:rule-list/t:rule" xmlns:t="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
  </get-config>
</rpc>

RPC reply

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
    <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
      <rule-list>
        <name>list1</name>
        <group>group1</group>
        <rule>
          <name>rule11</name>
          <module-name>*</module-name>
          <access-operations>create read update delete</access-operations>
          <action>permit</action>
          <rpc-name>commit</rpc-name>
        </rule>
        <rule>
          <name>rule12</name>
          <module-name>*</module-name>
          <access-operations>read</access-operations>
          <action>deny</action>
          <rpc-name>edit-config</rpc-name>
        </rule>
      </rule-list>
      <rule-list>
        <name>list2</name>
        <group>group2</group>
        <rule>
          <name>rule21</name>
          <module-name>*</module-name>
          <access-operations>create read update delete</access-operations>
          <action>permit</action>
          <rpc-name>commit</rpc-name>
        </rule>
      </rule-list>
    </nacm>
  </data>
</rpc-reply>

Use the /* symbol as a filter criterion to query information about all nodes in the specified XPath (before the * symbol).

For example, you can query information about all nodes in the /nacm XPath of the <candidate/> configuration database.

RPC request

<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <source>
      <candidate/>
    </source>
    <filter type="xpath" select="/t:nacm/*" xmlns:t="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
  </get-config>
</rpc>

RPC reply

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
    <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
      <enable-nacm>false</enable-nacm>
      <read-default>deny</read-default>
      <write-default>deny</write-default>
      <exec-default>deny</exec-default>
      <groups>
        <group>
          <name>group1</name>
          <user-name>puneeth1</user-name>
          <user-name>puneeth2</user-name>
          <user-name>puneeth3</user-name>
        </group>
        <group>
          <name>group2</name>
          <user-name>puneeth1</user-name>
          <user-name>puneeth2</user-name>
          <user-name>puneeth3</user-name>
        </group>
      </groups>
      <rule-list>
        <name>list1</name>
        <group>group1</group>
        <rule>
          <name>rule11</name>
          <module-name>*</module-name>
          <access-operations>create read update delete</access-operations>
          <action>permit</action>
          <rpc-name>commit</rpc-name>
        </rule>
        <rule>
          <name>rule12</name>
          <module-name>*</module-name>
          <access-operations>read</access-operations>
          <action>deny</action>
          <rpc-name>edit-config</rpc-name>
        </rule>
      </rule-list>
    </nacm>
  </data>
</rpc-reply>

Use the pagination query function to query information about specified nodes. For <get-config> and <get> operations, this function supports the optional expression [position() >= a and position() <= b] in the XPath to query the data of list/leaf-list nodes in the specified range [a, b].
- You can specify the left and right boundaries, which are interchangeable, for the pagination query.
  For example, either of the following expressions is used to query the data of nodes 1 to 100 on the list node interface.
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() >= 1 and position() <= 100] "
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() <= 100 and position() >= 1] "
- You can specify the same left and right boundary values for the pagination query. If they are the same, the query range is a fixed value rather than a value range.
  For example, the following expression is used to query the data of the first node on the list node interface.
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() >= 1 and position() <= 1] "
- You can specify only one boundary (left or right) for the pagination query. If only the left boundary is specified, the data of the specified node and all the subsequent nodes is queried. Conversely, if only the right boundary is specified, the data of node 1 to the specified node is queried.
  For example, the first of the following two expressions is used to query the data of node 100 and all the subsequent nodes on the list node interface, and the second expression is used to query the data of nodes 1 to 200 on the list node interface.
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() >= 100] "
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() <= 200] "
- The pagination query function verifies whether the specified query range meets the following conditions:
  - The left boundary value is less than or equal to the right boundary value.
  - The left and right boundary values are integers ranging from 1 to 1000000000. If the left boundary of the specified query range exceeds the actual number of data records to be queried, no query result is displayed.
- The pagination query function supports query based on multiple filter criteria, meaning that each query can contain more than one filter criterion.
  For example, the following expression contains two filter criteria, indicating that the GE port data of nodes 1 to 100 is queried.
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[ifm:type='gigabitethernet'][position() >= 1 and position()<= 100]"
- Only the list and leaf-list nodes support the pagination query function, and no other node can follow the expression position().
  For example:
  
  select="/ifm:ifm/ifm:interfaces/ifm:interface[position() >= 1 and position() <= 100] "
  
  In the preceding expression, the node interface is a list node, and the expression [position() >= 1 and position() <= 100] is not followed by another node.
- Multiple position() parameters cannot be combined by the OR symbol (|) to deliver the pagination query operation. To query different services, you must therefore deliver the pagination query operations separately.
- If a user sends two pagination query requests at a maximum interval of 3 minutes, the entered XPaths are the same (same prefix, namespace, and node), and the input numbers for the pagination query are consecutive, the device considers the later query request as part of the first one and preferentially obtains the data to be queried from the cache. If the input numbers for pagination query are not consecutive or the interval between two requests exceeds 3 minutes, the later query operation is processed as a new request. The queried content is obtained from the device configuration database.
  For example:
  - A user delivers two pagination query requests within 3 minutes. The first queries the content of nodes 1 to 100 of a specified list/leaf-list node, and the second queries the content of nodes 101 to 200 of the same XPath. If the device configuration changes at any time between the two query operations, the data queried by the user is the data before the change, that is, the data in the cache.
  - If a user delivers two pagination query requests (with the first querying the content of nodes 1 to 100 and the second querying the content of nodes 301 to 400) and the device configuration changes at any time between the two query operations, the pre-change data is obtained for the first request and the post-change data is obtained for the second. This is true regardless of whether the interval between the two requests exceeds 3 minutes.
  - The same XPath indicates that the prefixes, namespaces, and nodes are identical. If one of them is different, the queries are considered to be different. For example, the XPath prefixes of the following two expressions are considered different, meaning that the device processes them as two independent requests.
    select="/t:ifm/t:interfaces/t:interface[position() >= 1 and position()<= 100]"
    
    select="/l:ifm/l:interfaces/l:interface[position() >= 101 and position()<= 200]"
  During packet delivery, the greater-than sign (>) and less-than sign (<) in the position() expression must be represented by the escape characters > and <.
For example, query information about the first and second NACM authentication user groups in the <running/> configuration database.
- RPC request
```
<?xml version="1.0" encoding="utf-8"?>
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="827">
 <get-config>
  <source>
    <running/>
  </source>
  <filter xmlns:t="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" type="xpath"
          select="/t:nacm/t:groups/t:group[position()&gt;=1 and position()&lt;=2]"/>
 </get-config>
</rpc>
```
- RPC reply
```
<?xml version="1.0" encoding="utf-8"?>
<data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
    <groups>
      <group>
        <name>1</name>
        <user-name>test1</user-name>
        <user-name>test2</user-name>
        <user-name>test3</user-name>
        <user-name>test4</user-name>
      </group>
      <group>
        <name>2</name>
        <user-name>test1</user-name>
        <user-name>test2</user-name>
        <user-name>test3</user-name>
      </group>
    </groups>
  </nacm>
</data>
```