RFC 8340

YANG Tree Diagrams

📅 published March 2018, from ietf

RFC 8340: YANG Tree Diagrams 🦋

Request for Comments: 8340 🌸 Category: Best Current Practice (so it's BCP 215 💅) Authors: M. Bjorklund (Tail-f Systems) and L. Berger, Ed. (LabN Consulting, L.L.C.) 💖 Date: March 2018 ISSN: 2070-1721 Obsoletes / Updates: the title block doesn't list anything this one obsoletes or updates, so there's nothing extra to chase 🫶

Abstract ✨

okay so this doc captures the current syntax used in YANG module tree diagrams 🎀 the whole point is to have ONE single place for that definition instead of every doc copy-pasting it. the syntax may get updated from time to time as YANG itself evolves, so keep an eye out 👀

Status of This Memo 📜

this memo is documenting an Internet Best Current Practice 💅

this document is a product of the Internet Engineering Task Force (IETF) 🌈 it represents the consensus of the IETF community, it got public review, and it was approved for publication by the Internet Engineering Steering Group (IESG). if you want more info on BCPs, check Section 2 of RFC 7841 🧚

info about the current status of this document, any errata, and how to give feedback on it lives at https://www.rfc-editor.org/info/rfc8340 🔥

Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. 💜

this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. please actually read those, bestie, they describe your rights and restrictions for this document 🙈 also, any Code Components pulled out of this document MUST include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License ⚠️

heads up: the "MUST" in that last sentence is just my own shouting, it's not a BCP 14 keyword in the original, so don't take it as a new rule 💀

Table of Contents 🗂️

   1. Introduction ....................................................2
   2. Tree Diagram Syntax .............................................3
      2.1. Submodules .................................................5
      2.2. Groupings ..................................................5
      2.3. yang-data ..................................................5
      2.4. Collapsed Node Representation ..............................6
      2.5. Comments ...................................................6
      2.6. Node Representation ........................................6
   3. Usage Guidelines for RFCs .......................................7
      3.1. Wrapping Long Lines ........................................8
      3.2. Groupings ..................................................8
      3.3. Long Diagrams ..............................................8
   4. YANG Schema Mount Tree Diagrams .................................9
      4.1. Representation of Mounted Schema Trees ....................10
   5. IANA Considerations ............................................12
   6. Security Considerations ........................................12
   7. Informative References .........................................12
   Authors' Addresses ................................................13

1. Introduction 🌷

YANG tree diagrams were first published in RFC 6536 🎀 they give you a simplified graphical picture of a data model, and tools like "pyang" [PYANG] can generate them automatically. this doc describes the syntax used in YANG tree diagrams. it's expected to get updated or replaced whenever changes to the YANG language [RFC7950] make that necessary ✨

the usual practice has been to define the syntax for representing a YANG module inside every document that has a tree diagram 😩 that comes with several disadvantages, so this doc exists to be the single location for the definition. it's NOT meant to lock out future changes, it's more about making sure those changes are easy to spot and properly agreed on 🫶

here's an example tree diagram from Section 3 of [RFC8343], just a portion of it:

     +--rw interfaces
        +--rw interface* [name]
           +--rw name                        string
           +--rw description?                string
           +--rw type                        identityref
           +--rw enabled?                    boolean
           +--rw link-up-down-trap-enable?   enumeration {if-mib}?

2. Tree Diagram Syntax 🦋

this section explains what the symbols in YANG tree diagrams mean 💅

a full tree diagram of a module represents ALL the elements 👑 it includes the module name plus sections for top-level module statements (usually containers), augmentations, rpcs, and notifications, all identified under a module statement. module trees can go in a document as a whole, split into one or more sections, or even just subsets of nodes 🌈

a module is identified by "module:" followed by the module-name, and then comes one or more sections, in this order:

  1. the top-level data nodes defined in the module, offset by two spaces. 🌸
  2. augmentations, offset by two spaces and identified by the keyword augment followed by the augment target node and a colon (:) character. ✨
  3. RPCs, offset by two spaces and identified by rpcs:. 💖
  4. notifications, offset by two spaces and identified by notifications:. 🔔
  5. groupings, offset by two spaces and identified by the keyword grouping followed by the name of the grouping and a colon (:) character. 🧩
  6. yang-data, offset by two spaces and identified by the keyword yang-data followed by the name of the yang-data structure and a colon (:) character. 🎁

each section's layout is shown with a text format that looks a lot like the output of a file system directory tree command 📁 every node in the tree is prefixed with +--. schema nodes that are children of another node are offset from their parent by three spaces. sibling schema nodes line up with the same space offset and, when they're separated by lines, they're linked by a vertical bar (|) character 🪄

here's the full format, spacing conventions included:

     module: <module-name>
       +--<node>
       |  +--<node>
       |     +--<node>
       +--<node>
          +--<node>
             +--<node>

       augment <target-node>:
         +--<node>
            +--<node>
            +--<node>
               +--<node>
       augment <target-node>:
         +--<node>

       rpcs:
         +--<rpc-node>
         +--<rpc-node>
            +--<node>
            |  +--<node>
            +--<node>

       notifications:
         +--<notification-node>
         +--<notification-node>
            +--<node>
            |  +--<node>
            +--<node>

       grouping <grouping-name>:
         +--<node>
            +--<node>
            |  +--<node>
            +--<node>
       grouping <grouping-name>:
         +--<node>

       yang-data <yang-data-name>:
         +--<node>
            +--<node>
            |  +--<node>
            +--<node>
       yang-data <yang-data-name>:
         +--<node>

2.1. Submodules 🧁

submodules get drawn the same way as modules, except they're identified by "submodule:" followed by the (sub)module-name. for example:

     submodule: <module-name>
       +--<node>
       |  +--<node>
       |     +--<node>

2.2. Groupings 🍓

nodes inside a used grouping are normally expanded as if they were defined where the uses statement sits. BUT it's also possible to NOT expand the uses statement and just print the name of the grouping instead 🤔

for example, this diagram shows the "tls-transport" grouping from [RFC7407] unexpanded:

       +--rw tls
          +---u tls-transport

if the grouping IS expanded, it could be printed like this:

       +--rw tls
          +--rw port?                 inet:port-number
          +--rw client-fingerprint?   x509c2n:tls-fingerprint
          +--rw server-fingerprint?   x509c2n:tls-fingerprint
          +--rw server-identity?      snmp:admin-string

groupings may optionally be present in the "groupings" section 🌟

2.3. yang-data 🎀

if the module defines a "yang-data" structure [RFC8040], those structures may optionally be present in the "yang-data" section 💫

2.4. Collapsed Node Representation 🫧

sometimes the makeup of the nodes inside a module schema isn't important for the tree you're showing 🙃 in that case, sibling nodes and their children can be collapsed using the notation "..." in place of the text lines that represent the summarized nodes. like so:

       +--<node>
       |  ...
       +--<node>
          +--<node>
             +--<node>

2.5. Comments 💬

single-line comments are allowed in the tree notation. they start with "//" (possibly indented) and run to the end of the line ✨

2.6. Node Representation 🧠

each node in a YANG module gets printed like this:

     <status>--<flags> <name><opts> <type> <if-features>

the pieces work like this:

  • <status> is one of:
    • + for current
    • x for deprecated
    • o for obsolete
  • <flags> is one of:
    • rw for configuration data nodes and choice nodes
    • ro for non-configuration data nodes and choice nodes, output parameters to rpcs and actions, and notification parameters
    • -w for input parameters to rpcs and actions
    • -u for uses of a grouping
    • -x for rpcs and actions
    • -n for notifications
    • mp for nodes containing a "mount-point" extension statement
    • case nodes do NOT have any <flags> 🚫
  • <name> is the name of the node:
    • (<name>) means the node is a choice node
    • :(<name>) means the node is a case node
    • if the node gets augmented into the tree from another module, its name is printed as <prefix>:<name>, where <prefix> is the prefix defined in the module where the node is defined 🏷️
    • if the node is a case node, there's no space before the <name> 🪡
  • <opts> is one of:
    • ? for an optional leaf, choice, anydata, or anyxml
    • ! for a presence container
    • * for a leaf-list or list
    • [<keys>] for a list's keys
    • / for a top-level data node in a mounted module
    • @ for a top-level data node of a module identified in a mount point parent reference
  • <type> is the name of the type for leafs and leaf-lists 🍭
    • if the type is a leafref, the type is printed as either (1) -> TARGET, where TARGET is the leafref path, with prefixes removed if possible, or (2) leafref
  • <if-features> is the list of features this node depends on, printed within curly brackets and a question mark: {...}? 🎯

arbitrary whitespace is allowed between any of the whitespace-separated fields (for example, between <opts> and <type>) 🙌 extra whitespace can be used to "column align" fields, like within a list or container, to make things easier to read 💅

3. Usage Guidelines for RFCs 📚

this section gives general guidelines for using tree diagrams in RFCs 🌈

3.1. Wrapping Long Lines ✨

Okay bestie, so Internet-Drafts and RFCs cap lines at 72 characters 📏. When a tree diagram line runs longer than that, it should be broken between <opts> and <type>, or between <type> and <if-feature>. The new line gets indented so it starts below <name>, with at least two characters of whitespace offset 🎀. Here's how it looks:

  notifications:
    +---n yang-library-change
       +--ro module-set-id
               -> /modules-state/module-set-id

Long paths, like leafref paths or augment targets, can also be split across more than one line 🦋:

  augment /nat:nat/nat:instances/nat:instance/nat:mapping-table
            /nat:mapping-entry:

The "pyang" command can help you make this output 💖. For example, the notification diagram above came from this command:

  pyang -f tree --tree-line-length 50 ietf-yang-library.yang

If your tree diagram is going into an Internet-Draft or RFC as a figure, "--tree-line-length 69" works really well 🌸.

3.2. Groupings 🧚

If your YANG module is only groupings, then the tree diagram should contain the groupings 💜. The "pyang" compiler can make a tree diagram with groupings using the -f tree --tree-print-groupings command-line parameters ✨.

3.3. Long Diagrams 🌈

You can split tree diagrams into sections that match the document structure 📚. A tree diagram is supposed to be a simplified view of a module, so diagrams longer than a page are generally a no-go 🙈. If the whole tree for a module gets too long, split it into smaller diagrams. For instance, you could have one diagram for the data nodes and another for all the notifications. If the data node tree is still too long, you can split it into smaller diagrams for different subtrees 💅. When long diagrams go into a document, authors should think about whether to put them in the main body or in an appendix 🫶.

Here's an example of a split from [RFC7407] 👑. Section 2.4 of that document shows the diagram for "engine configuration":

    +--rw snmp
       +--rw engine
          // more parameters from the "engine" subtree here

Then Section 2.5 of [RFC7407] shows the diagram for "target configuration":

    +--rw snmp
       +--rw target* [name]
          // more parameters from the "target" subtree here

The "pyang" command can make this kind of output too 🍓. The example above came from this command:

  pyang -f tree --tree-path /snmp/target ietf-snmp.yang

4. YANG Schema Mount Tree Diagrams 🦋

"YANG schema mount" is defined in [SCHEMA-MOUNT], and it's worth a closer look 👀. Schema mount is a generic mechanism for mounting one or more YANG modules at a specified location in another (parent) schema. That specific location is called a "mount point", and any container or list node in a schema can be one 💖. You mark mount points by including the "mount-point" extension statement as a substatement under a container or list node. This means mount point nodes are identified directly in the module schema definition, and in a tree diagram you can flag them with the "mp" flag, as described above 🎀.

Here's an example from [YANG-NIs] 💅. "vrf-root" is a container, and its definition includes the "mount-point" extension statement:

  module: ietf-network-instance
    +--rw network-instances
       +--rw network-instance* [name]
          +--rw name           string
          +--rw enabled?       boolean
          +--rw description?   string
          +--rw (ni-type)?
          +--rw (root-type)
             +--:(vrf-root)
             |  +--mp vrf-root

4.1. Representation of Mounted Schema Trees 🌸

A server controls which actual modules are made available under a mount point, and it gives that info to clients 🧚. This information usually comes through the schema mount module ("ietf-yang-schema-mount") defined in [SCHEMA-MOUNT]. The schema mount module can expose both mounted schema and "parent-references" 💜. Parent references are used for XML Path Language (XPath) evaluation inside mounted modules. They're not client-accessible paths, since clients reach that info through the parent schema ✨. Schema mount also defines an "inline" type of mount point, where mounted modules are exposed through the YANG library module 🌈.

The modules made available under a mount point aren't specified in the YANG modules that include mount points 🙈. Instead, the document that defines the module describes the intended use, and it can name both the modules that will be mounted and the parent modules that mounted modules can reference. You can find an example of this in [YANG-NIs] 💅. A particular implementation of a module with mount points also supports its own specific list of mounted and referenced modules 🫶. To show both the intended use and the actual implementations, it helps to draw how mounted modules get instantiated and referenced under a mount point in tree diagrams 🦋.

In these diagrams, treat the mount point a lot 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 listed above should appear on the top-level nodes of a mounted or referenced module 💖. The following example from [YANG-NIs] shows the earlier example with the YANG modules "ietf-routing" [YANG-Routing] and "ietf-ospf" [OSPF-YANG] mounted. It also shows nodes from the YANG module "ietf-interfaces" [RFC8343] accessed through a parent-reference, with "config" set to "true" ✨:

  module: ietf-network-instance
    +--rw network-instances
       +--rw network-instance* [name]
          +--rw name           string
          +--rw enabled?       boolean
          +--rw description?   string
          +--rw (ni-type)?
          +--rw (root-type)
             +--:(vrf-root)
                +--mp vrf-root
                   +--ro rt:routing-state/
                   |  +--ro router-id?
                   |  +--ro control-plane-protocols
                   |     +--ro control-plane-protocol* [type name]
                   |        +--ro ospf:ospf
                   |           +--ro instance* [af]
                   |           ...
                   +--rw rt:routing/
                   |  +--rw router-id?
                   |  +--rw control-plane-protocols
                   |     +--rw control-plane-protocol* [type name]
                   |     +--rw ospf:ospf
                   |        +--rw instance* [af]
                   |           ...
                   +--ro if:interfaces@
                   |  ...
                   +--ro if:interfaces-state@
                   |  ...

It's worth noting that the "ietf-ospf" module augments the "ietf-routing" module 🔥. Even though it's listed in the schema mount module (or the inline YANG library), there's no special mount-related notation for it in the tree diagram 🙈.

A mount point definition on its own doesn't tell you whether the mounted modules hold configuration data or non-configuration data 👀. That's determined by the "config" leaf in the "ietf-yang-schema-mount" module that goes with the specific mount point, and it shows up on the top-level mounted nodes 🎀.

For example, in the tree above, if the "config" leaf for the "ietf-routing" module says "false", the nodes in the "rt:routing" subtree get different flags 💅:

                   +--ro rt:routing/
                   |  +--ro router-id?
                   |  +--ro control-plane-protocols
                      ...

5. IANA Considerations 🌈

This document has no IANA actions 💜.

6. Security Considerations 🚨

There is no security impact related to the tree diagrams defined in this document 🔒. Honestly, this one's a quiet little chapter, but we still take it seriously 💅.

7. Informative References 📚

Authors' Addresses 🫶

Martin Bjorklund Tail-f Systems

Email: mbj@tail-f.com

Lou Berger (editor) LabN Consulting, L.L.C.

Email: lberger@labn.net

📦 where this page comes from