libyang  3.4.2
libyang is YANG data modelling language parser and toolkit written (and providing API) in C.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
XPath Addressing

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.

XPath

Generally, any xpath argument expects an expression similar to when or must as the same evaluator is used. As for the format of any prefixes, the standardized JSON (RFC 7951) was used. Summarized, xpath follows these conventions:

  • full XPath can be used, but only data nodes (node sets) will always be returned,
  • 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,
  • note that non-data nodes/schema-only node (choice, case, uses, input, output) are skipped and MUST not be included in the path.

Functions List

Path

The term path is used when a simplified (subset of) XPath is expected. Path is always a valid XPath but not the other way around. In short, paths only identify a specific (set of) nodes based on their ancestors in the schema. Predicates are allowed the same as for an instance-identifier. Specifically, key values of a list, leaf-list value, or position of lists without keys can be used.

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 3rd list-without-keys instance with no keys defined
    /module-name:container/list-without-keys[3]
    
  • 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