pyang

PYANG(1)                         pyang manual                         PYANG(1)



NAME
       pyang - validate and convert YANG modules to various formats

SYNOPSIS
       pyang [--verbose] [--canonical] [--strict] [--lint] [--ietf]
             [--lax-xpath-checks] [--hello] [--check-update-from oldfile]
             [-o outfile] [-f format] [-p path] [-W warning] [-E error]
             file...

       pyang -h | --help

       pyang -v | --version

       One or more file parameters may be given on the command line. They
       denote either YANG modules to be processed (in YANG or YIN syntax) or,
       using the --hello switch, a server <hello> message conforming to RFC
       6241[1] and RFC 6020[2], which completely defines the data model -
       supported YANG modules as well as features and capabilities. In the
       latter case, only one file parameter may be present.

       If no files are given, pyang reads input from stdin, which must be one
       module or a server <hello> message.

DESCRIPTION
       The pyang program is used to validate YANG modules (RFC 6020[2]). It is
       also used to convert YANG modules into equivalent YIN modules. From a
       valid module a hybrid DSDL schema (RFC 6110[3]) can be generated.

       If no format is given, the specified modules are validated, and the
       program exits with exit code 0 if all modules are valid.

OPTIONS
       -h --help
           Print a short help text and exit.

       -v --version
           Print the version number and exit.

       -e --list-errors
           Print a listing of all error codes and messages pyang might
           generate, and then exit.

       --print-error-code
           On errors, print the symbolic error code instead of the error
           message.

       -Werror
           Treat warnings as errors.

       -Wnone
           Do not print any warnings.

       -W errorcode
           Treat errorcode as a warning, even if -Werror is given.  errorcode
           must be a warning or a minor error.

           Use --list-errors to get a listing of all errors and warnings.

           The following example treats all warnings except the warning for
           unused imports as errors:

               $ pyang --Werror -W UNUSED_IMPORT

       -E errorcode
           Treat the warning errorcode as an error.

           Use --list-errors to get a listing of all errors and warnings.

           The following example treats only the warning for unused import as
           an error:

               $ pyang --Werror -W UNUSED_IMPORT

       --ignore-error errorcode
           Ignore error errorcode.

           Use with care. Plugins that don't expect to be invoked if there are
           errors present may crash.

           Use --list-errors to get a listing of all errors and warnings.

           The following example ignores syntax errors in patterns:

               $ pyang --ignore-error PATTERN_ERROR

       --ignore-errors
           Ignore all errors. Use with care. Plugins that don't expect to be
           invoked if there are errors present may crash.

       --keep-comments
           This parameter has effect only if a plugin can handle comments. One
           example of such a plugin is the 'yang' output format plugin.

       --canonical
           Validate the module(s) according to the canonical YANG order.

       --strict
           Force strict YANG compliance. Currently this checks that the
           deref() function is not used in XPath expressions and leafrefs.

       --lint
           Validate the module(s) according to the generic YANG guideline as
           specified in RFC 6087[4]. In addition, it checks that the module is
           in canonical order.

       --ietf
           Validate the module(s) like --lint, and in addition verifies that
           the namespace and module name follow the IETF conventions.

       --lax-xpath-checks
           Lax checks of XPath expressions. Specifically, do not generate an
           error if an XPath expression uses a variable or an unknown
           function.

       -L --hello
           Interpret the input file or standard input as a server <hello>
           message. In this case, no more than one file parameter may be
           given.

       --trim-yin
           In YIN input modules, remove leading and trailing whitespace from
           every line in the arguments of the following statements: 'contact',
           'description', 'error-message', 'organization' and 'reference'.
           This way, the XML-indented argument texts look tidy after
           translating the module to the compact YANG syntax.

       --max-line-length maxlen
           Give a warning if any line is longer than maxlen. The value 0 means
           no check (default).

       --max-identifier-length maxlen
           Give a error if any identifier is longer than maxlen.

       -f --format format
           Convert the module(s) into format. Some translators require a
           single module, and some can translate multiple modules at one time.
           If no outfile file is specified, the result is printed on stdout.
           The supported formats are listed in OUTPUT FORMATS below.

       -o --output outfile
           Write the output to the file outfile instead of stdout.

       --features features
           features is a string on the form modulename:[feature(,feature)*]

           This option is used to prune the data model by removing all nodes
           that are defined with a "if-feature" that is not listed as feature.
           This option affects all output formats.

           This option can be given multiple times, and may be also combined
           with --hello. If a --features option specifies different supported
           features for a module than the hello file, the --features option
           takes precedence.

           If this option is not given, nothing is pruned, i.e., it works as
           if all features were explicitly listed.

           For example, to view the tree output for a module with all
           if-feature'd nodes removed, do:

               $ pyang -f tree --features mymod: mymod.yang

       --deviation-module file
           This option is used to apply the deviations defined in file. This
           option affects all output formats.

           This option can be given multiple times.

           For example, to view the tree output for a module with some
           deviations applied, do:

               $ pyang -f tree --deviation-module mymod-devs.yang mymod.yang

       -p --path path
           path is a colon (:) separated list of directories to search for
           imported modules. This option may be given multiple times.

           By default, all directories (except ".") found in the path are
           recursively scanned for modules. This behavior can be disabled by
           giving the option --no-path-recurse.

           The following directories are always added to the search path:

            1. current directory

            2. $YANG_MODPATH

            3. $HOME/yang/modules

            4. $YANG_INSTALL/yang/modules OR if $YANG_INSTALL is unset <the
               default installation directory>/yang/modules (on Unix systems:
               /usr/share/yang/modules)

       --no-path-recurse
           If this parameter is given, directories in the search path are not
           recursively scanned for modules.

       --plugindir plugindir
           Load all YANG plugins found in the directory plugindir. This option
           may be given multiple times.

           list of directories to search for pyang plugins. The following
           directories are always added to the search path:

            1. pyang/plugins from where pyang is installed

            2. $PYANG_PLUGINPATH

       --check-update-from oldfile
           Checks that a new revision of a module follows the update rules
           given in RFC 6020[2].  oldfile is the old module and file is the
           new version of the module.

           If the old module imports or includes any modules or submodules, it
           is important that the the old versions of these modules and
           submodules are found. By default, the directory where oldfile is
           found is used as the only directory in the search path for old
           modules. Use the option --check-update-from-path to control this
           path.

       -P --check-update-from-path oldpath
           oldpath is a colon (:) separated list of directories to search for
           imported modules. This option may be given multiple times.

       file...
           These are the names of the files containing the modules to be
           validated, or the module to be converted.

OUTPUT FORMATS
       Installed pyang plugins may define their own options, or add new
       formats to the -f option. These options and formats are listed in pyang
       -h.

       capability
           Capability URIs for each module of the data model.

       depend
           Makefile dependency rule for the module.

       dsdl
           Hybrid DSDL schema, see RFC 6110[3].

       jsonxsl
           XSLT stylesheet for transforming XML instance documents to JSON.

       jstree
           HTML/JavaScript tree navigator.

       jtox
           Driver file for transforming JSON instance documents to XML.

       name
           Module name, and the name of the main module for a submodule.

       omni
           An applescript file that draws a diagram in OmniGraffle.

       sample-xml-skeleton
           Skeleton of a sample XML instance document.

       tree
           Tree structure of the module.

       uml
           UML file that can be read by plantuml to generate UML diagrams.

       yang
           Normal YANG syntax.

       yin
           The XML syntax of YANG.

LINT CHECKER
       The lint option validates that the module follows the generic
       conventions and rules given in RFC 6087[4]. In addition, it checks that
       the module is in canonical order.

       Options for the lint checker:

       --lint-namespace-prefix prefix
           Validate that the module's namespace is on the form:
           "<prefix><modulename>".

       --lint-modulename-prefix prefix
           Validate that the module's name starts with prefix.

CAPABILITY OUTPUT
       The capability output prints a capability URL for each module of the
       input data model, taking into account features and deviations, as
       described in section 5.6.4 of RFC 6020[2].

       Options for the capability output format:

       --capability-entity
           Write ampersands in the output as XML entities ("&amp;").

DEPEND OUTPUT
       The depend output generates a Makefile dependency rule for files based
       on a YANG module. This is useful if files are generated from the
       module. For example, suppose a .c file is generated from each YANG
       module. If the YANG module imports other modules, or includes
       submodules, the .c file needs to be regenerated if any of the imported
       or included modules change. Such a dependency rule can be generated
       like this:

           $ pyang -f depend --depend-target mymod.c \
                 --depend-extension .yang mymod.yang
                 mymod.c : ietf-yang-types.yang my-types.yang

       Options for the depend output format:

       --depend-target
           Makefile rule target. Default is the module name.

       --depend-extension
           YANG module file name extension. Default is no extension.

       --depend-no-submodules
           Do not generate dependencies for included submodules.

       --depend-from-submodules
           Generate dependencies taken from all included submodules.

       --depend-recurse
           Recurse into imported modules and generate dependencies for their
           imported modules etc.

       --depend-include-path
           Include file path in the prerequisites. Note that if no
           --depend-extension has been given, the prerequisite is the filename
           as found, i.e., ending in ".yang" or ".yin".

       --depend-ignore-module
           Name of YANG module or submodule to ignore in the prerequisites.
           This option can be given multiple times.

DSDL OUTPUT
       The dsdl output takes a data model consisting of one or more YANG
       modules and generates a hybrid DSDL schema as described in RFC 6110[3].
       The hybrid schema is primarily intended as an interim product used by
       yang2dsdl(1).

       The dsdl plugin also supports metadata annotations, if they are defined
       and used as described in draft-lhotka-netmod-yang-metadata[5].

       Options for the dsdl output format:

       --dsdl-no-documentation
           Do not print documentation annotations

       --dsdl-no-dublin-core
           Do not print Dublin Core metadata terms

       --dsdl-record-defs
           Record translations of all top-level typedefs and groupings in the
           output schema, even if they are not used. This is useful for
           translating library modules.

JSONXSL OUTPUT
       The jsonxsl output generates an XSLT 1.0 stylesheet that can be used
       for transforming an XML instance document into JSON text as specified
       in draft-ietf-netmod-yang-json[6]. The XML document must be a valid
       instance of the data model which is specified as one or more input YANG
       modules on the command line (or via a <hello> message, see the --hello
       option).

       The jsonxsl plugin also converts metadata annotations, if they are
       defined and used as described in draft-lhotka-netmod-yang-metadata[5].

       The data tree(s) must be wrapped at least in either <nc:data> or
       <nc:config> element, where "nc" is the namespace prefix for the
       standard NETCONF URI "urn:ietf:params:xml:ns:netconf:base:1.0", or the
       XML instance document has to be a complete NETCONF RPC request/reply or
       notification. Translation of RPCs and notifications defined by the data
       model is also supported.

       The generated stylesheet accepts the following parameters that modify
       its behaviour:

       ·   compact: setting this parameter to 1 results in a compact
           representation of the JSON text, i.e. without any whitespace. The
           default is 0 which means that the JSON output is pretty-printed.

       ·   ind-step: indentation step, i.e. the number of spaces to use for
           each level. The default value is 2 spaces. Note that this setting
           is only useful for pretty-printed output (compact=0).

       The stylesheet also includes the file jsonxsl-templates.xsl which is a
       part of pyang distribution.

JSTREE OUTPUT
       The jstree output grenerates an HTML/JavaScript page that presents a
       tree-navigator to the given YANG module(s).

       jstree output specific option:

       --jstree-no-path
           Do not include paths in the output. This option makes the page less
           wide.

JTOX OUTPUT
       The jtox output generates a driver file which can be used as one of the
       inputs to json2xml for transforming a JSON document to XML as specified
       in draft-ietf-netmod-yang-json[6].

       The jtox output itself is a JSON document containing a concise
       representation of the data model which is specified as one or more
       input YANG modules on the command line (or via a <hello> message, see
       the --hello option).

       See json2xml manual page for more information.

OMNI OUTPUT
       The plugin generates an applescript file that draws a diagram in
       OmniGraffle. Requires OmniGraffle 6. Usage:

       omni output specific option:

       --omni-path path
           Subtree to print. The path is a slash ("/") separated path to a
           subtree to print. For example "/nacm/groups".

NAME OUTPUT
       The name output prints the name of each module in the input data model.
       For submodules, it also shows the name of the main module to which the
       submodule belongs.

SAMPLE-XML-SKELETON OUTPUT
       The sample-xml-skeleton output generates an XML instance document with
       sample elements for all nodes in the data model, according to the
       following rules:

       ·   An element is present for every leaf, container or anyxml.

       ·   At least one element is present for every leaf-list or list. The
           number of entries in the sample is min(1, min-elements).

       ·   For a choice node, sample element(s) are present for each case.

       ·   Leaf, leaf-list and anyxml elements are empty (but see the
           --sample-xml-skeleton-defaults option below).

       Note that the output document will most likely be invalid and needs
       manual editing.

       Options specific to the sample-xml-skeleton output format:

       --sample-xml-skeleton-annotations
           Add XML comments to the sample documents with hints about expected
           contents, for example types of leaf nodes, permitted number of list
           entries etc.

       --sample-xml-skeleton-defaults
           Add leaf elements with defined defaults to the output with their
           default value. Without this option, the default elements are
           omitted.

       --sample-xml-skeleton-doctype=type
           Type of the sample XML document. Supported values for type are data
           (default) and config. This option determines the document element
           of the output XML document (<data> or <config> in the NETCONF
           namespace) and also affects the contents: for config, only data
           nodes representing configuration are included.

       --sample-xml-skeleton-path=path
           Subtree of the sample XML document to generate, including all
           ancestor elements. The path is a slash ("/") separated list of data
           node names that specifies the path to a subtree to print. For
           example "/nacm/rule-list/rule/rpc-name".

TREE OUTPUT
       The tree output prints the resulting schema tree from one or more
       modules. Use pyang --tree-help to print a description on the symbols
       used by this format.

       Tree output specific options:

       --tree-help
           Print help on symbols used in the tree output and exit.

       --tree-depth depth
           Levels of the tree to print.

       --tree-path path
           Subtree to print. The path is a slash ("/") separated path to a
           subtree to print. For example "/nacm/groups". All ancestors and the
           selected subtree are printed.

       --tree-print-groupings

                     Print the top-level groupings defined in the module.
                   .RE

           --tree-line-length maxlen

                         Try to break lines so they are no longer than
                         maxlen.  This is a best effort
                         algorithm.
                       .RE

UML OUTPUT
       The uml output prints an output that can be used as input-file to
       plantuml (http://plantuml.sourceforge.net) in order to generate a UML
       diagram. Note that it requires graphviz (http://www.graphviz.org/).

       For large diagrams you may need to increase the Java heap-size by the
       -XmxSIZEm option, to java. For example: java -Xmx1024m -jar
       plantuml.jar ....

       Options for the UML output format:

       --uml-classes-only
           Generate UML with classes only, no attributes

       --uml-split-pages=layout
           Generate UML output split into pages, NxN, example 2x2. One .png
           file per page will be rendered.

       --uml-output-directory=directory
           Put the generated .png files(s) in the specified output directory.
           Default is "img/"

       --uml-title=title
           Set the title of the generated UML diagram, (default is YANG module
           name).

       --uml-header=header
           Set the header of the generated UML diagram.

       --uml-footer=footer
           Set the footer of the generated UML diagram.

       --uml-long-identifers
           Use complete YANG schema identifiers for UML class names.

       --uml-no=arglist
           This option suppresses specified arguments in the generated UML
           diagram. Valid arguments are: uses, leafref, identity, identityref,
           typedef, annotation, import, circles, stereotypes. Annotation
           suppresses YANG constructs rendered as annotations, examples module
           info, config statements for containers. Example
           --uml-no=circles,stereotypes,typedef,import

       --uml-truncate=elemlist
           Leafref attributes and augment elements can have long paths making
           the classes too wide. This option will only show the tail of the
           path. Example --uml-truncate=augment,leafref.

       --uml-inline-groupings
           Render the diagram with groupings inlined.

       --uml-inline-augments
           Render the diagram with augments inlined.

       --uml-max-enums=number
           Maximum of enum items rendered.

       --uml-filter-file=file
           NOT IMPLEMENTED: Only paths in the filter file will be included in
           the diagram. A default filter file is generated by option --filter.

YANG OUTPUT
       Options for the yang output format:

       --yang-canonical
           Generate all statements in the canonical order.

       --yang-remove-unused-imports
           Remove unused import statements from the output.

YIN OUTPUT
       Options for the yin output format:

       --yin-canonical
           Generate all statements in the canonical order.

       --yin-pretty-strings
           Pretty print strings, i.e. print with extra whitespace in the
           string. This is not strictly correct, since the whitespace is
           significant within the strings in XML, but the output is more
           readable.

YANG EXTENSIONS
       This section describes XPath functions that can be used in "must",
       "when", or "path" expressions in YANG modules, in addition to the core
       XPath 1.0 functions.

       pyang can be instructed to reject the usage of these functions with the
       parameter --strict.

       Function:node-setderef(node-set)

       The deref function follows the reference defined by the first node in
       document order in the argument node-set, and returns the nodes it
       refers to.

       If the first argument node is an instance-identifier, the function
       returns a node-set that contains the single node that the instance
       identifier refers to, if it exists. If no such node exists, an empty
       node-set is returned.

       If the first argument node is a leafref, the function returns a
       node-set that contains the nodes that the leafref refers to.

       If the first argument node is of any other type, an empty node-set is
       returned.

       The following example shows how a leafref can be written with and
       without the deref function:

           /* without deref */

           leaf my-ip {
             type leafref {
               path "/server/ip";
             }
           }
           leaf my-port {
             type leafref {
               path "/server[ip = current()/../my-ip]/port";
             }
           }

           /* with deref */

           leaf my-ip {
             type leafref {
               path "/server/ip";
             }
           }
           leaf my-port {
             type leafref {
               path "deref(../my-ip)/../port";
             }
           }


EXAMPLE
       The following example validates the standard YANG modules with derived
       types:

           $ pyang ietf-yang-types.yang ietf-inet-types.yang

       The following example converts the ietf-yang-types module into YIN:

           $ pyang -f yin -o ietf-yang-types.yin ietf-yang-types.yang

       The following example converts the ietf-netconf-monitoring module into
       a UML diagram:

                   $ pyang -f uml ietf-netconf-monitoring.yang > \
                   ietf-netconf-monitoring.uml
                   $ java -jar plantuml.jar ietf-netconf-monitoring.uml
                   $ open img/ietf-netconf-monitoring.png


ENVIRONMENT VARIABLES
       pyang searches for referred modules in the colon (:) separated path
       defined by the environment variable $YANG_MODPATH and in the directory
       $YANG_INSTALL/yang/modules.

       pyang searches for plugins in the colon (:) separated path defined by
       the environment variable $PYANG_PLUGINDIR.

BUGS
        1. The XPath arguments for the must and when statements are checked
           only for basic syntax errors.

AUTHORS
       Martin Björklund <mbj@tail-f.com>
       Tail-f Systems

       Ladislav Lhotka <lhotka@nic.cz>
       CZ.NIC

       Stefan Wallin <stefan@tail-f.com>
       Tail-f Systems

NOTES
        1. RFC 6241
           http://tools.ietf.org/html/rfc6241

        2. RFC 6020
           http://tools.ietf.org/html/rfc6020

        3. RFC 6110
           http://tools.ietf.org/html/rfc6110

        4. RFC 6087
           http://tools.ietf.org/html/rfc6087

        5. draft-lhotka-netmod-yang-metadata
           https://tools.ietf.org/html/draft-lhotka-netmod-yang-metadata

        6. draft-ietf-netmod-yang-json
           http://tools.ietf.org/html/draft-ietf-netmod-yang-json



pyang-1.7.1                       2016-11-02                          PYANG(1)