summaryrefslogtreecommitdiffstats
path: root/docs/cps-path.rst
blob: f321adfa9910572fb85127f5faf076c826b39787 (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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright (C) 2021-2022 Nordix Foundation

.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
.. _path:


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 inspired 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 Yang Model
=================

.. code-block::

  module stores {
      yang-version 1.1;
      namespace "org:onap:ccsdk:sample";

      prefix book-store;

      revision "2020-09-15" {
          description
            "Sample Model";
      }
      container shops {

          container bookstore {

              leaf bookstore-name {
                  type string;
              }

              leaf name {
                  type string;
              }

              list categories {

                  key "code";

                  leaf code {
                      type uint16;
                  }

                  leaf name {
                      type string;
                  }

                  leaf numberOfBooks {
                      type uint16;
                  }

                  container books {

                      list book {
                          key title;

                          leaf title {
                              type string;
                          }
                          leaf price {
                              type uint16;
                          }
                          leaf-list label {
                              type string;
                          }
                          leaf-list edition {
                              type string;
                          }
                      }
                  }
              }
          }
      }
  }

**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.

**Note.** CPS accepts only json data. The xml data presented here is for illustration purposes only.

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

Sample Data in Json
===================

.. code-block:: json

    {
      "shops": {
        "bookstore": {
          "bookstore-name": "Chapters",
          "name": "Chapters",
          "categories": [
            {
              "code": 1,
              "name": "SciFi",
              "numberOfBooks": 2,
              "books": {
                "book": [
                  {
                    "title": "2001: A Space Odyssey",
                    "price": 5,
                    "label": ["sale", "classic"],
                    "edition": ["1968", "2018"]
                  },
                  {
                    "title": "Dune",
                    "price": 5,
                    "label": ["classic"],
                    "edition": ["1965"]
                  }
                ]
              }
            },
            {
              "code": 2,
              "name": "Kids",
              "numberOfBooks": 1,
              "books": {
                "book": [
                  {
                    "title": "Matilda"
                  }
                ]
              }
            }
          ]
        }
      }
    }

Sample Data in XML
==================

.. code-block:: xml

    <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>

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 <https://jira.onap.org/browse/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']/books``
  - ``/shops/bookstore/categories[@code='1']/books/book[@title='2001: A Space Odyssey']``

**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']/books``
  - ``//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']/books/book[@title='Dune' and @price=5]``
  - ``//categories[@code=1]``
**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.
  - The key should be supplied with correct data type for it to be queried from DB. In the last example above the attribute code is of type
    Integer so the cps query will not work if the value is passed as string.
    eg: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string.
  - Having '[' token in any index in any list will have a negative impact on this function.

**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.
  - Having '[' token in any index in any list will have a negative impact on this function.

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[@code='2']/books/ancestor::bookstore``
  - ``//book/ancestor::categories[@code='1']/books``
  - ``//book/label[text()="classic"]/ancestor::shops``

**Limitations**
  - Ancestor list elements can only be addressed using the list key leaf.
  - List elements with compound keys are not supported.