summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--cps-rest/docs/openapi/components.yml4
-rw-r--r--docs/api/swagger/cps/openapi.yaml18
-rw-r--r--docs/modeling.rst1
-rw-r--r--docs/xpath.rst220
4 files changed, 232 insertions, 11 deletions
diff --git a/cps-rest/docs/openapi/components.yml b/cps-rest/docs/openapi/components.yml
index da43743edc..a7c13002bd 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 b5a5332e56..6e611c4858 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 95fa9ddedf..6d31f83f4b 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 0000000000..4ff1664854
--- /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": {}
+ }
+ ]
+