From b3550f16151d5de5b568f06c41c9b29b31a2ffaa Mon Sep 17 00:00:00 2001 From: Lathish Date: Tue, 15 Mar 2022 12:03:53 +0000 Subject: [PATCH] Updated the Documentation with sample yang and json Issue-ID: CPS-940 Change-Id: I66b2f0cc1007a23498803cca695aa3d19c0eb433 Signed-off-by: Lathish --- docs/cps-path.rst | 150 ++++++++++++++++++++++++++++++++++++++++++++----- docs/release-notes.rst | 3 + 2 files changed, 138 insertions(+), 15 deletions(-) diff --git a/docs/cps-path.rst b/docs/cps-path.rst index bc46681d1..e8a75d9cf 100644 --- 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 Chapters - + @@ -44,7 +164,7 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu - + @@ -52,8 +172,6 @@ The xml below describes some basic data to be used to illustrate the CPS Path fu -**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 `_ 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 0ca0547fa..9172e9f10 100755 --- 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 `_ 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 `_ +for more information. + *Known Vulnerabilities* None -- 2.16.6