X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fcps-path.rst;h=0271d07e1d42744b49c36ad2028dd8774e418bd1;hb=f0527c58c17963d940535d0ce0eb934c2b4c635c;hp=aec87cd4362c76e22ae4d12d84bdea2b65b77b17;hpb=6355b212de77e658b16614eb775f03c7713c8460;p=cps.git
diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index aec87cd43..0271d07e1 100644
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -14,8 +14,8 @@ CPS Path
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. `_
+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. `_
This section describes the functionality currently supported by CPS Path.
@@ -28,104 +28,137 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
- Chapters
-
-
-
-
-
-
-
-
-
-
-
+ Chapters
+
+
+
+
+
+ 1968
+ 2018
+
+
+
+ 1965
+
+
+
+
+
+
+
+
-**Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers
+**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.
General Notes
=============
-- String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
+- 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 `_ Special Character Limitations of cpsPath Queries
-Supported Queries
-=================
+Query Syntax
+============
-Get List Elements by Any Attribute Value
-----------------------------------------
+``( | ) [ ] [ ] [ ]``
-**Syntax**: ``/[@=]``
- - ``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.
+Each CPS path expression need to start with an 'absolute' or 'descendant' xpath.
+
+absolute-path
+-------------
+
+**Syntax**: ``'/' ( '[' ']' )? ( '/' ( '[' ']' )? )*``
+
+ - ``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/categories[@numberOfBooks=1]``
- - ``/shops/bookstore/categories[@name="Kids"]``
- - ``/shops/bookstore/categories[@name='Kids']``
+ - ``/shops/bookstore``
+ - ``/shops/bookstore/categories[@code=1]``
+ - ``/shops/bookstore/categories[@code=1]/book``
**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).
+ - 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.
-**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.
+descendant-path
+---------------
-Get Any Descendant
-------------------
+**Syntax**: ``'//' ( '[' ']' )? ( '/' ( '[' ']' )? )*``
-**Syntax**: ``//``
- - ``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]``.
+ - The syntax of a descendant path is identical to a absolute path except that it is preceded by a double slash ``//``.
**Examples**
- - ``//book``
- - ``//books/book``
- - ``//categories[@code=1]``
- - ``//categories[@code=1]/books``
+ - ``//bookstore``
+ - ``//categories[@code=1]/book``
+ - ``//bookstore/categories``
**Limitations**
- - List elements can only be addressed using the list key leaf.
+ - Each list reference must include a valid instance reference to the key for that list. Except when it is the last element.
-Get Any Descendant by Any Attribute Value
------------------------------------------
+leaf-conditions
+---------------
-**Syntax**: ``//[@=]``
- - ``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).
+**Syntax**: `` '[' @ '=' ( ' and ' @ '=' )* ']'``
+ - ``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[@name='Kids' and @numberOfBooks=1]``
+ - ``//categories[@code=1]/book[@title='Dune' and price=5]``
**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.
+ - 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.
+
+**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.
-Query Extensions
-================
+**Syntax**: `` ( '/' '[text()=' ']' )?``
+ - ``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 @ as described above.
-Ancestor Axis
+ancestor-axis
-------------
-The ancestor axis can be added to any CPS path query.
+The ancestor axis can be added to any CPS path query but has to be the last part.
-**Syntax**: ``///ancestor::``
+**Syntax**: `` ( '/ancestor::' )?``
- ``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 /.
+ - ``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``
+ - ``//book/label[text()="classic"]/ancestor::shop``
**Limitations**
- Ancestor list elements can only be addressed using the list key leaf.
- - List elements with compound keys are not supported.
\ No newline at end of file
+ - List elements with compound keys are not supported.