Updated the Documentation with sample yang and json

Issue-ID: CPS-940
Change-Id: I66b2f0cc1007a23498803cca695aa3d19c0eb433
Signed-off-by: Lathish <lathishbabu.ganesan@est.tech>

diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index bc46681..e8a75d9 100644 (file)
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -1,6 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2021 Nordix Foundation
+.. Copyright (C) 2021-2022 Nordix Foundation
 
 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
 .. _design:
@@ -20,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.
 
-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>
-          <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>
@@ -44,7 +164,7 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
                 </book>
              </books>
           </categories>
-          <categories code="2" name="Kids" numberOfBooks="1">
+          <categories code=2 name="Kids" numberOfBooks="1">
              <books>
                 <book title="Matilda" />
              </books>
@@ -52,8 +172,6 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu
        </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
 =============
 
@@ -79,12 +197,14 @@ absolute-path
 
 **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.
+  - 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
 ---------------
@@ -95,7 +215,7 @@ descendant-path
 
 **Examples**
   - ``//bookstore``
-  - ``//categories[@code=1]/book``
+  - ``//categories[@code='1']/books``
   - ``//bookstore/categories``
 
 **Limitations**
@@ -113,7 +233,7 @@ leaf-conditions
   - ``/shops/bookstore/categories[@numberOfBooks=1]``
   - ``//categories[@name="Kids"]``
   - ``//categories[@name='Kids']``
-  - ``//categories[@code=1]/books/book[@title='Dune' and @price=5]``
+  - ``//categories[@code='1']/books/book[@title='Dune' and @price=5]``
 
 **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).
@@ -156,9 +276,9 @@ The ancestor axis can be added to any CPS path query but has to be the last part
 
 **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.

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 0ca0547..9172e9f 100755 (executable)
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -59,6 +59,9 @@ Null can no longer be passed within the dmi plugin service names when registerin
 `CPS-837 <https://jira.onap.org/browse/CPS-837>`_ null is now used to indicate if a property should be removed as part
 of cm handle registration.
 
+The Absolute path to list with integer key will not work. Please refer `CPS-961 <https://jira.onap.org/browse/CPS-961>`_
+for more information.
+
 *Known Vulnerabilities*
 
 None