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