Internally, XPath evaluation is performed on when and must conditions in the schema. For that almost a full XPath 1.0 evaluator was implemented. In YANG models you can also find paths identifying augment targets, leafref targets, and trivial paths in choice default and unique statements argument. The exact format of all those paths can be found in the relevant RFCs. Further will only be discussed paths that are used directly in libyang API functions.
Schema
Regarding identifying schema nodes, we use a slightly modified version of YANG augment target path:
- strictly speaking, most XPath expressions are not accepted, only simple paths (no predicates, numbers, literals, operators, ...),
- whenever a prefix is used for a node, it is not the import prefix, but the module name itself,
- current module is specified separately for absolute paths and is the module of the start (current) node for relative paths,
- unprefixed nodes all use the prefix of the current module so all nodes from other modules than the current module MUST have prefixes,
- nodes from the current module MAY have prefixes,
Examples
Functions List
Data
As for paths evaluated on YANG data, we opted for standardized JSON paths (RFC 7951). Summarized, it follows these conventions:
- generally, you can use almost a full XPath in these paths where it makes sense, but only data nodes (node sets) will always be returned (except for paths, predicates are mostly used),
- as per the specification, prefixes are actually module names,
- also in the specification, for absolute paths, the first (leftmost) node MUST have a prefix,
- for relative paths, you specify the context node, which then acts as a parent for the first node in the path,
- nodes always inherit their module (prefix) from their parent node so whenever a node is from a different module than its parent, it MUST have a prefix,
- nodes from the same module as their parent MUST NOT have a prefix,
- different from schema paths, non-data nodes (choice, case, uses, input, output) are skipped and not included in the path.
Examples
- get list instance with key1 of value 1 and key2 of value 2 (this can return more list instances if there are more keys than key1 and key2)
/module-name:container/list[key1='1'][key2='2']
- get leaf-list instance with the value val
/module-name:container/leaf-list[.='val']
- get aug-list with aug-list-key, which was added to module-name from an augment module augment-module
/module-name:container/container2/augment-module:aug-cont/aug-list[aug-list-key='value']
Functions List