docs/cps-path.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   5 .. _design:
   6
   7
   8 CPS Path
   9 ########
  10
  11 .. toctree::
  12    :maxdepth: 1
  13
  14 Introduction
  15 ============
  16
  17 Several CPS APIs use the cps-path (or cpsPath in Java API) parameter.
  18 The CPS Path parameter is used for querying xpaths. CPS Path is insprired by the `XML Path Language (XPath) 3.1. <https://www.w3.org/TR/2017/REC-xpath-31-20170321/>`_
  19
  20 This section describes the functionality currently supported by CPS Path.
  21
  22 Sample Data
  23 ===========
  24
  25 The xml below describes some basic data to be used to illustrate the CPS Path functionality.
  26
  27 .. code-block:: xml
  28
  29     <shops>
  30        <bookstore name="Chapters">
  31          <bookstore-name>Chapters</bookstore-name>
  32          <categories code="1" name="SciFi" numberOfBooks="2">
  33            <books>
  34              <book name="Space Odyssee"/>
  35              <book name="Dune"/>
  36            </books>
  37         </categories>
  38         <categories code="2" name="Kids" numberOfBooks="1">
  39            <books>
  40              <book name="Matilda"/>
  41            </books>
  42         </categories>
  43        </bookstore>
  44     </shops>
  45
  46 **Note.** 'categories' is a Yang List and 'code' is its key leaf. All other data nodes are Yang Containers
  47
  48 General Notes
  49 =============
  50
  51 - String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
  52 - String comparisons are case sensitive.
  53
  54 Supported Queries
  55 =================
  56
  57 Get List Elements by Any Attribute Value
  58 ----------------------------------------
  59
  60 **Syntax**: ``<xpath>/<target-node>[@<leaf-name>=<leaf-value>]``
  61   - ``xpath``: The xpath to the parent of the target node including all ancestors.
  62   - ``target-node``: The name of the (list) node which elements will queried.
  63   - ``leaf-name``: The name of the leaf which value needs to be compared.
  64   - ``leaf-value``: The required value of the leaf.
  65
  66 **Examples**
  67   - ``/shops/bookstore/categories[@numberOfBooks=1]``
  68   - ``/shops/bookstore/categories[@name="Kids"]``
  69   - ``/shops/bookstore/categories[@name='Kids']``
  70
  71 **Limitations**
  72   - Only one list (last descendant) can be queried for a non-key value. Any ancestor list will have to be referenced by its key name-value pair(s).
  73   - Only one attribute can be queried.
  74   - Only string and integer values are supported (boolean and float values are not supported).
  75
  76 **Notes**
  77   - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath.
  78
  79 Get Any Descendant
  80 ------------------
  81
  82 **Syntax**: ``//<direct-ancestors><target-node>``
  83   - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
  84   - ``target-node``: The name of the (list) node from which element will be selected. If the target node is a Yang List he element needs to be specified using the key as normal e.g. ``categories[@code=1]``.
  85
  86 **Examples**
  87   - ``//book``
  88   - ``//books/book``
  89   - ``//categories[@code=1]``
  90   - ``//categories[@code=1]/books``
  91
  92 **Limitations**
  93   - List elements can only be addressed using the list key leaf.
  94
  95 Get Any Descendant by Any Attribute Value
  96 -----------------------------------------
  97
  98 **Syntax**: ``//<direct-ancestors><target-node>[@<leaf-name>=<leaf-value>]``
  99   - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
 100   - ``target-node``: The name of the (list) node which elements will queried.
 101   - ``leaf1-name .. leafN-name:``: One or more leaves whose value needs to be compared.
 102   - ``leaf1-value .. leafN-value:``: One or more required leaf values (multiple condition can be combined using the 'and' keyword).
 103
 104 **Examples**
 105   - ``//categories[@name='Kids']``
 106   - ``//categories[@name='Kids' and @numberOfBooks=1]``
 107
 108 **Limitations**
 109   - Only string and integer values are supported (boolean and float values are not supported).
 110   - Multiple attributes can only be combined using 'and'. 'or' and bracketing is not supported.
 111
 112 Query Extensions
 113 ================
 114
 115 Ancestor Axis
 116 -------------
 117
 118 The ancestor axis can be added to any CPS path query.
 119
 120 **Syntax**: ``//<cps-path>/ancestor::<ancestor-path>``
 121   - ``cps-path``: Any CPS path query.
 122   - ``ancestor-path``:  Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a /.
 123
 124 **Examples**
 125   - ``//book/ancestor::categories``
 126   - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
 127   - ``book/ancestor::categories[@code=1]/books``
 128
 129 **Limitations**
 130   - Ancestor list elements can only be addressed using the list key leaf.
 131   - List elements with compound keys are not supported.