docs/cps-path.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2021-2023 Nordix Foundation
   4 .. Modifications Copyright (C) 2023 TechMahindra Ltd
   5
   6 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   7 .. _path:
   8
   9
  10 CPS Path
  11 ########
  12
  13 .. toctree::
  14    :maxdepth: 1
  15
  16 Introduction
  17 ============
  18
  19 Several CPS APIs use the CPS path (or cpsPath in Java API) parameter.
  20 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/>`_
  21
  22 This section describes the functionality currently supported by CPS Path.
  23
  24 Sample Yang Model
  25 =================
  26
  27 .. code-block::
  28
  29   module stores {
  30       yang-version 1.1;
  31       namespace "org:onap:ccsdk:sample";
  32
  33       prefix book-store;
  34
  35       revision "2020-09-15" {
  36           description
  37             "Sample Model";
  38       }
  39       container shops {
  40
  41           container bookstore {
  42
  43               leaf bookstore-name {
  44                   type string;
  45               }
  46
  47               leaf name {
  48                   type string;
  49               }
  50
  51               list categories {
  52
  53                   key "code";
  54
  55                   leaf code {
  56                       type uint16;
  57                   }
  58
  59                   leaf name {
  60                       type string;
  61                   }
  62
  63                   leaf numberOfBooks {
  64                       type uint16;
  65                   }
  66
  67                   container books {
  68
  69                       list book {
  70                           key title;
  71
  72                           leaf title {
  73                               type string;
  74                           }
  75                           leaf price {
  76                               type uint16;
  77                           }
  78                           leaf-list label {
  79                               type string;
  80                           }
  81                           leaf-list edition {
  82                               type string;
  83                           }
  84                       }
  85                   }
  86               }
  87           }
  88       }
  89   }
  90
  91 **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.
  92
  93 **Note.** CPS accepts only json data. The xml data presented here is for illustration purposes only.
  94
  95 The json and xml below describes some basic data to be used to illustrate the CPS Path functionality.
  96
  97 Sample Data in Json
  98 ===================
  99
 100 .. code-block:: json
 101
 102     {
 103       "shops": {
 104         "bookstore": {
 105           "bookstore-name": "Chapters",
 106           "name": "Chapters",
 107           "categories": [
 108             {
 109               "code": 1,
 110               "name": "SciFi",
 111               "numberOfBooks": 2,
 112               "books": {
 113                 "book": [
 114                   {
 115                     "title": "2001: A Space Odyssey",
 116                     "price": 5,
 117                     "label": ["sale", "classic"],
 118                     "edition": ["1968", "2018"]
 119                   },
 120                   {
 121                     "title": "Dune",
 122                     "price": 5,
 123                     "label": ["classic"],
 124                     "edition": ["1965"]
 125                   }
 126                 ]
 127               }
 128             },
 129             {
 130               "code": 2,
 131               "name": "Kids",
 132               "numberOfBooks": 1,
 133               "books": {
 134                 "book": [
 135                   {
 136                     "title": "Matilda"
 137                   }
 138                 ]
 139               }
 140             }
 141           ]
 142         }
 143       }
 144     }
 145
 146 Sample Data in XML
 147 ==================
 148
 149 .. code-block:: xml
 150
 151     <shops>
 152        <bookstore name="Chapters">
 153           <bookstore-name>Chapters</bookstore-name>
 154           <categories code=1 name="SciFi" numberOfBooks="2">
 155              <books>
 156                 <book title="2001: A Space Odyssey" price="5">
 157                    <label>sale</label>
 158                    <label>classic</label>
 159                    <edition>1968</edition>
 160                    <edition>2018</edition>
 161               </book>
 162                 <book title="Dune" price="5">
 163                    <label>classic</label>
 164                    <edition>1965</edition>
 165                 </book>
 166              </books>
 167           </categories>
 168           <categories code=2 name="Kids" numberOfBooks="1">
 169              <books>
 170                 <book title="Matilda" />
 171              </books>
 172           </categories>
 173        </bookstore>
 174     </shops>
 175
 176 General Notes
 177 =============
 178
 179 - String values must be wrapped in quotation marks ``"`` (U+0022) or apostrophes ``'`` (U+0027).
 180 - Quotations marks and apostrophes can be escaped by doubling them in their respective quotes, for example ``'CPS ''Path'' Query' -> CPS 'Path' Query``
 181 - String comparisons are case sensitive.
 182
 183 Query Syntax
 184 ============
 185
 186 ``( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <contains()-condition> ] [ <ancestor-axis> ]``
 187
 188 Each CPS path expression need to start with an 'absolute' or 'descendant' xpath.
 189
 190 absolute-path
 191 -------------
 192
 193 **Syntax**: ``'/' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
 194
 195   - ``container name``: Any yang container or list.
 196   - ``list-key``:  One or more key-value pairs, each preceded by the ``@`` symbol, combined using the ``and`` keyword.
 197   - The above van repeated any number of times.
 198
 199 **Examples**
 200   - ``/shops/bookstore``
 201   - ``/shops/bookstore/categories[@code='1']/books``
 202   - ``/shops/bookstore/categories[@code='1']/books/book[@title='2001: A Space Odyssey']``
 203
 204 **Limitations**
 205   - Absolute paths must start with the top element (data node) as per the model tree.
 206   - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.
 207
 208 descendant-path
 209 ---------------
 210
 211 **Syntax**: ``'//' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
 212
 213   - The syntax of a descendant path is identical to a absolute path except that it is preceded by a double slash ``//``.
 214
 215 **Examples**
 216   - ``//bookstore``
 217   - ``//categories[@code='1']/books``
 218   - ``//bookstore/categories``
 219
 220 **Limitations**
 221   - Each list reference must include a valid instance reference to the key for that list.  Except when it is the last element.
 222
 223 leaf-conditions
 224 ---------------
 225
 226 **Syntax**: ``<xpath> '[' @<leaf-name1> '(=|>|<|>=|<=)' <leaf-value1> ( ' <and|or> ' @<leaf-name> '(=|>|<|>=|<=)' <leaf-value> )* ']'``
 227   - ``xpath``: Absolute or descendant or xpath to the (list) node which elements will be queried.
 228   - ``leaf-name``: The name of the leaf which value needs to be compared.
 229   - ``leaf-value``: The required value of the leaf.
 230
 231 **Examples**
 232   - ``/shops/bookstore/categories[@numberOfBooks=1]``
 233   - ``//categories[@name="Kids"]``
 234   - ``//categories[@name='Kids']``
 235   - ``//categories[@code='1']/books/book[@title='Dune' and @price=5]``
 236   - ``//categories[@code='1']/books/book[@title='xyz' or @price=15]``
 237   - ``//categories[@code='1']/books/book[@title='xyz' or @price>20]``
 238   - ``//categories[@code='1']/books/book[@title='Dune' and @price<=5]``
 239   - ``//categories[@code=1]``
 240 **Limitations**
 241   - 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).
 242   - When mixing ``and/or`` operators, ``and`` has precedence over ``or`` . So ``and`` operators get evaluated first.
 243   - Bracketing is not supported.
 244   - Leaf names are not validated so ``or`` operations with invalid leaf names will silently be ignored.
 245   - Only leaves can be used, leaf-list are not supported.
 246   - Only string and integer values are supported, boolean and float values are not supported.
 247   - Using comparative operators with string values will lead to an error at runtime. This error can't be validated earlier as the datatype is unknown until the execution phase.
 248   - 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
 249     Integer so the cps query will not work if the value is passed as string.
 250     e.g.: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string.
 251
 252 **Notes**
 253   - 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.
 254
 255 text()-condition
 256 ----------------
 257
 258 The text()-condition  can be added to any CPS path query.
 259
 260 **Syntax**: ``<cps-path> ( '/' <leaf-name> '[text()=' <string-value> ']' )?``
 261   - ``cps-path``: Any CPS path query.
 262   - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared.
 263   - ``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 will still match integer values.
 264
 265 **Examples**
 266   - ``//book/label[text()="classic"]``
 267   - ``//book/edition[text()="1965"]``
 268
 269 **Limitations**
 270   - 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).
 271   - Only one leaf or leaf-list can be tested.
 272   - Only string and integer values are supported, boolean and float values are not supported.
 273   - 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.
 274   - 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.
 275
 276 contains()-condition
 277 --------------------
 278
 279 **Syntax**: ``<cps-path> '[' 'contains' '(' '<leaf-name>','<string-value>' ')' ']'?``
 280   - ``cps-path``: Any CPS path query.
 281   - ``leaf-name``: The name of the leaf which value needs to be compared.
 282   - ``string-value``: The required value of the leaf element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values.
 283
 284 **Examples**
 285   - ``//categories[contains(@name,'Sci')]``
 286   - ``//books[contains(@title,'Space')]``
 287
 288 **Limitations**
 289   - Only leaves can be used, leaf-list are not supported.
 290   - Leaf names are not validated so ``contains() condition`` with invalid leaf names will silently be ignored.
 291
 292 **Notes**
 293   - contains condition is case sensitive.
 294
 295 ancestor-axis
 296 -------------
 297
 298 The ancestor axis can be added to any CPS path query but has to be the last part.
 299
 300 **Syntax**: ``<cps-path> ( '/ancestor::' <ancestor-path> )?``
 301   - ``cps-path``: Any CPS path query.
 302   - ``ancestor-path``: Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a ``/``.
 303
 304 **Examples**
 305   - ``//book/ancestor::categories``
 306   - ``//categories[@code='2']/books/ancestor::bookstore``
 307   - ``//book/ancestor::categories[@code='1']/books``
 308   - ``//book/label[text()="classic"]/ancestor::shops``
 309
 310 **Limitations**
 311   - Ancestor list elements can only be addressed using the list key leaf.
 312   - List elements with compound keys are not supported.