DragonFly On-Line Manual Pages
PYANG(1) pyang manual PYANG(1)
NAME
pyang - validate and convert YANG modules to various formats
SYNOPSIS
pyang [--canonical] [--strict] [--ietf] [--lax-xpath-checks] [--hello]
[-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.
Only the most common options are listed here. See below for a complete
list of options.
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
--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[4]. 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.
--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.
--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:
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)
--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
file...
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[3] for details.
xsd
DEPRECATED: 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
xmi
Prints a file that can be imported to ArgoUML
jstree
HTML/JavaScript tree navigator
hypertree
A hyperbolic tree navigator that can be displayed by treebolic
jsonxsl
Generates XSLT stylesheet for transforming XML instance documents
into JSON.
jtox
Generates a driver file for transforming JSON instance documents
into XML.
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.
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
NOTE: The XSD ouput plugin is deprecated. Use the dsdl plugin instead.
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-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.
--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.
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".
XMI OUTPUT
The xmi output prints an XMI file that can be imported by ArgUML
http://argouml.tigris.org/.
Drag all classes to the diagram area in ArgoUML and use the
Arrange-Layout menu.
XMI output specific option:
JSTREE OUTPUT
The jstree output prints an HTML/JavaScript based YANG browser. It
references an images folder that needs to exist in the same folder as
the generated file. This is installed as share/yang/images in the pyang
installation directory. The easiest way is to symlink to this
directory.
jstree output specific option:
--jstree-help
Print help on jstree usage and exit.
HYPERTREE OUTPUT
The hypertree output generates a hyperbolic YANG browser. The generated
xml file can be imported to treebolic. Download treebolic from
http://treebolic.sourceforge.net/en/index.html.
Color coding in the tree:
o Light green node background : config = True
o Light yellow node background : config = False
o Red node foreground : mandatory = True
o White leaf node background : index
o Orange foreground : presence container
The xml file references an images folder that needs to exist in the
same folder as the generated file. This is installed as
share/yang/images in the pyang installation directory. The easiest way
is to symlink to this directory.
pyang -f hypertree model.yang -o model.xml
Prepare a HTML file that links to the generated XMI file:
<applet code="treebolic.applet.Treebolic.class"
archive="TreebolicAppletDom.jar"
id="Treebolic" width="100%" height="100%">
<param name="doc" value="model.xml">
</applet>
hypertree output specific option:
--hypertree-help
Print help on hypertree usage and exit.
--xmi-no-assoc-names
Do not print association names. ArgoUML has no way of hiding the
association name and the diagram gets cluttered.
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-output-director=OUTPUT_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
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
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-filter-file=FILTER_FILE
NOT IMPLEMENTED: Only paths in the filter file will be included in
the diagram. A default filter file is generated by option --filter.
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-lhotka-netmod-yang-json[5]. 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 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:
o 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.
o 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.
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-lhotka-netmod-yang-json[5].
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.
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
1. The XPath arguments for the must and when statements are checked
only for basic syntax errors.
AUTHORS
Martin Bjorklund <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-json
http://tools.ietf.org/html/draft-lhotka-netmod-yang-json
pyang-1.4.1 2013-11-11 PYANG(1)