summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8340.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc8340.txt')
-rw-r--r--doc/rfc/rfc8340.txt731
1 files changed, 731 insertions, 0 deletions
diff --git a/doc/rfc/rfc8340.txt b/doc/rfc/rfc8340.txt
new file mode 100644
index 0000000..cb95072
--- /dev/null
+++ b/doc/rfc/rfc8340.txt
@@ -0,0 +1,731 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Bjorklund
+Request for Comments: 8340 Tail-f Systems
+BCP: 215 L. Berger, Ed.
+Category: Best Current Practice LabN Consulting, L.L.C.
+ISSN: 2070-1721 March 2018
+
+
+ YANG Tree Diagrams
+
+Abstract
+
+ This document captures the current syntax used in YANG module tree
+ diagrams. The purpose of this 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.
+
+Status of This Memo
+
+ This memo documents 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 has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ BCPs is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ https://www.rfc-editor.org/info/rfc8340.
+
+Copyright Notice
+
+ 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) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 1]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+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. Such diagrams
+ are used to provide a simplified graphical representation of a data
+ model and can be automatically generated via tools such as "pyang"
+ [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 [RFC7950] 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; therefore,
+ the purpose of this 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 that such changes are easily identified
+ and suitably agreed upon.
+
+ An example tree diagram can be found in Section 3 of [RFC8343]; the
+ following is 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}?
+
+
+
+Bjorklund & Berger Best Current Practice [Page 2]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+2. Tree Diagram Syntax
+
+ 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 by subsets of
+ nodes.
+
+ A module is identified by "module:" followed by the module-name.
+ This is followed by one or more sections, in 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.
+
+ 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 prefaced with "+--".
+ Schema nodes that are children of another node are offset from the
+ parent by three spaces. Sibling schema nodes are listed with the
+ same space offset and, when separated by lines, are linked via a
+ vertical bar ("|") character.
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 3]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ The full format, including spacing conventions, is:
+
+ 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>
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 4]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+2.1. Submodules
+
+ Submodules are represented in the same fashion as modules but are
+ identified by "submodule:" followed by the (sub)module-name. For
+ example:
+
+ submodule: <module-name>
+ +--<node>
+ | +--<node>
+ | +--<node>
+
+2.2. Groupings
+
+ 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 to instead print
+ the name of the grouping.
+
+ For example, the following diagram shows the "tls-transport" grouping
+ from [RFC7407] unexpanded:
+
+ +--rw tls
+ +---u tls-transport
+
+ If the grouping is expanded, it could be printed as:
+
+ +--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], these
+ structures may optionally be present in the "yang-data" section.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 5]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+2.4. Collapsed Node Representation
+
+ At times when the composition of the nodes within a module schema is
+ 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:
+
+ +--<node>
+ | ...
+ +--<node>
+ +--<node>
+ +--<node>
+
+2.5. Comments
+
+ Single line comments, starting with "//" (possibly indented) and
+ ending at the end of the line, may be used in the tree notation.
+
+2.6. Node Representation
+
+ Each node in a YANG module is printed as:
+
+ <status>--<flags> <name><opts> <type> <if-features>
+
+ <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>.
+
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 6]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ <name> is the name of the node
+ (<name>) means that the node is a choice node
+ :(<name>) means that the node is a case node
+
+ If the node is 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 is 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 (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.
+
+3. Usage Guidelines for RFCs
+
+ This section provides general guidelines related to the use of tree
+ diagrams in RFCs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 7]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+3.1. Wrapping Long Lines
+
+ Internet-Drafts and RFCs limit the number of characters that may
+ appear in a line of text to 72 characters. When the tree
+ representation of a node results in a 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 whitespace offset of at least two
+ characters. For example:
+
+ notifications:
+ +---n yang-library-change
+ +--ro module-set-id
+ -> /modules-state/module-set-id
+
+ Long paths (e.g., leafref paths or augment targets) can be split and
+ printed on more than one line. For example:
+
+ augment /nat:nat/nat:instances/nat:instance/nat:mapping-table
+ /nat:mapping-entry:
+
+ The previously mentioned "pyang" command can be helpful in producing
+ such output; for example, the notification diagram above was produced
+ using:
+
+ pyang -f tree --tree-line-length 50 ietf-yang-library.yang
+
+ When a tree diagram is included as a figure in an Internet-Draft or
+ RFC, "--tree-line-length 69" works well.
+
+3.2. Groupings
+
+ 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.
+
+3.3. Long Diagrams
+
+ 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
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 8]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ 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 [RFC7407], where
+ Section 2.4 of that document shows the diagram for "engine
+ configuration":
+
+ +--rw snmp
+ +--rw engine
+ // more parameters from the "engine" subtree here
+
+ Further, Section 2.5 of [RFC7407] shows the diagram for "target
+ configuration":
+
+ +--rw snmp
+ +--rw target* [name]
+ // more parameters from the "target" subtree here
+
+ The previously mentioned "pyang" command can be helpful in producing
+ such output; for example, the above example was produced using:
+
+ 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 warrants some
+ specific discussion. Schema mount is a generic mechanism that allows
+ for the 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 9]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ In the following example taken from [YANG-NIs], "vrf-root" is a
+ container that includes the "mount-point" extension statement as part
+ of its definition:
+
+ 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
+
+ The actual modules made available under a mount point are controlled
+ by a server and are provided to clients. This information is
+ typically provided via the schema mount module
+ ("ietf-yang-schema-mount") defined in [SCHEMA-MOUNT]. The schema
+ mount module supports the exposure of both mounted schema and
+ "parent-references". Parent references are used for XML Path
+ Language (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 of mount point, where mounted modules are
+ exposed via the YANG library module.
+
+ Although 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 [YANG-NIs]. 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 [YANG-NIs],
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 10]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ represents the prior example with the YANG modules "ietf-routing"
+ [YANG-Routing] and "ietf-ospf" [OSPF-YANG] mounted, nodes from the
+ YANG module "ietf-interfaces" [RFC8343] accessible via a
+ parent-reference, and "config" indicating "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 is worth highlighting that the "ietf-ospf" module augments the
+ "ietf-routing" module, and although 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 whether
+ the mounted modules are used for configuration data 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.
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 11]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ For example, in the above tree, when the "config" leaf for the
+ "ietf-routing" module indicates "false", the nodes in the
+ "rt:routing" subtree would have 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.
+
+7. Informative References
+
+ [OSPF-YANG]
+ Yeung, D., Qu, Y., Zhang, J., Chen, I., and A. Lindem,
+ "Yang Data Model for OSPF Protocol", Work in Progress,
+ draft-ietf-ospf-yang-10, March 2018.
+
+ [PYANG] "pyang", February 2018,
+ <https://github.com/mbj4668/pyang>.
+
+ [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
+ SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
+ December 2014, <https://www.rfc-editor.org/info/rfc7407>.
+
+ [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+ RFC 7950, DOI 10.17487/RFC7950, August 2016,
+ <https://www.rfc-editor.org/info/rfc7950>.
+
+ [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
+ Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
+ <https://www.rfc-editor.org/info/rfc8040>.
+
+ [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
+ Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
+ <https://www.rfc-editor.org/info/rfc8343>.
+
+ [SCHEMA-MOUNT]
+ Bjorklund, M. and L. Lhotka, "YANG Schema Mount", Work in
+ Progress, draft-ietf-netmod-schema-mount-08, October 2017.
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 12]
+
+RFC 8340 YANG Tree Diagrams March 2018
+
+
+ [YANG-NIs] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
+ Liu, "YANG Model for Network Instances", Work in
+ Progress, draft-ietf-rtgwg-ni-model-11, March 2018.
+
+ [YANG-Routing]
+ Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for
+ Routing Management (NMDA Version)", Work in Progress,
+ draft-ietf-netmod-rfc8022bis-11, January 2018.
+
+Authors' Addresses
+
+ Martin Bjorklund
+ Tail-f Systems
+
+ Email: mbj@tail-f.com
+
+
+ Lou Berger (editor)
+ LabN Consulting, L.L.C.
+
+ Email: lberger@labn.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund & Berger Best Current Practice [Page 13]
+