CPS Path

Introduction

Several CPS APIs use the CPS path (or cpsPath in Java API) parameter. The CPS path parameter is used for querying xpaths. CPS path is inspired by the XML Path Language (XPath) 3.1.

This section describes the functionality currently supported by CPS Path.

Sample Data

The xml below describes some basic data to be used to illustrate the CPS Path functionality.

<shops>
   <bookstore name="Chapters">
      <bookstore-name>Chapters</bookstore-name>
      <categories code="1" name="SciFi" numberOfBooks="2">
         <books>
            <book title="2001: A Space Odyssey" price="5">
               <label>sale</label>
               <label>classic</label>
               <edition>1968</edition>
               <edition>2018</edition>
          </book>
            <book title="Dune" price="5">
               <label>classic</label>
               <edition>1965</edition>
            </book>
         </books>
      </categories>
      <categories code="2" name="Kids" numberOfBooks="1">
         <books>
            <book title="Matilda" />
         </books>
      </categories>
   </bookstore>
</shops>

Note. ‘categories’ is a Yang List and ‘code’ is its key leaf. All other data nodes are Yang Containers. ‘label’ and ‘edition’ are both leaf-lists.

General Notes

  • String values must be wrapped in quotation marks " (U+0022) or apostrophes ' (U+0027).

  • String comparisons are case sensitive.

  • List key-fields containing \ or @[ will not be processed correctly when being referenced with such key values in absolute or descendant paths. This means such entries will be omitted from any query result. See CPS-500 Special Character Limitations of cpsPath Queries

Query Syntax

( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <ancestor-axis> ]

Each CPS path expression need to start with an ‘absolute’ or ‘descendant’ xpath.

absolute-path

Syntax: '/' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*

  • container name: Any yang container or list.

  • list-key: One or more key-value pairs, each preceded by the @ symbol, combined using the and keyword.

  • The above van repeated any number of times.

Examples
  • /shops/bookstore

  • /shops/bookstore/categories[@code=1]

  • /shops/bookstore/categories[@code=1]/book

Limitations
  • Absolute paths must start with the top element (data node) as per the model tree.

  • Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.

descendant-path

Syntax: '//' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*

  • The syntax of a descendant path is identical to a absolute path except that it is preceded by a double slash //.

Examples
  • //bookstore

  • //categories[@code=1]/book

  • //bookstore/categories

Limitations
  • Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.

leaf-conditions

Syntax: <xpath> '[' @<leaf-name1> '=' <leaf-value1> ( ' and ' @<leaf-name> '=' <leaf-value> )* ']'
  • xpath: Absolute or descendant or xpath to the (list) node which elements will be queried.

  • leaf-name: The name of the leaf which value needs to be compared.

  • leaf-value: The required value of the leaf.

Examples
  • /shops/bookstore/categories[@numberOfBooks=1]

  • //categories[@name="Kids"]

  • //categories[@name='Kids']

  • //categories[@code=1]/book[@title='Dune' and price=5]

Limitations
  • Only the last list or container can be queried leaf values. Any ancestor list will have to be referenced by its key name-value pair(s).

  • Multiple attributes can only be combined using and. or and bracketing is not supported.

  • Only leaves can be used, leaf-list are not supported.

  • Only string and integer values are supported, boolean and float values are not supported.

Notes
  • For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath.

text()-condition

The text()-condition can be added to any CPS path query.

Syntax: <cps-path> ( '/' <leaf-name> '[text()=' <string-value> ']' )?
  • cps-path: Any CPS path query.

  • leaf-name: The name of the leaf or leaf-list which value needs to be compared.

  • string-value: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This wil still match integer values.

Examples
  • //book/label[text()="classic"]

  • //book/edition[text()="1965"]

Limitations
  • Only the last list or container can be queried for leaf values with a text() condition. Any ancestor list will have to be referenced by its key name-value pair(s).

  • Only one leaf or leaf-list can be tested.

  • Only string and integer values are supported, boolean and float values are not supported.

  • Since CPS cannot return individual leaves it will always return the container with all its leaves. Ancestor-axis can be used to specify a parent higher up the tree.

  • When querying a leaf value (instead of leaf-list) it is better, more performant to use a text value condition use @<leaf-name> as described above.

ancestor-axis

The ancestor axis can be added to any CPS path query but has to be the last part.

Syntax: <cps-path> ( '/ancestor::' <ancestor-path> )?
  • cps-path: Any CPS path query.

  • ancestor-path: Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a /.

Examples
  • //book/ancestor::categories

  • //categories[@genre="SciFi"]/book/ancestor::bookstore

  • book/ancestor::categories[@code=1]/books

  • //book/label[text()="classic"]/ancestor::shop

Limitations
  • Ancestor list elements can only be addressed using the list key leaf.

  • List elements with compound keys are not supported.