docs/xpath.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2023 Nordix Foundation
   4
   5 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   6 .. _xpath:
   7
   8
   9 XPath
  10 ########
  11
  12 .. toctree::
  13    :maxdepth: 1
  14
  15 Introduction
  16 ============
  17
  18 In CPS , Xpath is a parameter used in several APIs, which allows us to retrieve JSON and XML data efficiently.
  19 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.
  20
  21 Sample Yang Model
  22 =================
  23
  24 .. code-block::
  25
  26   module stores {
  27       yang-version 1.1;
  28       namespace "org:onap:ccsdk:sample";
  29
  30       prefix book-store;
  31
  32       revision "2020-09-15" {
  33           description
  34             "Sample Model";
  35       }
  36       container shops {
  37
  38           container bookstore {
  39
  40               leaf bookstore-name {
  41                   type string;
  42               }
  43
  44               leaf name {
  45                   type string;
  46               }
  47
  48               list categories {
  49
  50                   key "code";
  51
  52                   leaf code {
  53                       type uint16;
  54                   }
  55
  56                   leaf name {
  57                       type string;
  58                   }
  59
  60                   leaf numberOfBooks {
  61                       type uint16;
  62                   }
  63
  64                   container books {
  65
  66                       list book {
  67                           key title;
  68
  69                           leaf title {
  70                               type string;
  71                           }
  72                           leaf price {
  73                               type uint16;
  74                           }
  75                           leaf-list label {
  76                               type string;
  77                           }
  78                           leaf-list edition {
  79                               type string;
  80                           }
  81                       }
  82                   }
  83               }
  84           }
  85       }
  86   }
  87
  88 **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.
  89
  90 Sample Data in Json
  91 ===================
  92
  93 .. code-block:: json
  94
  95     {
  96       "shops": {
  97         "bookstore": {
  98           "bookstore-name": "Chapters",
  99           "name": "Chapters",
 100           "categories": [
 101             {
 102               "code": 1,
 103               "name": "SciFi",
 104               "numberOfBooks": 2,
 105               "books": {
 106                 "book": [
 107                   {
 108                     "title": "2001: A Space Odyssey",
 109                     "price": 5,
 110                     "label": ["sale", "classic"],
 111                     "edition": ["1968", "2018"]
 112                   },
 113                   {
 114                     "title": "Dune",
 115                     "price": 5,
 116                     "label": ["classic"],
 117                     "edition": ["1965"]
 118                   }
 119                 ]
 120               }
 121             },
 122             {
 123               "code": 2,
 124               "name": "Kids",
 125               "numberOfBooks": 1,
 126               "books": {
 127                 "book": [
 128                   {
 129                     "title": "Matilda"
 130                   }
 131                 ]
 132               }
 133             }
 134           ]
 135         }
 136       }
 137     }
 138
 139 Nodes
 140 =====
 141
 142 - Xpaths uses 'nodes' to navigate through the data.
 143     - Nodes typically used in CPS:
 144         - container
 145         - list
 146         - leaf (CPS does not support addressing leaf nodes using XPath syntax)
 147 - JSON data and XML data are node trees
 148     - the 'root node' contains all the configuration data nodes that exist at the top-level in all modules, serving as their parent node.
 149
 150 Relationships
 151 =============
 152
 153 - Every node has a parent, not every node has a children
 154 - Ancestor: a node's parent, parent's parent , parent's parent's parents …
 155     - In the given sample model and data, the top data node 'shops' is the ancestor of every other node
 156 - Descendants: a node's children, children's children,  children's children's children
 157     - In the given sample model and data, the list node 'books' is a descendant of the container node 'books'
 158
 159 Supported XPath syntax in CPS
 160 =============================
 161
 162 Selecting nodes
 163 ---------------
 164
 165   - ``/``: Selects from the root node
 166     - **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.
 167   - ``@``: Selects attributes
 168     - **Note:** Providing the attribute value can be enclosed in quotations i.e. ``[@code=1]`` will provide same result as ``[@code='1']``
 169
 170 .. list-table::
 171    :header-rows: 1
 172
 173    * - XPath
 174      - Description
 175      - Selected node(s) without descendants
 176    * - - /
 177        - /shops
 178      - Selects the root node
 179      - .. code-block:: json
 180
 181             [
 182               {
 183                 "book-store:shops": {}
 184               }
 185             ]
 186    * - /shops/bookstore
 187      - Selects the bookstore container node
 188      - .. code-block:: json
 189
 190             [
 191               {
 192                 "book-store:bookstore": {
 193                   "name": "Chapters",
 194                   "bookstore-name": "Chapters"
 195                 }
 196               }
 197             ]
 198    * - /shops/bookstore/categories[@code='1']
 199      - Selects 'categories' list node in 'bookstore' container that contains the key attribute 'code=1'
 200      - .. code-block:: json
 201
 202             [
 203               {
 204                 "book-store:categories": {
 205                   "code": 1,
 206                   "name": "SciFi",
 207                   "numberOfBooks": 2
 208                 }
 209               }
 210             ]
 211    * - /shops/bookstore/categories[@code='1']/books
 212      - Selects the 'books' container node in 'categories' list node in 'bookstore' container that contains the key attribute 'code=1'
 213      - .. code-block:: json
 214
 215             [
 216               {
 217                 "book-store:books": {}
 218               }
 219             ]
 220