libyang-Data Instances

All the nodes in data tree comes are based on lyd_node structure. According to the content of the lyd_node.schema it can be cast to several other structures.

In case the lyd_node.schema pointer is NULL, the node is actually opaq and can be safely cast to lyd_node_opaq. The opaq node represent an unknown node which wasn't mapped to any (compiled) schema node in the context. Such a node can appear in several places in the data tree.

• As a part of the tree structure, but only in the case the LYD_PARSE_OPAQ option was used when input data were parsed, because unknown data instances are ignored by default. The same way, the opaq nodes can appear as a node's attributes.
• As a representation of YANG anydata/anyxml content.
• As envelopes of standard data tree instances (RPCs, actions or Notifications).

In case the data node has its definition in a compiled schema tree, the structure of the data node is actually one of the followings according to the schema node's nodetype (lysc_node.nodetype).

• lyd_node_inner - represents data nodes corresponding to schema nodes matching LYD_NODE_INNER nodetypes. They provide structure of the tree by having children nodes.
• lyd_node_term - represents data nodes corresponding to schema nodes matching LYD_NODE_TERM nodetypes. The terminal nodes provide values of the particular configuration/status information. The values are represented as lyd_value structure with string representation of the value (retrieved by lyd_get_value() and lyd_get_meta_value()) and the type specific data stored in the structure's union according to the real type of the value (lyd_value.realtype). The string representation provides canonical representation of the value in case the type has the canonical representation specified. Otherwise, it is the original value or, in case the value can contain prefixes, the JSON format is used to make the value unambiguous.
• lyd_node_any - represents data nodes corresponding to schema nodes matching LYD_NODE_ANY nodetypes.

Despite all the aforementioned structures and their members are available as part of the libyang API and callers can use it to navigate through the data tree structure or to obtain various information, we recommend to use the following macros and functions.

• lyd_child() (or lyd_child_no_keys()) and lyd_parent() to get the node's child/parent node.
• LYD_CTX to get libyang context from a data node.
• lyd_get_value()/lyd_get_meta_value() to get canonical string value from a terminal node/metadata instance.
• LYD_TREE_DFS_BEGIN and LYD_TREE_DFS_END to traverse the data tree (depth-first).
• LY_LIST_FOR and LY_ARRAY_FOR as described on Data Structures page.

Instead of going through the data tree on your own, a specific data node can be also located using a wide set of lyd_find_*() functions.

More information about specific operations with data instances can be found on the following pages:

• Parsing Data
• Validating Data
• Default Values
• Manipulating Data
• Printing Data
• LYB Binary Format

Note

API for this group of functions is described in the Data Instances module.

Functions List (not assigned to above subsections)

• lyd_child()
• lyd_child_no_keys()
• lyd_parent()
• lyd_owner_module()
• lyd_get_value()
• lyd_get_meta_value()
• lyd_find_xpath()
• lyd_find_path()
• lyd_find_target()
• lyd_find_sibling_val()
• lyd_find_sibling_first()
• lyd_find_sibling_opaq_next()
• lyd_find_meta()
• lyd_path()
• lyd_target()
• lyd_lyb_data_length()

Metadata Support

YANG Metadata annotations are defined in RFC 7952 as YANG extension (and libyang implements them as internal extension plugin). In practice, it allows to have XML attributes (there is also a special encoding for JSON) in YANG modeled data. libyang does not allow to have any XML attribute without the appropriate annotation definition describing the data as it is done e.g. for leafs. When an attribute without a matching annotation definition is found in the input data, it is:

• silently dropped (with warning) or
• an error is reported in case the LYD_PARSE_STRICT parser option is provided to the parser function or
• stored into a generic lyd_attr structure without a connection with any YANG module in case the LYD_PARSE_OPAQ parser options is provided to the parser function.

There are some XML attributes, described by YANG and NETCONF specifications, which are not defined as annotations, but libyang implements them this way. In case of attributes in the YANG namespace (insert, value and key attributes for the NETCONF edit-config operation), they are defined in special libyang's internal module yang, which is available in each context and the content of this schema can be printed via schema printers.

In case of the attributes described in NETCONF specification, the libyang's annotations structures are hidden and cannot be printed despite, internally, they are part of the ietf-netconf's schema structure. Therefore, these attributes are available only when the ietf-netconf schema is loaded in the context. The definitions of these annotations are as follows:

md:annotation operation {
  type enumeration {
    enum merge;
    enum replace;
    enum create;
    enum delete;
    enum remove;
  }
}

md:annotation type {
  type enumeration {
    enum subtree;
    enum xpath {
      if-feature "nc:xpath";
    }
  }
}

md:annotation select {
  type string;
}

Note, that, following the specification,

• the type and select XML attributes are supposed to be unqualified (without namespace) and that
• the select's content is XPath and it is internally transformed by libyang into the format where the XML namespace prefixes are replaced by the YANG module names.

yang-data Support

RFC 8040 defines ietf-restconf module, which includes yang-data extension. Despite the definition in the RESTCONF YANG module, the yang-data concept is quite generic and used even in modules without a connection to RESTCONF protocol. The extension allows to define a separated YANG trees usable separately from any datastore.

libyang implements support for yang-data internally as an extension plugin. To ease the use of yang-data with libyang, there are several generic functions, which are usable for yang-data:

• lyd_parse_ext_data()
• lyd_parse_ext_op()
• lys_getnext_ext()
• lyd_new_ext_inner()
• lyd_new_ext_list()
• lyd_new_ext_term()
• lyd_new_ext_any()
• lyd_new_ext_path()