summaryrefslogtreecommitdiffstats
path: root/docs/xpath.rst
diff options
context:
space:
mode:
authorLuke Gleeson <luke.gleeson@est.tech>2023-04-20 15:42:58 +0000
committerGerrit Code Review <gerrit@onap.org>2023-04-20 15:42:58 +0000
commit13237bbca932741b8ff3061bc79a9c45d38d80d5 (patch)
tree2b35ca8f6967e7844687615b65fa909e12e61462 /docs/xpath.rst
parent7d4ece815749402a2d75a7e69f8dd7915e655b22 (diff)
parent50e000f1ca05535b1e9c61a21e06b09ecdd64bbe (diff)
Merge "Correct documentation for GET node API"
Diffstat (limited to 'docs/xpath.rst')
-rw-r--r--docs/xpath.rst220
1 files changed, 220 insertions, 0 deletions
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": {}
+ }
+ ]
+