pyang

Description

The pyang program is used to validate YANG modules (RFC 6020). It is also used to convert YANG modules into equivalent YIN modules. From a valid module, a W3C XML Schema (XSD) or a hybrid DSDL schema (RFC 6110) 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.

--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.

--ietf

Validate the module(s) according to IETF rules as specified in RFC 6087. In addition, it checks that the module is in canonical order, and that --max-line-length is 72 so that the module fits into an RFC.

--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.

--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.

-p --path path

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

The following directories are always added to the search path:

current directory
$YANG_MODPATH
$HOME/yang/modules
$YANG_INSTALL/yang/modules OR if $YANG_INSTALL is unset <the default installation directory>/yang/modules (on Unix systems: /usr/share/yang/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:

pyang/plugins from where pyang is installed
$PYANG_PLUGINPATH

module...

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

Output Formats

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

yin: the XML syntax of YANG
yang: normal YANG syntax
dsdl: Hybrid DSDL schema (RELAX NG with annotations) which is primarily intended as an interim product used by yang2dsdl(1). See RFC 6110 for details.
xsd: W3C XML Schema
depend: Prints a Makefile dependency rule for the module
tree: tree structure of the module
uml: Prints a file that can be read by plantuml to generate UML diagrams

YANG Output

Options for the yang output format:

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

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.

DSDL Output

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.

XSD Output

Options for the xsd output format:

--xsd-no-appinfo: Do not print YANG specific appinfo.
--xsd-no-lecture: Do not print the lecture about how the XSD can be used.
--xsd-no-imports: Do not generate any xs:imports.
--xsd-no-includes: Do not generate any xs:includes.
--xsd-break-pattern: Break long patterns so that they fit into RFCs. The resulting patterns might not always be valid XSD, so use with care.

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 modulename.
--depend-extension: YANG module file name extension. Default is no extension.
--depend-no-submodules: Do not generate dependencies for included submodules.

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 option:

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

UML Output

The uml output prints an output that can be used as input-file to plantuml in order to generate a UML diagram. Download the plantuml jar-file from http://plantuml.sourceforge.net. 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=PAGES_LAYOUT: Generate UML output split into pages, NxN, example 2x2. One .png file per page will be rendered.
--uml-classes-only: Generate UML with classes only, no attributes
--uml-output-director=OUTPUT_DIRECTORY: Put the genereated .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: 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 cosntructs rendered as annotations, examples module info, config statements for containers. Example --uml-no=circles,stereotypes,typedef,import
--uml-truncate: 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-filter-file=FILTER_FILE: NOT IMPLEMENTED: Only paths in the filter file will be included in the diagram. A deault filter file is generated by option --filter.

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-set deref(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

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

Name

Synopsis