Updated the documentation with limitation of leaf condition

[cps.git] / docs / cps-path.rst

diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index 0271d07..fba21f3 100644 (file)
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -1,5 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 .. 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
 .. _design:
 
 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
 .. _design:


@@ -19,17 +20,137 @@ The CPS path parameter is used for querying xpaths. CPS path is inspired by the
 
 This section describes the functionality currently supported by CPS Path.
 
 
 This section describes the functionality currently supported by CPS Path.
 

-Sample Data
-===========
+Sample Yang Model
+=================

 
 

-The xml below describes some basic data to be used to illustrate the CPS Path functionality.
+.. 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>
 
 .. code-block:: xml
 
     <shops>
        <bookstore name="Chapters">
           <bookstore-name>Chapters</bookstore-name>

-          <categories code="1" name="SciFi" numberOfBooks="2">
+          <categories code=1 name="SciFi" numberOfBooks="2">

              <books>
                 <book title="2001: A Space Odyssey" price="5">
                    <label>sale</label>
              <books>
                 <book title="2001: A Space Odyssey" price="5">
                    <label>sale</label>


@@ -43,7 +164,7 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
                 </book>
              </books>
           </categories>
                 </book>
              </books>
           </categories>

-          <categories code="2" name="Kids" numberOfBooks="1">
+          <categories code=2 name="Kids" numberOfBooks="1">

              <books>
                 <book title="Matilda" />
              </books>
              <books>
                 <book title="Matilda" />
              </books>


@@ -51,8 +172,6 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
        </bookstore>
     </shops>
 
        </bookstore>
     </shops>
 

-**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
 =============
 
 General Notes
 =============
 


@@ -78,12 +197,14 @@ absolute-path
 
 **Examples**
   - ``/shops/bookstore``
 
 **Examples**
   - ``/shops/bookstore``

-  - ``/shops/bookstore/categories[@code=1]``
-  - ``/shops/bookstore/categories[@code=1]/book``
+  - ``/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.
 
 **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.

+  - The Absolute path to list with integer key will not work. It needs to be surrounded with a single quote ([@code='1'])
+    as if it is a string. This will be fixed in `CPS-961 <https://jira.onap.org/browse/CPS-961>`_

 
 descendant-path
 ---------------
 
 descendant-path
 ---------------


@@ -94,7 +215,7 @@ descendant-path
 
 **Examples**
   - ``//bookstore``
 
 **Examples**
   - ``//bookstore``

-  - ``//categories[@code=1]/book``
+  - ``//categories[@code='1']/books``

   - ``//bookstore/categories``
 
 **Limitations**
   - ``//bookstore/categories``
 
 **Limitations**


@@ -112,13 +233,16 @@ leaf-conditions
   - ``/shops/bookstore/categories[@numberOfBooks=1]``
   - ``//categories[@name="Kids"]``
   - ``//categories[@name='Kids']``
   - ``/shops/bookstore/categories[@numberOfBooks=1]``
   - ``//categories[@name="Kids"]``
   - ``//categories[@name='Kids']``

-  - ``//categories[@code=1]/book[@title='Dune' and price=5]``
-
+  - ``//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.
 **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.

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


@@ -155,9 +279,9 @@ The ancestor axis can be added to any CPS path query but has to be the last part
 
 **Examples**
   - ``//book/ancestor::categories``
 
 **Examples**
   - ``//book/ancestor::categories``

-  - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
-  - ``book/ancestor::categories[@code=1]/books``
-  - ``//book/label[text()="classic"]/ancestor::shop``
+  - ``//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.
 
 **Limitations**
   - Ancestor list elements can only be addressed using the list key leaf.