YANG Tree DiagramsTail-f Systemsmbj@tail-f.comLabN Consulting, L.L.C.lberger@labn.net
This document captures the current syntax used in YANG module Tree
Diagrams. The purpose of the document is to provide a single location
for this definition. This syntax may be updated from time to time
based on the evolution of the YANG language.
YANG Tree Diagrams were first published in . Such diagrams
are used to provided a simplified graphical representation of
a data model and can be automatically generated via tools such as
"pyang". (See <https://github.com/mbj4668/pyang>). This document
describes the syntax used in YANG Tree Diagrams. It is expected that
this document will be updated or replaced as changes to the YANG
language, see , necessitate.
Today's common practice is to include the definition of the syntax
used to represent a YANG module in every document that provides a tree
diagram. This practice has several disadvantages and the purpose of
the document is to provide a single location for this definition. It
is not the intent of this document to restrict future changes, but
rather to ensure such changes are easily identified and suitably
agreed upon.
An example tree diagram can be found in Section 3. A
portion of which follows:
This section describes the meaning of the symbols used in YANG Tree
diagrams.
A full tree diagram of a module represents all elements. It includes
the name of the module and sections for top level module statements
(typically containers), augmentations, rpcs and notifications all
identified under a module statement. Module trees may be included in a
document as a whole, by one or more sections, or even subsets of nodes.
A module is identified by "module:" followed the module-name. This is
followed by one or more sections, in order:
The top-level data nodes defined in the module, offset by 2 spaces.
Augmentations, offset by 2 spaces and identified by the keyword
"augment" followed by the augment target node and a colon (":")
character.
RPCs, offset by 2 spaces and identified by "rpcs:".
Notifications, offset by 2 spaces and identified by
"notifications:".
Groupings, offset by 2 spaces, and identified by the keyword
"grouping" followed by the name of the grouping and a colon (":")
character.
yang-data, offset by 2 spaces, and identified by the keyword
"yang‑data" followed by the name of the yang-data structure and a
colon (":") character.
The relative organization of each section is provided using a text-based
format that is typical of a file system directory tree display command.
Each node in the tree is prefaces with "+‑‑". Schema nodes that are
children of another node are offset from the parent by 3 spaces.
Sibling schema nodes are listed with the same space offset and, when
separated by lines, linked via a vertical bar ("|") character.
The full format, including spacing conventions is:
Submodules are represented in the same fashion as modules, but are
identified by "submodule:" followed the (sub)module-name. For example:
Nodes within a used grouping are normally expanded as if the nodes
were defined at the location of the "uses" statement. However, it is
also possible to not expand the "uses" statement, but instead print
the name of the grouping.
For example, the following diagram shows the "tls‑transport" grouping
from unexpanded:
If the grouping is expanded, it could be printed as:
Groupings may optionally be present in the "groupings" section.
If the module defines a "yang‑data" structure , these
structures may optionally be present in the "yang‑data" section.
At times when the composition of the nodes within a module schema are
not important in the context of the presented tree, sibling nodes and their
children can be collapsed using the notation "..." in place of the
text lines used to represent the summarized nodes. For example:
Single line comments, starting with "//" (possibly indented) and
ending at the end of the line, may be used in the tree notation.
Each node in a YANG module is printed as:
Arbitrary whitespace is allowed between any of the whitespace
separated fields (e.g., <opts> and <type>). Additional whitespace may
for example be used to column align fields (e.g., within a list or
container) to improve readability.
This section provides general guidelines related to the use of tree
diagrams in RFCs.
Internet Drafts and RFCs limit the number of characters that may in a
line of text to 72 characters. When the tree representation of a node
results in line being longer than this limit the line should be broken
between <opts> and <type>, or between <type> and <if‑feature>. The
new line should be indented so that it starts below <name> with
a white space offset of at least two characters. For example:
Long paths (e.g., leafref paths or augment targets) can be split and
printed on more than one line. For example:
The previously mentioned "pyang" command can be helpful in producing
such output, for example the notification diagram above was produced
using:
When a tree diagram is included as a figure in an Internet Draft or
RFC, "--tree-line-length 69" works well.
If the YANG module is comprised of groupings only, then the tree
diagram should contain the groupings. The 'pyang' compiler can be
used to produce a tree diagram with groupings using the
"-f tree --tree-print-groupings" command line parameters.
Tree diagrams can be split into sections to correspond to
document structure.
As tree diagrams are intended to provide a simplified view of a module,
diagrams longer than a page should generally be avoided.
If the complete tree diagram for a module becomes too long,
the diagram can be split into several smaller
diagrams. For example, it might be possible to have one diagram with
the data node and another with all notifications. If the data nodes
tree is too long, it is also possible to split the diagram into
smaller diagrams for different subtrees.
When long diagrams are included in a document, authors should consider
whether to include the long diagram in the main body of the document or
in an appendix.
An example of such a split can be found in , where section
2.4 shows the diagram for "engine configuration":
Further, section 2.5 shows the diagram for "target configuration":
The previously mentioned "pyang" command can be helpful in producing
such output, for example the above example was produced using:
YANG Schema Mount is defined in and
warrants some specific discussion. Schema mount is a generic mechanism
that allows for mounting of one or more YANG modules at a specified
location of another (parent) schema. The specific location is referred
to as a mount point, and any container or list node in a schema may
serve as a mount point. Mount points are identified via the inclusion
of the "mount‑point" extension statement as a substatement under a
container or list node. Mount point nodes are thus directly identified
in a module schema definition and can be identified in a tree diagram
as indicated above using the "mp" flag.
In the following example taken from ,
"vrf‑root" is a container that includes the "mount‑point" extension
statement as part of its definition:
The actual modules made available under a mount point is controlled by a
server and is provided to clients. This information is typically
provided via the Schema Mount module defined in
. The Schema Mount module supports
exposure of both mounted schema and "parent‑references". Parent
references are used for XPath evaluation within mounted modules and do
not represent client-accessible paths; the referenced information is
available to clients via the parent schema. Schema mount also defines
an "inline" type mount point where mounted modules are exposed via the
YANG library module.
While the modules made available under a mount point are not specified
in YANG modules that include mount points, the document defining the
module will describe the intended use of the module and may identify
both modules that will be mounted and parent modules that can be
referenced by mounted modules. An example of such a description can be
found in . A specific implementation of a
module containing mount points will also support a specific list of
mounted and referenced modules. In describing both intended use and
actual implementations, it is helpful to show how mounted modules
would be instantiated and referenced under a mount point using tree
diagrams.
In such diagrams, the mount point should be treated much like a
container that uses a grouping. The flags should also be set based on
the "config" leaf mentioned above, and the mount related options
indicated above should be shown for the top level nodes in a mounted or
referenced module. The following example, taken from
, represents the prior example with YANG
Routing and OSPF modules mounted, YANG Interface module nodes accessible
via a parent-reference, and "config" indicating true:
It is worth highlighting that the OSPF module augments the Routing
module, and while it is listed in the Schema Mount module (or inline YANG
library) there is no special mount-related notation in the tree diagram.
A mount point definition alone is not sufficient to identify if the
mounted modules are used for configuration or for non-configuration
data. This is determined by the "ietf‑yang‑schema‑mount" module's
"config" leaf associated with the specific mount point and is
indicated on the top level mounted nodes. For example in the above
tree, when the "config" for the routing module indicates false, the
nodes in the "rt:routing" subtree would have different flags:
There are no IANA requests or assignments included in this document.
There is no security impact related to the tree diagrams defined in this
document.
YANG Schema MountThis document defines a mechanism to combine YANG modules into the schema defined in other YANG modules.YANG Network InstancesThis document defines a network instance module. This module can be used to manage the virtual resource partitioning that may be present on a network device. Examples of common industry terms for virtual resource partitioning are Virtual Routing and Forwarding (VRF) instances and Virtual Switch Instances (VSIs).Network Configuration Protocol (NETCONF) Access Control ModelThe standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF protocol access for particular users to a pre-configured subset of all available NETCONF protocol operations and content. This document defines such an access control model. [STANDARDS-TRACK]A YANG Data Model for Interface ManagementThis document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data and state data (status information and counters for the collection of statistics).A YANG Data Model for SNMP ConfigurationThis document defines a collection of YANG definitions for configuring SNMP engines.The YANG 1.1 Data Modeling LanguageYANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF).RESTCONF ProtocolThis document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).