blob: 91bfdcb4319454374c5b42a059d9ad2433cf4091 [file] [log] [blame]
ToineSiebelink98c07872021-04-20 17:33:09 +01001.. 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
8CPS Path
9########
10
11.. toctree::
12 :maxdepth: 1
13
14Introduction
15============
16
17Several CPS APIs use the cps-path (or cpsPath in Java API) parameter.
18The 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
20This section describes the functionality currently supported by CPS Path.
21
22Sample Data
23===========
24
25The 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
48General 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
54Supported Functions
55===================
56
57Get List Elements by Any Attribute Value
58----------------------------------------
59
puthuparambil.adityaff714622021-04-23 11:55:24 +010060**Syntax**: ``<xpath>/<target-node>[@<leaf-name>=<leaf-value>]``
ToineSiebelink98c07872021-04-20 17:33:09 +010061 - ``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**
puthuparambil.adityaff714622021-04-23 11:55:24 +010077 - For performance reasons it does not make sense to query the list key leaf. If the key value is known it is better to execute a get request with the complete xpath.
ToineSiebelink98c07872021-04-20 17:33:09 +010078
79Get 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.
puthuparambil.adityaff714622021-04-23 11:55:24 +010094
95Get 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 - ``leaf-name``: The name of the leaf which value needs to be compared.
102 - ``leaf-value``: The required value of the leaf.
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 should be separated by 'and'.
111 - Trailing 'and' is ignored in the yang list.