1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
4 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
17 Several CPS APIs use the cps-path (or cpsPath in Java API) parameter.
18 The CPS Path parameter is used for querying xpaths. CPS Path is insprired by the `XML Path Language (XPath) 3.1. <https://www.w3.org/TR/2017/REC-xpath-31-20170321/>`_
20 This section describes the functionality currently supported by CPS Path.
25 The xml below describes some basic data to be used to illustrate the CPS Path functionality.
30 <bookstore name="Chapters">
31 <bookstore-name>Chapters</bookstore-name>
32 <categories code="1" name="SciFi" numberOfBooks="2">
34 <book name="Space Odyssee"/>
38 <categories code="2" name="Kids" numberOfBooks="1">
40 <book name="Matilda"/>
46 **Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers
51 - String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
52 - String comparisons are case sensitive.
57 Get List Elements by Any Attribute Value
58 ----------------------------------------
60 **Syntax**: ``<xpath>/<target-node>[@<leaf-name>=<leaf-value>]``
61 - ``xpath``: The xpath to the parent of the target node including all ancestors.
62 - ``target-node``: The name of the (list) node which elements will queried.
63 - ``leaf-name``: The name of the leaf which value needs to be compared.
64 - ``leaf-value``: The required value of the leaf.
67 - ``/shops/bookstore/categories[@numberOfBooks=1]``
68 - ``/shops/bookstore/categories[@name="Kids"]``
69 - ``/shops/bookstore/categories[@name='Kids']``
72 - Only one list (last descendant) can be queried for a non-key value. Any ancestor list will have to be referenced by its key name-value pair(s).
73 - Only one attribute can be queried.
74 - Only string and integer values are supported (boolean and float values are not supported).
77 - 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.
82 **Syntax**: ``//<direct-ancestors><target-node>``
83 - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
84 - ``target-node``: The name of the (list) node from which element will be selected. If the target node is a Yang List he element needs to be specified using the key as normal e.g. ``categories[@code=1]``.
89 - ``//categories[@code=1]``
90 - ``//categories[@code=1]/books``
93 - List elements can only be addressed using the list key leaf.
95 Get Any Descendant by Any Attribute Value
96 -----------------------------------------
98 **Syntax**: ``//<direct-ancestors><target-node>[@<leaf-name>=<leaf-value>]``
99 - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
100 - ``target-node``: The name of the (list) node which elements will queried.
101 - ``leaf1-name .. leafN-name:``: One or more leaves whose value needs to be compared.
102 - ``leaf1-value .. leafN-value:``: One or more required leaf values (multiple condition can be combined using the 'and' keyword).
105 - ``//categories[@name='Kids']``
106 - ``//categories[@name='Kids' and @numberOfBooks=1]``
109 - Only string and integer values are supported (boolean and float values are not supported).
110 - Multiple attributes can only be combined using 'and'. 'or' and bracketing is not supported.
118 The ancestor axis can be added to any CPS path query.
120 **Syntax**: ``//<cps-path>/ancestor::<ancestor-path>``
121 - ``cps-path``: Any CPS path query.
122 - ``ancestor-path``: Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a /.
125 - ``//book/ancestor::categories``
126 - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
127 - ``book/ancestor::categories[@code=1]/books``
130 - Ancestor list elements can only be addressed using the list key leaf.
131 - List elements with compound keys are not supported.