From: Toine Siebelink Date: Mon, 28 Mar 2022 11:03:31 +0000 (+0000) Subject: Merge "Updated the Documentation with sample yang and json" X-Git-Tag: 3.1.0~158 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=cps.git;a=commitdiff_plain;h=a0bbcfd8de94bb433e787b1a6ee400c988975850;hp=21f7162f675617af72d904b3a5247cabe72db9bf Merge "Updated the Documentation with sample yang and json" --- 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 c2e2a5fdc..2fea4a21f 100755 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -73,6 +73,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