blob: d13fd57b0723b70b220bcd4d4697f44450cb83e7 [file] [log] [blame]
Radek Krejci7931b192020-06-25 17:05:03 +02001/**
2 * @file parser_data.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vaskoaf5a8dd2023-03-02 11:25:02 +01004 * @author Michal Vasko <mvasko@cesnet.cz>
Radek Krejci7931b192020-06-25 17:05:03 +02005 * @brief Data parsers for libyang
6 *
Michal Vaskoaf5a8dd2023-03-02 11:25:02 +01007 * Copyright (c) 2015-2023 CESNET, z.s.p.o.
Radek Krejci7931b192020-06-25 17:05:03 +02008 *
9 * This source code is licensed under BSD 3-Clause License (the "License").
10 * You may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * https://opensource.org/licenses/BSD-3-Clause
14 */
15
16#ifndef LY_PARSER_DATA_H_
17#define LY_PARSER_DATA_H_
18
19#include "tree_data.h"
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25struct ly_in;
26
27/**
Radek Krejci8678fa42020-08-18 16:07:28 +020028 * @page howtoDataParsers Parsing Data
29 *
30 * Data parser allows to read instances from a specific format. libyang supports the following data formats:
31 *
32 * - XML
33 *
34 * Original data format used in NETCONF protocol. XML mapping is part of the YANG specification
35 * ([RFC 6020](http://tools.ietf.org/html/rfc6020)).
36 *
37 * - JSON
38 *
39 * The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG
40 * can be found in [RFC 7951](http://tools.ietf.org/html/rfc7951). The specification does not cover RPCs, actions and
41 * Notifications, so the representation of these data trees is proprietary and corresponds to the representation of these
42 * trees in XML.
43 *
44 * While the parsers themselves process the input data only syntactically, all the parser functions actually incorporate
45 * the [common validator](@ref howtoDataValidation) checking the input data semantically. Therefore, the parser functions
46 * accepts two groups of options - @ref dataparseroptions and @ref datavalidationoptions.
47 *
48 * In contrast to the schema parser, data parser also accepts empty input data if such an empty data tree is valid
49 * according to the schemas in the libyang context (i.e. there are no top level mandatory nodes).
50 *
51 * There are individual functions to process different types of the data instances trees:
52 * - ::lyd_parse_data() is intended for standard configuration data trees. According to the given
53 * [parser options](@ref dataparseroptions), the caller can further specify which kind of data tree is expected:
54 * - *complete :running datastore*: this is the default case, possibly with the use of (some of) the
55 * ::LYD_PARSE_STRICT, ::LYD_PARSE_OPAQ or ::LYD_VALIDATE_PRESENT options.
56 * - *complete configuration-only datastore* (such as :startup): in this case it is necessary to except all state data
57 * using ::LYD_PARSE_NO_STATE option.
58 * - *incomplete datastore*: there are situation when the data tree is incomplete or invalid by specification. For
59 * example the *:operational* datastore is not necessarily valid and results of the NETCONF's \<get\> or \<get-config\>
60 * oprations used with filters will be incomplete (and thus invalid). This can be allowed using ::LYD_PARSE_ONLY,
61 * the ::LYD_PARSE_NO_STATE should be used for the data returned by \<get-config\> operation.
Radek Krejcif16e2542021-02-17 15:39:23 +010062 * - ::lyd_parse_ext_data() is used for parsing configuration data trees defined inside extension instances, such as
63 * instances of yang-data extension specified in [RFC 8040](http://tools.ietf.org/html/rfc8040).
Michal Vaskoe0665742021-02-11 11:08:44 +010064 * - ::lyd_parse_op() is used for parsing RPCs/actions, replies, and notifications. Even NETCONF rpc, rpc-reply, and
Radek Krejcif16e2542021-02-17 15:39:23 +010065 * notification messages are supported.
66 * - ::lyd_parse_ext_op() is used for parsing RPCs/actions, replies, and notifications defined inside extension instances.
Radek Krejci8678fa42020-08-18 16:07:28 +020067 *
68 * Further information regarding the processing input instance data can be found on the following pages.
69 * - @subpage howtoDataValidation
70 * - @subpage howtoDataWD
71 *
72 * Functions List
73 * --------------
74 * - ::lyd_parse_data()
75 * - ::lyd_parse_data_mem()
76 * - ::lyd_parse_data_fd()
77 * - ::lyd_parse_data_path()
Radek Krejcif16e2542021-02-17 15:39:23 +010078 * - ::lyd_parse_ext_data()
Michal Vaskoe0665742021-02-11 11:08:44 +010079 * - ::lyd_parse_op()
Radek Krejcif16e2542021-02-17 15:39:23 +010080 * - ::lyd_parse_ext_op()
Radek Krejci8678fa42020-08-18 16:07:28 +020081 */
82
83/**
84 * @page howtoDataValidation Validating Data
85 *
86 * Data validation is performed implicitly to the input data processed by the [parser](@ref howtoDataParsers) and
87 * on demand via the lyd_validate_*() functions. The explicit validation process is supposed to be used when a (complex or
88 * simple) change is done on the data tree (via [data manipulation](@ref howtoDataManipulation) functions) and the data
89 * tree is expected to be valid (it doesn't make sense to validate modified result of filtered \<get\> operation).
90 *
91 * Similarly to the [data parser](@ref howtoDataParsers), there are individual functions to validate standard data tree
92 * (::lyd_validate_all()) and RPC, Action and Notification (::lyd_validate_op()). For the standard data trees, it is possible
93 * to modify the validation process by @ref datavalidationoptions. This way the state data can be prohibited
94 * (::LYD_VALIDATE_NO_STATE) and checking for mandatory nodes can be limited to the YANG modules with already present data
95 * instances (::LYD_VALIDATE_PRESENT). Validation of the standard data tree can be also limited with ::lyd_validate_module()
96 * function, which scopes only to a specified single YANG module.
97 *
98 * Since the operation data trees (RPCs, Actions or Notifications) can reference (leafref, instance-identifier, when/must
99 * expressions) data from a datastore tree, ::lyd_validate_op() may require additional data tree to be provided. This is a
100 * difference in contrast to the parsing process, when the data are loaded from an external source and invalid reference
101 * outside the operation tree is acceptable.
102 *
103 * Functions List
104 * --------------
105 * - ::lyd_validate_all()
106 * - ::lyd_validate_module()
107 * - ::lyd_validate_op()
108 */
109
110/**
Radek Krejci7931b192020-06-25 17:05:03 +0200111 * @addtogroup datatree
112 * @{
113 */
114
115/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200116 * @ingroup datatree
Radek Krejci7931b192020-06-25 17:05:03 +0200117 * @defgroup dataparseroptions Data parser options
118 *
119 * Various options to change the data tree parsers behavior.
120 *
121 * Default parser behavior:
122 * - complete input file is always parsed. In case of XML, even not well-formed XML document (multiple top-level
123 * elements) is parsed in its entirety,
Michal Vasko78041d12022-11-29 14:11:07 +0100124 * - parser silently ignores data without matching schema node definition (for LYB format an error),
Radek Krejci7931b192020-06-25 17:05:03 +0200125 * - list instances are checked whether they have all the keys, error is raised if not.
126 *
127 * Default parser validation behavior:
128 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
129 * and performs data validation according to all YANG rules, specifics follow,
130 * - list instances are expected to have all the keys (it is not checked),
131 * - instantiated (status) obsolete data print a warning,
132 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
133 * all the keys, leaf(-lists) correct values),
134 * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
Radek Krejci7931b192020-06-25 17:05:03 +0200135 * - invalid multiple data instances/data from several cases cause a validation error,
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200136 * - implicit nodes (NP containers and default values) are added.
Radek Krejci7931b192020-06-25 17:05:03 +0200137 * @{
138 */
139/* note: keep the lower 16bits free for use by LYD_VALIDATE_ flags. They are not supposed to be combined together,
140 * but since they are used (as a separate parameter) together in some functions, we want to keep them in a separated
141 * range to be able detect that the caller put wrong flags into the parser/validate options parameter. */
Michal Vaskoabd34fb2024-02-21 09:53:56 +0100142#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no data validation will be performed but
143 type value restrictions will be checked (unlike ::LYD_PARSE_STORE_ONLY).
144 When statements are kept unevaluated, union types may not be fully
145 resolved, and default values are not added (only the ones parsed are
146 present). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100147#define LYD_PARSE_STRICT 0x020000 /**< Instead of silently ignoring data without schema definition raise an error.
Michal Vasko369f7a62021-02-01 08:59:36 +0100148 Do not combine with ::LYD_PARSE_OPAQ (except for ::LYD_LYB). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100149#define LYD_PARSE_OPAQ 0x040000 /**< Instead of silently ignoring data without definition, parse them into
Michal Vasko369f7a62021-02-01 08:59:36 +0100150 an opaq node. Do not combine with ::LYD_PARSE_STRICT (except for ::LYD_LYB). */
151#define LYD_PARSE_NO_STATE 0x080000 /**< Forbid state data in the parsed data. Usually used with ::LYD_VALIDATE_NO_STATE. */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100152#define LYD_PARSE_LYB_MOD_UPDATE 0x100000 /**< Only for LYB format, allow parsing data printed using a specific module
Radek Krejci7931b192020-06-25 17:05:03 +0200153 revision to be loaded even with a module with the same name but newer
154 revision. */
Michal Vasko6ee6f432021-07-16 09:49:14 +0200155#define LYD_PARSE_ORDERED 0x200000 /**< Do not search for the correct place of each node but instead expect
156 that the nodes are being parsed in the correct schema-based order,
157 which is always true if the data were printed by libyang and not
158 modified manually. If this flag is used incorrectly (for unordered data),
159 the behavior is undefined and most functions executed with these
160 data will not work correctly. */
Jan Kundrátd49adf82023-11-01 15:46:36 +0100161#define LYD_PARSE_SUBTREE 0x400000 /**< Parse only the first child item along with any descendants, but no
162 siblings. This flag is not required when parsing data which do not
163 start at the schema root; for that purpose, use lyd_parse_data's parent
164 argument.
Michal Vaskoddd76592022-01-17 13:34:48 +0100165 Also, a new return value ::LY_ENOT is returned if there is a sibling
Michal Vasko0820b5b2023-10-03 12:00:01 +0200166 subtree following in the input data. Note that if validation is requested,
Jan Kundrátd49adf82023-11-01 15:46:36 +0100167 only the newly parsed subtree is validated. This might result in
168 an invalid datastore content. */
Michal Vaskofbb48c22022-11-30 13:28:03 +0100169#define LYD_PARSE_WHEN_TRUE 0x800000 /**< Mark all the parsed nodes dependend on a when condition with the flag
170 that means the condition was satisifed before. This allows for
171 auto-deletion of these nodes during validation. */
Michal Vaskobc9f76f2022-12-01 10:31:38 +0100172#define LYD_PARSE_NO_NEW 0x1000000 /**< Do not set ::LYD_NEW (non-validated node flag) for any nodes. Use
173 when parsing validated data to skip some validation tasks and modify
174 some validation behavior (auto-deletion of cases). */
Michal Vaskoa5c4fa42024-02-26 14:04:00 +0100175#define LYD_PARSE_STORE_ONLY 0x2010000 /**< Similar to ::LYD_PARSE_ONLY but even type value restrictions will not
Michal Vaskoabd34fb2024-02-21 09:53:56 +0100176 be checked (length, range, pattern, ...) and if a value can be stored,
177 it is. Calling separate validation on these data always checks all the
178 restrictions as well. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200179
180#define LYD_PARSE_OPTS_MASK 0xFFFF0000 /**< Mask for all the LYD_PARSE_ options. */
181
Radek Krejci7931b192020-06-25 17:05:03 +0200182/** @} dataparseroptions */
183
Radek Krejci7931b192020-06-25 17:05:03 +0200184/**
Radek Krejci7931b192020-06-25 17:05:03 +0200185 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200186 * @defgroup datavalidationoptions Data validation options
Radek Krejci7931b192020-06-25 17:05:03 +0200187 *
188 * Various options to change data validation behaviour, both for the parser and separate validation.
189 *
190 * Default separate validation behavior:
191 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
192 * and performs data validation according to all YANG rules, specifics follow,
193 * - instantiated (status) obsolete data print a warning,
194 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
195 * all the keys, leaf(-lists) correct values),
196 * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation
197 * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error
198 * is raised if it evaluates to false,
199 * - if-feature statements are evaluated,
200 * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed
201 * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or
202 * more cases were created) a validation error is raised,
203 * - default values are added.
204 *
205 * @{
206 */
Michal Vasko369f7a62021-02-01 08:59:36 +0100207#define LYD_VALIDATE_NO_STATE 0x0001 /**< Consider state data not allowed and raise an error if they are found.
208 Also, no implicit state data are added. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200209#define LYD_VALIDATE_PRESENT 0x0002 /**< Validate only modules whose data actually exist. */
Michal Vaskod027f382023-02-10 09:13:25 +0100210#define LYD_VALIDATE_MULTI_ERROR 0x0004 /**< Do not stop validation on the first error but generate all the detected errors. */
Michal Vasko6b14c7e2023-11-09 12:08:14 +0100211#define LYD_VALIDATE_OPERATIONAL 0x0008 /**< Semantic constraint violations are reported only as warnings instead of
212 errors (see [RFC 8342 sec. 5.3](https://datatracker.ietf.org/doc/html/rfc8342#section-5.3)). */
Michal Vaskoaf5a8dd2023-03-02 11:25:02 +0100213#define LYD_VALIDATE_NO_DEFAULTS 0x0010 /**< Do not add any default nodes during validation, other implicit nodes
214 (such as NP containers) are still added. Validation will fail if a
215 default node is required for it to pass. */
Michal Vasko6b14c7e2023-11-09 12:08:14 +0100216#define LYD_VALIDATE_NOT_FINAL 0x0020 /**< Skip final validation tasks that require for all the data nodes to
217 either exist or not, based on the YANG constraints. Once the data
218 satisfy this requirement, the final validation should be performed. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200219
220#define LYD_VALIDATE_OPTS_MASK 0x0000FFFF /**< Mask for all the LYD_VALIDATE_* options. */
Radek Krejci7931b192020-06-25 17:05:03 +0200221
222/** @} datavalidationoptions */
223
224/**
Radek Krejci7931b192020-06-25 17:05:03 +0200225 * @brief Parse (and validate) data from the input handler as a YANG data tree.
226 *
227 * @param[in] ctx Context to connect with the tree being built here.
Jan Kundrátd49adf82023-11-01 15:46:36 +0100228 * @param[in] parent Optional parent to connect the parsed nodes to. If provided, the data are expected to describe
229 * a subtree of the YANG model instead of starting at the schema root.
Radek Krejci7931b192020-06-25 17:05:03 +0200230 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
231 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
232 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
233 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskob36c56f2024-01-31 12:50:07 +0100234 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, the first parsed child.
Radek Krejci7931b192020-06-25 17:05:03 +0200235 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200236 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Jan Kundrátd49adf82023-11-01 15:46:36 +0100237 *
238 * When parsing subtrees (i.e., when @p parent is non-NULL), validation is only performed on the newly parsed data.
239 * This might result in allowing invalid datastore content when the schema contains cross-branch constraints,
240 * complicated `must` statements, etc. When a full-datastore validation is desirable, parse all subtrees
241 * first, and then request validation of the complete datastore content.
Radek Krejci7931b192020-06-25 17:05:03 +0200242 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100243LIBYANG_API_DECL LY_ERR lyd_parse_data(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
Michal Vaskoe0665742021-02-11 11:08:44 +0100244 uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200245
246/**
247 * @brief Parse (and validate) input data as a YANG data tree.
248 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100249 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200250 *
251 * @param[in] ctx Context to connect with the tree being built here.
252 * @param[in] data The input data in the specified @p format to parse (and validate).
Michal Vasko107c8162021-09-23 11:21:53 +0200253 * @param[in] format Format of the input data to be parsed.
Radek Krejci7931b192020-06-25 17:05:03 +0200254 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
255 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100256 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200257 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200258 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200259 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100260LIBYANG_API_DECL LY_ERR lyd_parse_data_mem(const struct ly_ctx *ctx, const char *data, LYD_FORMAT format, uint32_t parse_options,
Radek Krejci1deb5be2020-08-26 16:43:36 +0200261 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200262
263/**
264 * @brief Parse (and validate) input data as a YANG data tree.
265 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100266 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200267 *
268 * @param[in] ctx Context to connect with the tree being built here.
Michal Vaskoe0665742021-02-11 11:08:44 +0100269 * @param[in] fd File descriptor of a regular file (e.g. sockets are not supported) containing the input data in the
270 * specified @p format to parse.
Michal Vasko107c8162021-09-23 11:21:53 +0200271 * @param[in] format Format of the input data to be parsed.
Radek Krejci7931b192020-06-25 17:05:03 +0200272 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
273 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100274 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200275 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200276 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200277 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100278LIBYANG_API_DECL LY_ERR lyd_parse_data_fd(const struct ly_ctx *ctx, int fd, LYD_FORMAT format, uint32_t parse_options,
Michal Vaskoe0665742021-02-11 11:08:44 +0100279 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200280
281/**
282 * @brief Parse (and validate) input data as a YANG data tree.
283 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100284 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200285 *
286 * @param[in] ctx Context to connect with the tree being built here.
287 * @param[in] path Path to the file with the input data in the specified @p format to parse (and validate).
Michal Vasko107c8162021-09-23 11:21:53 +0200288 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from @p path extension.
Radek Krejci7931b192020-06-25 17:05:03 +0200289 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
290 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100291 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200292 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200293 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200294 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100295LIBYANG_API_DECL LY_ERR lyd_parse_data_path(const struct ly_ctx *ctx, const char *path, LYD_FORMAT format,
296 uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200297
298/**
Radek Krejci75104122021-04-01 15:37:45 +0200299 * @brief Parse (and validate) data from the input handler as an extension data tree following the schema tree of the given
Radek Krejcif16e2542021-02-17 15:39:23 +0100300 * extension instance.
301 *
302 * Note that the data being parsed are limited only to the schema tree specified by the given extension, it does not allow
303 * to mix them with the standard data from any module.
304 *
Radek Krejci75104122021-04-01 15:37:45 +0200305 * Directly applicable to data defined as [yang-data](@ref howtoDataYangdata).
306 *
Radek Krejcif16e2542021-02-17 15:39:23 +0100307 * @param[in] ext Extension instance providing the specific schema tree to match with the data being parsed.
308 * @param[in] parent Optional parent to connect the parsed nodes to.
309 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
310 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
311 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
312 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
313 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, set to NULL.
314 * @return LY_SUCCESS in case of successful parsing (and validation).
315 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
316 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100317LIBYANG_API_DECL LY_ERR lyd_parse_ext_data(const struct lysc_ext_instance *ext, struct lyd_node *parent, struct ly_in *in,
318 LYD_FORMAT format, uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
Radek Krejcif16e2542021-02-17 15:39:23 +0100319
320/**
Michal Vaskoe0665742021-02-11 11:08:44 +0100321 * @ingroup datatree
322 * @defgroup datatype Data operation type
Radek Krejci7931b192020-06-25 17:05:03 +0200323 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100324 * Operation provided to ::lyd_validate_op() to validate.
325 *
326 * The operation cannot be determined automatically since RPC/action and a reply to it share the common top level node
327 * referencing the RPC/action schema node and may not have any input/output children to use for distinction.
328 *
329 * @{
Radek Krejci7931b192020-06-25 17:05:03 +0200330 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100331enum lyd_type {
Michal Vasko820efe82023-05-12 15:47:43 +0200332 LYD_TYPE_DATA_YANG = 0, /* generic YANG instance data */
333 LYD_TYPE_RPC_YANG, /* instance of a YANG RPC/action request with only "input" data children,
Michal Vasko64592692023-06-12 13:50:11 +0200334 including all parents and optional top-level "action" element in case of an action */
Michal Vasko820efe82023-05-12 15:47:43 +0200335 LYD_TYPE_NOTIF_YANG, /* instance of a YANG notification, including all parents in case of a nested one */
336 LYD_TYPE_REPLY_YANG, /* instance of a YANG RPC/action reply with only "output" data children,
337 including all parents in case of an action */
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100338
Michal Vasko820efe82023-05-12 15:47:43 +0200339 LYD_TYPE_RPC_NETCONF, /* complete NETCONF RPC invocation as defined for
340 [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
341 [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
342 LYD_TYPE_NOTIF_NETCONF, /* complete NETCONF notification message as defined for
343 [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */
344 LYD_TYPE_REPLY_NETCONF, /* complete NETCONF RPC reply as defined for
345 [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
346 [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
347
348 LYD_TYPE_RPC_RESTCONF, /* message-body of a RESTCONF operation input parameters
349 ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.1)) */
350 LYD_TYPE_NOTIF_RESTCONF, /* RESTCONF JSON notification data
351 ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-6.4)), to parse
352 a notification in XML, use ::LYD_TYPE_NOTIF_NETCONF */
353 LYD_TYPE_REPLY_RESTCONF /* message-body of a RESTCONF operation output parameters
354 ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.2)) */
Michal Vaskoe0665742021-02-11 11:08:44 +0100355};
356/** @} datatype */
Radek Krejci7931b192020-06-25 17:05:03 +0200357
358/**
Michal Vasko2d4d3692023-05-04 08:52:03 +0200359 * @brief Parse YANG data into an operation data tree. Specific parsing flags ::LYD_PARSE_ONLY, ::LYD_PARSE_STRICT and
360 * no validation flags are used.
Radek Krejci7931b192020-06-25 17:05:03 +0200361 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100362 * At least one of @p parent, @p tree, or @p op must always be set.
Radek Krejci7931b192020-06-25 17:05:03 +0200363 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100364 * Specific @p data_type values have different parameter meaning as follows:
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100365 * - ::LYD_TYPE_RPC_NETCONF:
Michal Vaskoe0665742021-02-11 11:08:44 +0100366 * - @p parent - must be NULL, the whole RPC is expected;
367 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
368 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vasko299d5d12021-02-16 16:36:37 +0100369 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vaskoe0665742021-02-11 11:08:44 +0100370 * - @p op - must be provided, the RPC/action data tree itself will be returned here, pointing to the operation;
371 *
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100372 * - ::LYD_TYPE_NOTIF_NETCONF:
373 * - @p parent - must be NULL, the whole notification is expected;
374 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
375 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vaskof4da8892021-02-19 09:15:18 +0100376 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100377 * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
378 *
379 * - ::LYD_TYPE_REPLY_NETCONF:
Michal Vaskoe0665742021-02-11 11:08:44 +0100380 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
381 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
382 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vaskof4da8892021-02-19 09:15:18 +0100383 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100384 * - @p op - must be NULL, the reply is appended to the RPC;
385 * Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC.
Michal Vaskoe0665742021-02-11 11:08:44 +0100386 *
Michal Vasko820efe82023-05-12 15:47:43 +0200387 * - ::LYD_TYPE_RPC_RESTCONF:
388 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
389 * - @p format - can be both ::LYD_JSON and ::LYD_XML;
390 * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
391 * a separate opaque data tree, even if the function fails, this may be returned;
392 * - @p op - must be NULL, @p parent points to the operation;
393 *
394 * - ::LYD_TYPE_NOTIF_RESTCONF:
395 * - @p parent - must be NULL, the whole notification is expected;
396 * - @p format - must be ::LYD_JSON, XML-formatted notifications are parsed using ::LYD_TYPE_NOTIF_NETCONF;
397 * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
398 * a separate opaque data tree, even if the function fails, this may be returned;
399 * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
400 *
401 * - ::LYD_TYPE_REPLY_RESTCONF:
402 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
403 * - @p format - can be both ::LYD_JSON and ::LYD_XML;
404 * - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
405 * a separate opaque data tree, even if the function fails, this may be returned;
406 * - @p op - must be NULL, @p parent points to the operation;
407 * Note that error reply should be parsed as 'yang-data' extension data.
408 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100409 * @param[in] ctx libyang context.
410 * @param[in] parent Optional parent to connect the parsed nodes to.
411 * @param[in] in Input handle to read the input from.
412 * @param[in] format Expected format of the data in @p in.
413 * @param[in] data_type Expected operation to parse (@ref datatype).
414 * @param[out] tree Optional full parsed data tree. If @p parent is set, set to NULL.
Michal Vasko438b5292021-06-09 14:31:25 +0200415 * @param[out] op Optional pointer to the operation (action/RPC) node.
Michal Vaskoe0665742021-02-11 11:08:44 +0100416 * @return LY_ERR value.
Michal Vaskob7dba862021-02-18 16:10:02 +0100417 * @return LY_ENOT if @p data_type is a NETCONF message and the root XML element is not the expected one.
Radek Krejci7931b192020-06-25 17:05:03 +0200418 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100419LIBYANG_API_DECL LY_ERR lyd_parse_op(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
Michal Vaskoe0665742021-02-11 11:08:44 +0100420 enum lyd_type data_type, struct lyd_node **tree, struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200421
422/**
Radek Krejci75104122021-04-01 15:37:45 +0200423 * @brief Parse extension data into an operation data tree following only the specification from the given extension instance.
424 *
425 * Directly applicable to data defined as [yang-data](@ref howtoDataYangdata).
Radek Krejcif16e2542021-02-17 15:39:23 +0100426 *
427 * At least one of @p parent, @p tree, or @p op must always be set.
428 *
429 * Specific @p data_type values have different parameter meaning as follows:
430 * - ::LYD_TYPE_RPC_NETCONF:
431 * - @p parent - must be NULL, the whole RPC is expected;
432 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
433 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
434 * a separate opaque data tree, even if the function fails, this may be returned;
435 * - @p op - must be provided, the RPC/action data tree itself will be returned here, pointing to the operation;
436 *
437 * - ::LYD_TYPE_NOTIF_NETCONF:
438 * - @p parent - must be NULL, the whole notification is expected;
439 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
440 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
441 * a separate opaque data tree, even if the function fails, this may be returned;
442 * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
443 *
444 * - ::LYD_TYPE_REPLY_NETCONF:
445 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
446 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
447 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
448 * a separate opaque data tree, even if the function fails, this may be returned;
449 * - @p op - must be NULL, the reply is appended to the RPC;
450 * Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC.
451 *
452 * @param[in] ext Extension instance providing the specific schema tree to match with the data being parsed.
453 * @param[in] parent Optional parent to connect the parsed nodes to.
454 * @param[in] in Input handle to read the input from.
455 * @param[in] format Expected format of the data in @p in.
456 * @param[in] data_type Expected operation to parse (@ref datatype).
457 * @param[out] tree Optional full parsed data tree. If @p parent is set, set to NULL.
Michal Vasko438b5292021-06-09 14:31:25 +0200458 * @param[out] op Optional pointer to the operation (action/RPC) node.
Radek Krejcif16e2542021-02-17 15:39:23 +0100459 * @return LY_ERR value.
460 * @return LY_ENOT if @p data_type is a NETCONF message and the root XML element is not the expected one.
461 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100462LIBYANG_API_DECL LY_ERR lyd_parse_ext_op(const struct lysc_ext_instance *ext, struct lyd_node *parent, struct ly_in *in,
463 LYD_FORMAT format, enum lyd_type data_type, struct lyd_node **tree, struct lyd_node **op);
Radek Krejcif16e2542021-02-17 15:39:23 +0100464
465/**
Radek Krejci7931b192020-06-25 17:05:03 +0200466 * @brief Fully validate a data tree.
467 *
Michal Vaskoddd76592022-01-17 13:34:48 +0100468 * The data tree is modified in-place. As a result of the validation, some data might be removed
Jan Kundrát94747632021-10-14 16:23:09 +0200469 * from the tree. In that case, the removed items are freed, not just unlinked.
470 *
471 * @param[in,out] tree Data tree to recursively validate. May be changed by validation, might become NULL.
Radek Krejci7931b192020-06-25 17:05:03 +0200472 * @param[in] ctx libyang context. Can be NULL if @p tree is set.
473 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200474 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200475 * @return LY_SUCCESS on success.
476 * @return LY_ERR error on error.
477 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100478LIBYANG_API_DECL LY_ERR lyd_validate_all(struct lyd_node **tree, const struct ly_ctx *ctx, uint32_t val_opts,
479 struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200480
481/**
Michal Vasko26e80012020-07-08 10:55:46 +0200482 * @brief Fully validate a data tree of a module.
Radek Krejci7931b192020-06-25 17:05:03 +0200483 *
Michal Vaskoddd76592022-01-17 13:34:48 +0100484 * The data tree is modified in-place. As a result of the validation, some data might be removed
Jan Kundrát94747632021-10-14 16:23:09 +0200485 * from the tree. In that case, the removed items are freed, not just unlinked.
486 *
Michal Vasko6b14c7e2023-11-09 12:08:14 +0100487 * If several modules need to be validated, the flag ::LYD_VALIDATE_NOT_FINAL should be used first for validation
488 * of each module and then ::lyd_validate_module_final() should be called also for each module. Otherwise,
489 * false-positive validation errors for foreign dependencies may occur.
490 *
Jan Kundrát94747632021-10-14 16:23:09 +0200491 * @param[in,out] tree Data tree to recursively validate. May be changed by validation, might become NULL.
Michal Vasko26e80012020-07-08 10:55:46 +0200492 * @param[in] module Module whose data (and schema restrictions) to validate.
Radek Krejci7931b192020-06-25 17:05:03 +0200493 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200494 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200495 * @return LY_SUCCESS on success.
496 * @return LY_ERR error on error.
497 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100498LIBYANG_API_DECL LY_ERR lyd_validate_module(struct lyd_node **tree, const struct lys_module *module, uint32_t val_opts,
499 struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200500
501/**
Michal Vasko6b14c7e2023-11-09 12:08:14 +0100502 * @brief Finish validation of a module data that have previously been validated with ::LYD_VALIDATE_NOT_FINAL flag.
503 *
504 * This final validation will not add or remove any nodes.
505 *
506 * @param[in] tree Data tree to recursively validate.
507 * @param[in] module Module whose data (and schema restrictions) to validate.
508 * @param[in] val_opts Validation options (@ref datavalidationoptions).
509 * @return LY_SUCCESS on success.
510 * @return LY_ERR error on error.
511 */
512LIBYANG_API_DECL LY_ERR lyd_validate_module_final(struct lyd_node *tree, const struct lys_module *module,
513 uint32_t val_opts);
514
515/**
Michal Vasko0bec3222022-04-22 07:46:00 +0200516 * @brief Validate an RPC/action request, reply, or notification. Only the operation data tree (input/output/notif)
517 * is validate, any parents are ignored.
Radek Krejci7931b192020-06-25 17:05:03 +0200518 *
519 * @param[in,out] op_tree Operation tree with any parents. It can point to the operation itself or any of
520 * its parents, only the operation subtree is actually validated.
Michal Vaskoe0665742021-02-11 11:08:44 +0100521 * @param[in] dep_tree Tree to be used for validating references from the operation subtree.
522 * @param[in] data_type Operation type to validate (only YANG operations are accepted, @ref datatype).
Michal Vasko8104fd42020-07-13 11:09:51 +0200523 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200524 * @return LY_SUCCESS on success.
525 * @return LY_ERR error on error.
526 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100527LIBYANG_API_DECL LY_ERR lyd_validate_op(struct lyd_node *op_tree, const struct lyd_node *dep_tree, enum lyd_type data_type,
Michal Vaskoe0665742021-02-11 11:08:44 +0100528 struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200529
530/** @} datatree */
531
532#ifdef __cplusplus
533}
534#endif
535
536#endif /* LY_PARSER_DATA_H_ */