blob: aec87cd4362c76e22ae4d12d84bdea2b65b77b17 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
.. _design:
CPS Path
########
.. toctree::
:maxdepth: 1
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 insprired by the `XML Path Language (XPath) 3.1. <https://www.w3.org/TR/2017/REC-xpath-31-20170321/>`_
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.
.. code-block:: xml
<shops>
<bookstore name="Chapters">
<bookstore-name>Chapters</bookstore-name>
<categories code="1" name="SciFi" numberOfBooks="2">
<books>
<book name="Space Odyssee"/>
<book name="Dune"/>
</books>
</categories>
<categories code="2" name="Kids" numberOfBooks="1">
<books>
<book name="Matilda"/>
</books>
</categories>
</bookstore>
</shops>
**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers
General Notes
=============
- String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
- String comparisons are case sensitive.
Supported Queries
=================
Get List Elements by Any Attribute Value
----------------------------------------
**Syntax**: ``<xpath>/<target-node>[@<leaf-name>=<leaf-value>]``
- ``xpath``: The xpath to the parent of the target node including all ancestors.
- ``target-node``: The name of the (list) node which elements will 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]``
- ``/shops/bookstore/categories[@name="Kids"]``
- ``/shops/bookstore/categories[@name='Kids']``
**Limitations**
- 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).
- Only one attribute can be queried.
- 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.
Get Any Descendant
------------------
**Syntax**: ``//<direct-ancestors><target-node>``
- ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
- ``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]``.
**Examples**
- ``//book``
- ``//books/book``
- ``//categories[@code=1]``
- ``//categories[@code=1]/books``
**Limitations**
- List elements can only be addressed using the list key leaf.
Get Any Descendant by Any Attribute Value
-----------------------------------------
**Syntax**: ``//<direct-ancestors><target-node>[@<leaf-name>=<leaf-value>]``
- ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
- ``target-node``: The name of the (list) node which elements will queried.
- ``leaf1-name .. leafN-name:``: One or more leaves whose value needs to be compared.
- ``leaf1-value .. leafN-value:``: One or more required leaf values (multiple condition can be combined using the 'and' keyword).
**Examples**
- ``//categories[@name='Kids']``
- ``//categories[@name='Kids' and @numberOfBooks=1]``
**Limitations**
- Only string and integer values are supported (boolean and float values are not supported).
- Multiple attributes can only be combined using 'and'. 'or' and bracketing is not supported.
Query Extensions
================
Ancestor Axis
-------------
The ancestor axis can be added to any CPS path query.
**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``
**Limitations**
- Ancestor list elements can only be addressed using the list key leaf.
- List elements with compound keys are not supported.
|
