pyang

pyang
Prev	ConfD man-pages, Volume 1	Next

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

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

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

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

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

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

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

--check-update-from oldfile

Checks that a new revision of a module follows the update rules given in RFC 6020. 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.

Tail-f Specific Options

-a --annotate filename

filename is the name of a file containing a YANG module with tailf:annotate statements.

This parameter can be given multiple times.

--cs-feature feature

Indicates that support for feature should be present in the generated confspec file. If feature is defined in an imported YANG module, it must be given as prefix:feature-name.

If no such parameter is given, all features in the module is supported.

This parameter can be given multiple times.

--cs-no-features

Indicates that no features are supported.

--cs-ignore-unknown-features

Instructs the compiler to not give an error if an unknown feature is specified with --feature.

--cs-use-description

Normally, 'description' statements are ignored by pyang when translating to confspecs. Instead the 'tailf:info' statement is used as help and information text in the CLI and WebUI. When this option is specified, text in 'description' statements is used if no 'tailf:info' statement is present.

Tail-f Sanitation Options

--tailf-sanitize

This option removes all tailf specific statements from a module, including the import statement that imports tailf-common, if possible. This option is intended to be used together with -f yang or -f yin, in order to produce a module without any references to tailf modules.

This option is useful in order to publish YANG modules to NETCONF clients, like Tail-f's NCS.

The behavior of this option can be changed with the other options listed is this manual page.

By default, this option:

Removes all tailf extension statements. Most of these extensions are used to control the implementation on the server, or to tweak the CLI experience. These extensions are not needed in a NETCONF client.
Removes any 'must' or 'when' statement that uses a non-standard XPath function.
Removes any node marked with a 'tailf:hidden full' statement. Such a node is not visible in any agent.
Inlines the subtree that a 'tailf:symlink' points to. If any node in the target subtree contains 'when' or 'must' statements, these are removed. The reason for this is that in general, it is not possible to guarantee that the argument to such a statement will point to a node that is visible in the module.
Copies any typedefs from 'tailf-common' into the module, and changes any references to such types to reference the copied type.

--tailf-remove-body

Removes all 'container', 'list', 'leaf', 'leaf-list', 'augment', 'rpc', and 'notification' statements from the module.

This can be useful if the module is normally compiled with the --export option to confdc, and the module is not exported to NETCONF, but it still has typedefs, groupings, features, or identities that are referenced by some other module. By using this option, such a module can safely be published to a NETCONF client.

--tailf-keep-non-std-xpath

In the sanitition process, do not remove 'must' and 'when' statements with non-standard XPath functions.

If a module is prepared for NCS, this option should be used, so that NCS can make use of the 'must' and 'when' statements.

--tailf-keep-actions

In the sanitition process, do not remove 'tailf:action' statements. This is useful if the client understands this extension.

If a module is prepared for NCS, this option should be used, so that NCS can invoke actions on the server.

--tailf-keep-info

In the sanitition process, do not remove 'tailf:info' statements. This is useful if the client understands this extension.

If a module is prepared for NCS, this option should be used, so that the NCS CLI prints the given help text.

--tailf-keep-tailf-typedefs

In the sanitation process, do not copy types from 'tailf-common'. This option can be given if the 'tailf-common' module is published to the client.

If a module is prepared for NCS, this option should be used, so that the NCS uses the correct internal representation of these types.

--tailf-keep-symlink-when

In the sanitation process, do not remove 'when' statements found in the 'tailf:symlink' target subtree. Use this option only if the 'when' expressions do not escape out of the symlinked subtree.

--tailf-keep-symlink-must

In the sanitation process, do not remove 'must' statements found in the 'tailf:symlink' target subtree. Use this option only if the 'must' expressions do not escape out of the symlinked subtree.

--tailf-keep-display-when

In the sanitition process, do not remove 'tailf:display-when' statements. This is useful if the client understands this extension.

Confspec Generation

In order to compile a YANG module for usage with ConfD, the YANG (or YIN) module is converted to a functionally equivalent confspec. This confspec is then compiled by the normal ConfD toolchain. For example:

$ pyang -f cs test.yang -o test.cs
$ confdc -c test.cs
$ confdc -l -o t.fxs t.xso

REST Documentation Options

--rest-doc-db=[candidate | running]

This option defines what database to use, default is running.

--rest-doc-address=address

Address used in curl output, default is http://localhost:8080.

This option defines the output format, default is get.

delete output generic DELETE format.
delete_curl output curl DELETE format.
docbook output docbook format.
The docbook format contains delete, delete_curl, get, get_curl, patch, patch_curl, put, put_curl, post and post_curl formats for all the top containers and lists in a module.
get output generic GET format.
get_curl output curl GET format.
patch generates the generic PATCH format.
patch_curl generates the curl PATCH format.
post generates the generic POST format.
post_curl generates the curl POST format.
put generates the generic PUT format.
put_curl generates the curl PUT format.

--rest-doc-query-type=[default | shallow | deep]

GET result depth, default is default.

--rest-doc-end-list-url-with-keys

End example list path with key parameters. This is the default.

--rest-doc-end-list-url-with-no-keys

Don't end example list path with key parameters.

--rest-doc-list-keys

JSON dictionary of list keys and values.

Replaces the example leaf- and key-values in GET, PATCH, POST and PUT, with the specified values in the dictionary.

--rest-doc-path

Keypath to the yang-statment to generate output for.

--rest-doc-curl-flags

Additional curl-flags added to the --rest-doc-output *_curl commands.

OUTPUT EXAMPLES

--rest-doc-output=get

# leaf (string) /t1:test/t1:leaf-j-1/t1:s1
GET /api/running/test/leaf-j-1/s1
Accept: application/vnd.yang.data+json

--rest-doc-output=get_curl

curl -X GET \
  -u admin:admin \
  -H "Accept: application/vnd.yang.data+json" \
  http://localhost:8080/api/running/test/leaf-j-1/s1

--rest-doc-output=patch_curl

echo '
{
  "cont-j-1" : {
    "s1" : "s1 value",
    "i1" : 42,
    "ui1" : 42
  }
}
' | curl -X PATCH -d @- -u admin:admin \
      -H "Content-type: application/vnd.yang.data+json" \
      http://localhost:8080/api/running/test/cont-j-1

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.
hypertree: Hyperbolic tree navigator that can be displayed by treebolic.
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.
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.
xmi: XMI file that can be imported by ArgoUML.
xsd: DEPRECATED: W3C XML Schema.
yang: Normal YANG syntax.
yin: The XML syntax of YANG.

cs: Tail-f confspec language

Capability Output

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

Options for the capability output format:

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

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

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.

hypertree output

The hypertree output generates a hyperbolic YANG browser. The generated xml file can be imported to treebolic (http://treebolic.sourceforge.net/en/).

Color coding in the tree:

Light green node background : config = True
Light yellow node background : config = False
Red node foreground : mandatory = True
White leaf node background : index
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.

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

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.

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:

$ pyang -f omni foo.yang -o foo.scpt
$ osascript foo.scpt

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

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

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

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.

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:

XSD Output

NOTE: The XSD output 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.

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

Prev	Up	Next
maapi	Home	ConfD man-pages, Volume 3

Name

Synopsis