Command-line tools

This section describes two command line tools that are part of the Yangson package. A few more specialized Python scripts are available in the project repository, directory tools/python.

yangson

This tool provides a command-line interface to the essential high-level functions of the Yangson library, namely

printing an ASCII schema tree, see DataModel.ascii_tree()
printing an opaque identifier of a YANG module set, see DataModel.module_set_id().
printing a schema digest in JSON format, see DataModel.schema_digest().
validating an instance document against a data model schema or subschema, see InstanceNode.validate().
dumping and loading a YANG data model in a serialized (pickled) form that reduces data model loading time compared to repeated parsing of source YANG modules; see the Python standard library module pickle.

For example, an ASCII tree of the schema from Example 4 can be generated by executing the following command in the docs/examples/ex4 directory:

$ yangson -p .:../../../yang-modules/ietf -t yang-library-ex4.json
+--rw example-4-a:bag!
|  +--ro bar <boolean>
|  x--rw foo <uint8>
|  +--rw (opts)?
|     +--:(a)
|     |  +--rw baz? <empty>
|     +--:(example-4-b:fooref)
|        +--rw fooref? <leafref>
+--rw example-4-b:quux# <decimal64>

An overview of command-line parameters can be obtained by using the --help/-h switch:

$ yangson --help
usage: yangson [-h] [-V] [-p PATH | -P] [-i | -t | -d | -D FILE | -v INST]
               [-s {syntax,semantics,all}] [-c {config,nonconfig,all}]
               [-S SUBSCHEMA] [-n]
               INFILE

Validate JSON data against a YANG data model.

positional arguments:
  INFILE                file name with JSON-encoded YANG library [RFC 7895] or
                        pickled data model

options:
  -h, --help            show this help message and exit
  -V, --version         show the Yangson library version number and exit
  -p, --path PATH       colon-separated list of directories to search for YANG
                        modules
  -P, --pickled         interpret INFILE as pickled data model
  -i, --id              print module set id
  -t, --tree            print schema tree as ASCII art
  -d, --digest          print schema digest in JSON format
  -D, --dump FILE       dump pickled data model to FILE
  -v, --validate INST   name of file with JSON-encoded instance data
  -s, --scope {syntax,semantics,all}
                        validation scope (default: all)
  -c, --ctype {config,nonconfig,all}
                        content type of the data instance (default: all)
  -S, --subschema SUBSCHEMA
                        prefixed name of an RPC or notification subschema
  -n, --no-types        suppress type info in tree output

Consult the manual page for further details.

convert8525

This script allows for extracting one schema from NMDA-enabled YANG library data [RFC8525] (in JSON representation) and storing its parameters in the old YANG library format of [RFC7895] that can be used as input to Yangson library functions and the yangson tool.

As an example, the distribution directory docs/examples/ex3 also contains new-format YANG library data in the file rfc8525-ex3.json. It can be converted to the old format by executing the following command in that directory:

$ convert8525 --path ../../../yang-modules/ietf --datastore running rfc8525-ex3.json
{
  "ietf-yang-library:modules-state": {
    "module-set-id": "5798f6c8acd78ccb1171cb36d34fb95ca797c769",
    "module": [
      {
        "name": "example-3-a",
        "revision": "2017-08-01",
        "conformance-type": "implement",
        "namespace": "http://example.com/example-3/a",
        "submodule": [
          {
            "name": "example-3-suba",
            "revision": "2017-08-01"
          }
        ],
        "feature": [
          "fea1",
          "fea2"
        ]
      },
      {
        "name": "example-3-b",
        "revision": "2016-08-22",
        "conformance-type": "implement",
        "namespace": "http://example.com/example-3/b"
      },
      {
        "name": "ietf-inet-types",
        "revision": "2010-09-24",
        "conformance-type": "import",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types"
      },
      {
        "name": "ietf-yang-types",
        "revision": "2013-07-15",
        "conformance-type": "import",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types"
      },
      {
        "name": "ietf-inet-types",
        "revision": "2013-07-15",
        "conformance-type": "import",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types"
      }
    ]
  }
}

An overview of command-line parameters can be obtained by using the --help/-h switch:

$ convert8525 --help
usage: convert8525 [-h] [-o OUTFILE] [-p PATH] [-d DSTORE | -s SCHEMA] YLIB

Convert NMDA-compatible YANG library data to the old style of RFC 7985.

positional arguments:
  YLIB                  name of the input file containing JSON-encoded YANG
                        library data conforming to the RFC 8525 schema

options:
  -h, --help            show this help message and exit
  -o, --output OUTFILE  Direct output to OUTFILE instead of standard output
  -p, --path PATH       colon-separated list of directories to search for YANG
                        modules
  -d, --datastore DSTORE
                        name of a datastore
  -s, --schema SCHEMA   name of a schema

Consult the manual page for further details.