diff options
| -rw-r--r-- | cps-rest/docs/openapi/components.yml | 4 | ||||
| -rw-r--r-- | docs/api/swagger/cps/openapi.yaml | 18 | ||||
| -rw-r--r-- | docs/modeling.rst | 1 | ||||
| -rw-r--r-- | docs/xpath.rst | 220 |
4 files changed, 232 insertions, 11 deletions
diff --git a/cps-rest/docs/openapi/components.yml b/cps-rest/docs/openapi/components.yml index da43743ed..a7c13002b 100644 --- a/cps-rest/docs/openapi/components.yml +++ b/cps-rest/docs/openapi/components.yml @@ -191,7 +191,7 @@ components: xpathInQuery: name: xpath in: query - description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html + description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html required: false schema: type: string @@ -204,7 +204,7 @@ components: requiredXpathInQuery: name: xpath in: query - description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html + description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html required: true schema: type: string diff --git a/docs/api/swagger/cps/openapi.yaml b/docs/api/swagger/cps/openapi.yaml index b5a5332e5..6e611c485 100644 --- a/docs/api/swagger/cps/openapi.yaml +++ b/docs/api/swagger/cps/openapi.yaml @@ -1213,7 +1213,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1308,7 +1308,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1413,7 +1413,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1522,7 +1522,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1655,7 +1655,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1751,7 +1751,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: false schema: type: string @@ -1851,7 +1851,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: true schema: type: string @@ -1946,7 +1946,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: true schema: type: string @@ -2054,7 +2054,7 @@ paths: example: my-anchor - name: xpath in: query - description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html" + description: "For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/xpath.html" required: true schema: type: string diff --git a/docs/modeling.rst b/docs/modeling.rst index 95fa9dded..6d31f83f4 100644 --- a/docs/modeling.rst +++ b/docs/modeling.rst @@ -60,6 +60,7 @@ Querying .. toctree:: :maxdepth: 1 + xpath.rst cps-path.rst .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning diff --git a/docs/xpath.rst b/docs/xpath.rst new file mode 100644 index 000000000..4ff166485 --- /dev/null +++ b/docs/xpath.rst @@ -0,0 +1,220 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING +.. _xpath: + + +XPath +######## + +.. toctree:: + :maxdepth: 1 + +Introduction +============ + +In CPS , Xpath is a parameter used in several APIs, which allows us to retrieve JSON and XML data efficiently. +The XPath syntax provides us with the ability to navigate through the hierarchical structure of data used in CPS easily via specification of node names, values ,attributes etc. + +Sample Yang Model +================= + +.. 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. + +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" + } + ] + } + } + ] + } + } + } + +Nodes +===== + +- Xpaths uses 'nodes' to navigate through the data. + - Nodes typically used in CPS: + - container + - list + - leaf (CPS does not support addressing leaf nodes using XPath syntax) +- JSON data and XML data are node trees + - the 'root node' contains all the configuration data nodes that exist at the top-level in all modules, serving as their parent node. + +Relationships +============= + +- Every node has a parent, not every node has a children +- Ancestor: a node's parent, parent's parent , parent's parent's parents … + - In the given sample model and data, the top data node 'shops' is the ancestor of every other node +- Descendants: a node's children, children's children, children's children's children + - In the given sample model and data, the list node 'books' is a descendant of the container node 'books' + +Supported XPath syntax in CPS +============================= + +Selecting nodes +--------------- + + - ``/``: Selects from the root node + - **Note:** CPS uses absolute location path which means that XPath expression expected in CPS must start with / followed by the nodes leading to the node being selected. + - ``@``: Selects attributes + - **Note:** Providing the attribute value can be enclosed in quotations i.e. ``[@code=1]`` will provide same result as ``[@code='1']`` + +.. list-table:: + :header-rows: 1 + + * - XPath + - Description + - Selected node(s) without descendants + * - - / + - /shops + - Selects the root node + - .. code-block:: json + + [ + { + "book-store:shops": {} + } + ] + * - /shops/bookstore + - Selects the bookstore container node + - .. code-block:: json + + [ + { + "book-store:bookstore": { + "name": "Chapters", + "bookstore-name": "Chapters" + } + } + ] + * - /shops/bookstore/categories[@code='1'] + - Selects 'categories' list node in 'bookstore' container that contains the key attribute 'code=1' + - .. code-block:: json + + [ + { + "book-store:categories": { + "code": 1, + "name": "SciFi", + "numberOfBooks": 2 + } + } + ] + * - /shops/bookstore/categories[@code='1']/books + - Selects the 'books' container node in 'categories' list node in 'bookstore' container that contains the key attribute 'code=1' + - .. code-block:: json + + [ + { + "book-store:books": {} + } + ] + |