summaryrefslogtreecommitdiffstats
path: root/tools/lint/examples/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--tools/lint/examples/README.md471
1 files changed, 471 insertions, 0 deletions
diff --git a/tools/lint/examples/README.md b/tools/lint/examples/README.md
new file mode 100644
index 0000000..604591c
--- /dev/null
+++ b/tools/lint/examples/README.md
@@ -0,0 +1,471 @@
+# YANGLINT - Interactive Mode Examples
+
+This text provides several use-case of the `yanglint(1)` interactive
+mode. For basic information about the `yanglint(1)` usage, please see
+the man page.
+
+The examples are supposed to be went through one by one. Some of the examples
+suppose the specific schemas loaded in some of the previous example is still
+loaded. If an addition work is need, the *preparation* part in the example
+provides information what to do.
+
+To show all available command of the `yanglint(1)`, use the `help` command:
+```
+> help
+Available commands:
+ help Display commands description
+ add Add a new module from a specific file
+ load Load a new schema from the searchdirs
+ print Print a module
+ data Load, validate and optionally print instance data
+ list List all the loaded modules
+ feature Print all features of module(s) with their state
+ searchpath Print/set the search path(s) for schemas
+ clear Clear the context - remove all the loaded modules
+ verb Change verbosity
+ debug Display specific debug message groups
+ quit Quit the program
+ ? Display commands description
+ exit Quit the program
+```
+To show the information about the specific command, use the `help` command in
+combination with the command name you are interested in:
+```
+> help searchpath
+Usage: searchpath [--clear] [<modules-dir-path> ...]
+ Set paths of directories where to search for imports and
+ includes of the schema modules. The current working directory
+ and the path of the module being added is used implicitly.
+ The 'load' command uses these paths to search even for the
+ schema modules to be loaded.
+```
+
+The input files referred in this document are available together with this
+document.
+
+## Duplicit Data Model
+
+Let's have two data models [module1.yang](./module1.yang)
+and [module1b.yang](./module1b.yang).
+They differ in the module name but their namespaces are the same.
+
+Preparation:
+
+```
+> clear
+> add module1.yang
+> list
+```
+
+Output:
+
+```
+List of the loaded models:
+ i ietf-yang-metadata@2016-08-05
+ I yang@2022-06-16
+ i ietf-inet-types@2013-07-15
+ i ietf-yang-types@2013-07-15
+ I ietf-yang-schema-mount@2019-01-14
+ I module1
+```
+
+Command and its output:
+
+```
+> add module1b.yang
+libyang[0]: Two different modules ("module1" and "module1b") have the same namespace "urn:yanglint:module".
+libyang[0]: Parsing module "module1b" failed.
+```
+
+## Yang Data Model Validation
+
+**YANG/YIN syntax**
+
+`module2.yin` contains a syntax error.
+There is a bad syntax of the `type` statement in YIN file.
+
+```
+<type value="string"/>
+```
+
+instead of
+
+```
+<type name="string"/>
+```
+
+Preparation:
+
+```
+> clear
+```
+
+Command and its output:
+
+```
+> add module2.yin
+libyang[0]: Unexpected attribute "value" of "type" element. (path: Line number 8.)
+libyang[0]: Parsing module "module2" failed.
+```
+
+Similarly, there is a typo in `module2.yang`.
+
+**XPath errors**
+
+`libyang` and `yanglint(1)` is able to detect also errors in XPath expressions.
+In `module3.yang` the `must` expression refers to the node which does not exists.
+
+Preparation:
+
+```
+> clear
+```
+
+Command and its output:
+
+```
+> add module3.yang
+libyang[1]: Schema node "a" for parent "/module3:c" not found; in expr "../c/a" with context node "/module3:m".
+```
+
+Note that libyang prints only a warning in this case because it is not
+specified that XPath expressions must refer to existing nodes.
+
+## Data Validation
+
+Preparation:
+
+```
+> clear
+> add ietf-netconf-acm.yang
+```
+
+**Unknown data**
+
+By default, yanglint ignores unknown data and no error is printed (you can
+compare real content of the `datastore.xml` file and what yanglint prints
+in the following command if you add `-f xml` option).
+
+Command and its output:
+
+```
+> data -t config datastore.xml
+```
+
+We use option `-t` to specify type of the data in `datastore.xml`. By the
+`config` value we declare that the input file contains all the configuration
+data (with at least all the mandatory nodes as required by the loaded schemas),
+but without the status data. More examples of different data types will follow.
+
+Command and its output:
+
+```
+> data -t config datastore.xml
+libyang[0]: No module with namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces" in the context. (path: Line number 20.)
+YANGLINT[E]: Failed to parse input data file "datastore.xml".
+```
+
+Note that in case of working with complete datastore including the status data
+(no `-t` option is specified), `yanglint(1)` has to add status data from its
+internal `ietf-yang-library` module.
+
+**RPC and RPC-reply**
+
+It is possible to validate RPCs and their replies as well.
+
+Peparation:
+
+```
+> clear
+> add module4.yang
+```
+
+Command and its output:
+
+```
+> data -t rpc rpc.xml
+```
+
+Reply to this RPC can be validated too, but it must be nested in the original
+RPC element.
+
+Command and its output:
+
+```
+> data -t reply ../tools/lint/examples/rpc-reply.xml
+```
+
+**action and action-reply**
+
+Actions are validated the same way as RPCs except you need to be careful
+about the input file structure. No NETCONF-specific envelopes are expected.
+
+Preparation
+
+```
+> clear
+> add module4.yang
+```
+
+Command and its output:
+
+```
+> data -t rpc action.xml
+```
+
+Command and its output:
+
+```
+> data -t rpc action-reply.xml action.xml
+```
+
+**notification**
+
+Both top-level and nested notification can be validated.
+
+Preparation
+
+```
+> clear
+> add module4.yang
+```
+
+Command and its output:
+
+```
+> data -t notif notification.xml
+```
+
+Command and its output:
+
+```
+> data -t notif nested-notification.xml
+```
+
+
+**Multiple top-level elements in a single document**
+
+As a feature and in conflict with the XML definition, `yanglint(1)` (and libyang)
+is able to read XML files with multiple top-level elements. Such documents
+are not well-formed according to the XML spec, but it fits to how the YANG
+interconnects data trees (defined as top-level elements of a single schema
+or by multiple schemas).
+
+Preparation:
+
+```
+> clear
+> add ietf-netconf-acm.yang
+> add ietf-interfaces.yang
+> add ietf-ip.yang
+> add iana-if-type.yang
+```
+
+Command and its output:
+
+```
+> data -t config datastore.xml
+```
+
+**Different data content types**
+
+Since NETCONF requires the data described by YANG to be used in different
+situations (e.g. as <edit-config data>, result of the <get> with status data
+included or as a result of the <get-config> without the status data and
+possibly filtered, so without specified subtrees), it must be possible to
+specify which kind of data is going to be parsed. In `yanglint(1)`, this is done
+via `-t` option. The list of supported modes can be displayed by the `-h`
+option given to the `data` command. In general, the `auto` value lets the
+`yanglint(1)` to recognize the data type automatically by the additional top-level
+elements added to the parsed data. This is the same way as `pyang(1)` uses. Note,
+that the automatic data type recognition is available only for the XML input.
+
+**Malformed XML data**
+
+Command and its output:
+
+```
+> data -t edit config-missing-key.xml
+libyang[0]: Node "nam" not found as a child of "group" node. (path: Schema location "/ietf-netconf-acm:nacm/groups/group", data location "/ietf-netconf-acm:group", line number 19.)
+YANGLINT[E]: Failed to parse input data file "config-missing-key.xml".
+```
+
+**State information in edit-config XML**
+
+Command and its output:
+
+```
+> data -t edit config-unknown-element.xml
+libyang[0]: Unexpected data state node "denied-operations" found. (path: Schema location "/ietf-netconf-acm:nacm/denied-operations", data location "/ietf-netconf-acm:nacm", line number 24.)
+YANGLINT[E]: Failed to parse input data file "config-unknown-element.xml".
+```
+
+**Missing required element in NETCONF data**
+
+Command and its output:
+
+```
+> data data-missing-key.xml
+libyang[0]: List instance is missing its key "name". (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule", data location "/ietf-netconf-acm:rule", line number 10.)
+YANGLINT[E]: Failed to parse input data file "data-missing-key.xml".
+```
+
+**Malformed XML**
+
+Command and its output:
+
+```
+> data data-malformed-xml.xml
+libyang[0]: Node "nam" not found as a child of "rule" node. (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule", data location "/ietf-netconf-acm:rule", line number 8.)
+YANGLINT[E]: Failed to parse input data file "data-malformed-xml.xml".
+```
+
+Command and its output:
+
+```
+> data data-malformed-xml2.xml
+libyang[0]: Child element "module-name" inside a terminal node "name" found. (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule/name", data location "/ietf-netconf-acm:name", line number 7.)
+YANGLINT[E]: Failed to parse input data file "data-malformed-xml2.xml".
+```
+
+**Bad value**
+
+Command and its output:
+
+```
+> data data-out-of-range-value.xml
+libyang[0]: Value "-1" is out of type uint32 min/max bounds. (path: Schema location "/ietf-netconf-acm:nacm/denied-operations", data location "/ietf-netconf-acm:nacm", line number 24.)
+YANGLINT[E]: Failed to parse input data file "data-out-of-range-value.xml".
+```
+
+## Validation of "when" Statement in Data
+
+Preparation:
+
+```
+> clear
+> add ietf-netconf-acm-when.yang
+```
+
+**`When` condition is not satisfied since `denied-operation = 0`**
+
+Command and its output:
+
+```
+> data data-acm.xml
+libyang[0]: When condition "../denied-operations > 0" not satisfied. (path: Schema location "/ietf-netconf-acm-when:nacm/denied-data-writes", data location "/ietf-netconf-acm-when:nacm/denied-data-writes".)
+YANGLINT[E]: Failed to parse input data file "data-acm.xml".
+```
+
+## Printing a Data Model
+
+Preparation:
+
+```
+> clear
+> add ietf-netconf-acm.yang
+```
+
+**Print a `pyang`-style tree**
+
+Command and its output:
+
+```
+> print ietf-netconf-acm
+module: ietf-netconf-acm
+ +--rw nacm
+ +--rw enable-nacm? boolean
+ +--rw read-default? action-type
+ +--rw write-default? action-type
+ +--rw exec-default? action-type
+ +--rw enable-external-groups? boolean
+ +--ro denied-operations yang:zero-based-counter32
+ +--ro denied-data-writes yang:zero-based-counter32
+ +--ro denied-notifications yang:zero-based-counter32
+ +--rw groups
+ | +--rw group* [name]
+ | +--rw name group-name-type
+ | +--rw user-name* user-name-type
+ +--rw rule-list* [name]
+ +--rw name string
+ +--rw group* union
+ +--rw rule* [name]
+ +--rw name string
+ +--rw module-name? union
+ +--rw (rule-type)?
+ | +--:(protocol-operation)
+ | | +--rw rpc-name? union
+ | +--:(notification)
+ | | +--rw notification-name? union
+ | +--:(data-node)
+ | +--rw path node-instance-identifier
+ +--rw access-operations? union
+ +--rw action action-type
+ +--rw comment? string
+```
+
+**Print information about specific model part**
+
+Command and its output:
+
+```
+> print -f info -P /ietf-netconf-acm:nacm/ietf-netconf-acm:enable-nacm ietf-netconf-acm
+leaf enable-nacm {
+ ietf-netconf-acm:default-deny-all;
+ type boolean;
+ default "true";
+ config true;
+ status current;
+ description
+ "Enables or disables all NETCONF access control
+ enforcement. If 'true', then enforcement
+ is enabled. If 'false', then enforcement
+ is disabled.";
+}
+```
+
+## Usage of `feature` in Yang
+
+Preparation:
+
+```
+> clear
+> add ietf-interfaces.yang
+> add ietf-ip.yang -F ietf-ip:*
+> add iana-if-type.yang
+```
+
+Note: This example also shows `JSON` output of the command.
+
+Command and its output:
+```
+> feature ietf-ip
+ietf-ip features:
+ ipv4-non-contiguous-netmasks (on)
+ ipv6-privacy-autoconf (on)
+> data -f json -t config data-ip.xml
+{
+ "ietf-interfaces:interfaces": {
+ "interface": [
+ {
+ "name": "eth0",
+ "description": "Wire Connection",
+ "type": "iana-if-type:ethernetCsmacd",
+ "enabled": true,
+ "ietf-ip:ipv4": {
+ "address": [
+ {
+ "ip": "192.168.1.15",
+ "netmask": "255.255.255.0"
+ },
+ {
+ "ip": "192.168.1.10",
+ "netmask": "255.255.255.0"
+ }
+ ]
+ }
+ }
+ ]
+ }
+}
+```