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 Nordix Foundation
   4
   5 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   6 .. _design:
   7
   8
   9 CPS Path
  10 ########
  11
  12 .. warning:: draft
  13
  14 .. toctree::
  15    :maxdepth: 1
  16
  17 Introduction
  18 ============
  19
  20 Several CPS APIs use the CPS path (or cpsPath in Java API) parameter.
  21 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/>`_
  22
  23 This section describes the functionality currently supported by CPS Path.
  24
  25 Sample Data
  26 ===========
  27
  28 The xml below describes some basic data to be used to illustrate the CPS Path functionality.
  29
  30 .. code-block:: xml
  31
  32     <shops>
  33        <bookstore name="Chapters">
  34           <bookstore-name>Chapters</bookstore-name>
  35           <categories code="1" name="SciFi" numberOfBooks="2">
  36              <books>
  37                 <book title="2001: A Space Odyssey" price="5">
  38                    <label>sale</label>
  39                    <label>classic</label>
  40                    <edition>1968</edition>
  41                    <edition>2018</edition>
  42               </book>
  43                 <book title="Dune" price="5">
  44                    <label>classic</label>
  45                    <edition>1965</edition>
  46                 </book>
  47              </books>
  48           </categories>
  49           <categories code="2" name="Kids" numberOfBooks="1">
  50              <books>
  51                 <book title="Matilda" />
  52              </books>
  53           </categories>
  54        </bookstore>
  55     </shops>
  56
  57 **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.
  58
  59 General Notes
  60 =============
  61
  62 - String values must be wrapped in quotation marks ``"`` (U+0022) or apostrophes ``'`` (U+0027).
  63 - String comparisons are case sensitive.
  64 - 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
  65
  66 Query Syntax
  67 ============
  68
  69 ``( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <ancestor-axis> ]``
  70
  71 Each CPS path expression need to start with an 'absolute' or 'descendant' xpath.
  72
  73 absolute-path
  74 -------------
  75
  76 **Syntax**: ``'/' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
  77
  78   - ``container name``: Any yang container or list.
  79   - ``list-key``:  One or more key-value pairs, each preceded by the ``@`` symbol, combined using the ``and`` keyword.
  80   - The above van repeated any number of times.
  81
  82 **Examples**
  83   - ``/shops/bookstore``
  84   - ``/shops/bookstore/categories[@code=1]``
  85   - ``/shops/bookstore/categories[@code=1]/book``
  86
  87 **Limitations**
  88   - Absolute paths must start with the top element (data node) as per the model tree.
  89   - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.
  90
  91 descendant-path
  92 ---------------
  93
  94 **Syntax**: ``'//' <container-name> ( '[' <list-key> ']' )? ( '/' <containerName> ( '[' <list-key> ']' )? )*``
  95
  96   - The syntax of a descendant path is identical to a absolute path except that it is preceded by a double slash ``//``.
  97
  98 **Examples**
  99   - ``//bookstore``
 100   - ``//categories[@code=1]/book``
 101   - ``//bookstore/categories``
 102
 103 **Limitations**
 104   - Each list reference must include a valid instance reference to the key for that list.  Except when it is the last element.
 105
 106 leaf-conditions
 107 ---------------
 108
 109 **Syntax**: ``<xpath> '[' @<leaf-name1> '=' <leaf-value1> ( ' and ' @<leaf-name> '=' <leaf-value> )* ']'``
 110   - ``xpath``: Absolute or descendant or xpath to the (list) node which elements will be queried.
 111   - ``leaf-name``: The name of the leaf which value needs to be compared.
 112   - ``leaf-value``: The required value of the leaf.
 113
 114 **Examples**
 115   - ``/shops/bookstore/categories[@numberOfBooks=1]``
 116   - ``//categories[@name="Kids"]``
 117   - ``//categories[@name='Kids']``
 118   - ``//categories[@code=1]/book[@title='Dune' and price=5]``
 119
 120 **Limitations**
 121   - 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).
 122   - Multiple attributes can only be combined using ``and``. ``or`` and bracketing is not supported.
 123   - Only leaves can be used, leaf-list are not supported.
 124   - Only string and integer values are supported, boolean and float values are not supported.
 125
 126 **Notes**
 127   - 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.
 128
 129 text()-condition
 130 ----------------
 131
 132 The text()-condition  can be added to any CPS path query.
 133
 134 **Syntax**: ``<cps-path> ( '/' <leaf-name> '[text()=' <string-value> ']' )?``
 135   - ``cps-path``: Any CPS path query.
 136   - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared.
 137   - ``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.
 138
 139 **Examples**
 140   - ``//book/label[text()="classic"]``
 141   - ``//book/edition[text()="1965"]``
 142
 143 **Limitations**
 144   - 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).
 145   - Only one leaf or leaf-list can be tested.
 146   - Only string and integer values are supported, boolean and float values are not supported.
 147   - 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.
 148   - 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.
 149
 150 ancestor-axis
 151 -------------
 152
 153 The ancestor axis can be added to any CPS path query but has to be the last part.
 154
 155 **Syntax**: ``<cps-path> ( '/ancestor::' <ancestor-path> )?``
 156   - ``cps-path``: Any CPS path query.
 157   - ``ancestor-path``: Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a ``/``.
 158
 159 **Examples**
 160   - ``//book/ancestor::categories``
 161   - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
 162   - ``book/ancestor::categories[@code=1]/books``
 163   - ``//book/label[text()="classic"]/ancestor::shop``
 164
 165 **Limitations**
 166   - Ancestor list elements can only be addressed using the list key leaf.
 167   - List elements with compound keys are not supported.