idnits 2.17.1 draft-ietf-netmod-yang-tree-diagrams-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 260 has weird spacing: '... rw for c...' == Line 261 has weird spacing: '... ro for n...' == Line 267 has weird spacing: '... mp for n...' -- The document date (February 8, 2018) is 2268 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-12) exists of draft-ietf-netmod-schema-mount-08 == Outdated reference: A later version (-12) exists of draft-ietf-rtgwg-ni-model-05 -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Intended status: Best Current Practice L. Berger, Ed. 5 Expires: August 12, 2018 LabN Consulting, L.L.C. 6 February 8, 2018 8 YANG Tree Diagrams 9 draft-ietf-netmod-yang-tree-diagrams-06 11 Abstract 13 This document captures the current syntax used in YANG module Tree 14 Diagrams. The purpose of this document is to provide a single 15 location for this definition. This syntax may be updated from time 16 to time based on the evolution of the YANG language. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 12, 2018. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Tree Diagram Syntax . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Submodules . . . . . . . . . . . . . . . . . . . . . . . 6 55 2.2. Groupings . . . . . . . . . . . . . . . . . . . . . . . . 6 56 2.3. yang-data . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.4. Collapsed Node Representation . . . . . . . . . . . . . . 6 58 2.5. Comments . . . . . . . . . . . . . . . . . . . . . . . . 7 59 2.6. Node Representation . . . . . . . . . . . . . . . . . . . 7 60 3. Usage Guidelines For RFCs . . . . . . . . . . . . . . . . . . 8 61 3.1. Wrapping Long Lines . . . . . . . . . . . . . . . . . . . 8 62 3.2. Groupings . . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.3. Long Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 64 4. YANG Schema Mount Tree Diagrams . . . . . . . . . . . . . . . 10 65 4.1. Representation of Mounted Schema Trees . . . . . . . . . 10 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 68 7. Informative References . . . . . . . . . . . . . . . . . . . 12 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 71 1. Introduction 73 YANG Tree Diagrams were first published in [RFC6536]. Such diagrams 74 are used to provided a simplified graphical representation of a data 75 model and can be automatically generated via tools such as "pyang". 76 (See ). This document describes 77 the syntax used in YANG Tree Diagrams. It is expected that this 78 document will be updated or replaced as changes to the YANG language, 79 see [RFC7950], necessitate. 81 Today's common practice is to include the definition of the syntax 82 used to represent a YANG module in every document that provides a 83 tree diagram. This practice has several disadvantages and the 84 purpose of this document is to provide a single location for this 85 definition. It is not the intent of this document to restrict future 86 changes, but rather to ensure such changes are easily identified and 87 suitably agreed upon. 89 An example tree diagram can be found in [RFC7223] Section 3. A 90 portion of which follows: 92 +--rw interfaces 93 | +--rw interface* [name] 94 | +--rw name string 95 | +--rw description? string 96 | +--rw type identityref 97 | +--rw enabled? boolean 98 | +--rw link-up-down-trap-enable? enumeration 100 2. Tree Diagram Syntax 102 This section describes the meaning of the symbols used in YANG Tree 103 diagrams. 105 A full tree diagram of a module represents all elements. It includes 106 the name of the module and sections for top level module statements 107 (typically containers), augmentations, rpcs and notifications all 108 identified under a module statement. Module trees may be included in 109 a document as a whole, by one or more sections, or even subsets of 110 nodes. 112 A module is identified by "module:" followed the module-name. This 113 is followed by one or more sections, in order: 115 1. The top-level data nodes defined in the module, offset by 2 116 spaces. 118 2. Augmentations, offset by 2 spaces and identified by the keyword 119 "augment" followed by the augment target node and a colon (":") 120 character. 122 3. RPCs, offset by 2 spaces and identified by "rpcs:". 124 4. Notifications, offset by 2 spaces and identified by 125 "notifications:". 127 5. Groupings, offset by 2 spaces, and identified by the keyword 128 "grouping" followed by the name of the grouping and a colon (":") 129 character. 131 6. yang-data, offset by 2 spaces, and identified by the keyword 132 "yang-data" followed by the name of the yang-data structure and a 133 colon (":") character. 135 The relative organization of each section is provided using a text- 136 based format that is typical of a file system directory tree display 137 command. Each node in the tree is prefaces with "+--". Schema nodes 138 that are children of another node are offset from the parent by 3 139 spaces. Sibling schema nodes are listed with the same space offset 140 and, when separated by lines, linked via a vertical bar ("|") 141 character. 143 The full format, including spacing conventions is: 145 module: 146 +-- 147 | +-- 148 | +-- 149 +-- 150 +-- 151 +-- 153 augment : 154 +-- 155 +-- 156 +-- 157 +-- 158 augment : 159 +-- 161 rpcs: 162 +-- 163 +-- 164 +-- 165 | +-- 166 +-- 168 notifications: 169 +-- 170 +-- 171 +-- 172 | +-- 173 +-- 175 grouping : 176 +-- 177 +-- 178 | +-- 179 +-- 180 grouping : 181 +-- 183 yang-data : 184 +-- 185 +-- 186 | +-- 187 +-- 188 yang-data : 189 +-- 191 2.1. Submodules 193 Submodules are represented in the same fashion as modules, but are 194 identified by "submodule:" followed the (sub)module-name. For 195 example: 197 submodule: 198 +-- 199 | +-- 200 | +-- 202 2.2. Groupings 204 Nodes within a used grouping are normally expanded as if the nodes 205 were defined at the location of the "uses" statement. However, it is 206 also possible to not expand the "uses" statement, but instead print 207 the name of the grouping. 209 For example, the following diagram shows the "tls-transport" grouping 210 from [RFC7407] unexpanded: 212 +--rw tls 213 +---u tls-transport 215 If the grouping is expanded, it could be printed as: 217 +--rw tls 218 +--rw port? inet:port-number 219 +--rw client-fingerprint? x509c2n:tls-fingerprint 220 +--rw server-fingerprint? x509c2n:tls-fingerprint 221 +--rw server-identity? snmp:admin-string 223 Groupings may optionally be present in the "groupings" section. 225 2.3. yang-data 227 If the module defines a "yang-data" structure [RFC8040], these 228 structures may optionally be present in the "yang-data" section. 230 2.4. Collapsed Node Representation 232 At times when the composition of the nodes within a module schema are 233 not important in the context of the presented tree, sibling nodes and 234 their children can be collapsed using the notation "..." in place of 235 the text lines used to represent the summarized nodes. For example: 237 +-- 238 | ... 239 +-- 240 +-- 241 +-- 243 2.5. Comments 245 Single line comments, starting with "//" (possibly indented) and 246 ending at the end of the line, may be used in the tree notation. 248 2.6. Node Representation 250 Each node in a YANG module is printed as: 252 -- 254 is one of: 255 + for current 256 x for deprecated 257 o for obsolete 259 is one of: 260 rw for configuration data 261 ro for non-configuration data, output parameters to rpcs 262 and actions, and notification parameters 263 -w for input parameters to rpcs and actions 264 -u for uses of a grouping 265 -x for rpcs and actions 266 -n for notifications 267 mp for nodes containing a "mount-point" extension statement 269 is the name of the node 270 () means that the node is a choice node 271 :() means that the node is a case node 273 If the node is augmented into the tree from another module, 274 its name is printed as :, where is the 275 prefix defined in the module where the node is defined. 277 is one of: 278 ? for an optional leaf, choice, anydata or anyxml 279 ! for a presence container 280 * for a leaf-list or list 281 [] for a list's keys 282 / for a top-level data node in a mounted module 283 @ for a top-level data node in a parent referenced module 285 is the name of the type for leafs and leaf-lists 287 If the type is a leafref, the type is either printed as 288 "-> TARGET", where TARGET is the leafref path, with prefixes 289 removed if possible, or printed as "leafref". 291 is the list of features this node depends on, 292 printed within curly brackets and a question mark "{...}?" 294 Arbitrary whitespace is allowed between any of the whitespace 295 separated fields (e.g., and ). Additional whitespace 296 may for example be used to column align fields (e.g., within a list 297 or container) to improve readability. 299 3. Usage Guidelines For RFCs 301 This section provides general guidelines related to the use of tree 302 diagrams in RFCs. 304 3.1. Wrapping Long Lines 306 Internet Drafts and RFCs limit the number of characters that may in a 307 line of text to 72 characters. When the tree representation of a 308 node results in line being longer than this limit the line should be 309 broken between and , or between and . 310 The new line should be indented so that it starts below with a 311 white space offset of at least two characters. For example: 313 notifications: 314 +---n yang-library-change 315 +--ro module-set-id 316 -> /modules-state/module-set-id 318 Long paths (e.g., leafref paths or augment targets) can be split and 319 printed on more than one line. For example: 321 augment /nat:nat/nat:instances/nat:instance/nat:mapping-table 322 /nat:mapping-entry: 324 The previously mentioned "pyang" command can be helpful in producing 325 such output, for example the notification diagram above was produced 326 using: 328 pyang -f tree --tree-line-length 50 ietf-yang-library.yang 330 When a tree diagram is included as a figure in an Internet Draft or 331 RFC, "--tree-line-length 69" works well. 333 3.2. Groupings 335 If the YANG module is comprised of groupings only, then the tree 336 diagram should contain the groupings. The 'pyang' compiler can be 337 used to produce a tree diagram with groupings using the "-f tree -- 338 tree-print-groupings" command line parameters. 340 3.3. Long Diagrams 342 Tree diagrams can be split into sections to correspond to document 343 structure. As tree diagrams are intended to provide a simplified 344 view of a module, diagrams longer than a page should generally be 345 avoided. If the complete tree diagram for a module becomes too long, 346 the diagram can be split into several smaller diagrams. For example, 347 it might be possible to have one diagram with the data node and 348 another with all notifications. If the data nodes tree is too long, 349 it is also possible to split the diagram into smaller diagrams for 350 different subtrees. When long diagrams are included in a document, 351 authors should consider whether to include the long diagram in the 352 main body of the document or in an appendix. 354 An example of such a split can be found in [RFC7407], where section 355 2.4 shows the diagram for "engine configuration": 357 +--rw snmp 358 +--rw engine 359 // more parameters from the "engine" subtree here 361 Further, section 2.5 shows the diagram for "target configuration": 363 +--rw snmp 364 +--rw target* [name] 365 // more parameters from the "target" subtree here 367 The previously mentioned "pyang" command can be helpful in producing 368 such output, for example the above example was produced using: 370 pyang -f tree --tree-path /snmp/target ietf-snmp.yang 372 4. YANG Schema Mount Tree Diagrams 374 YANG Schema Mount is defined in [I-D.ietf-netmod-schema-mount] and 375 warrants some specific discussion. Schema mount is a generic 376 mechanism that allows for mounting of one or more YANG modules at a 377 specified location of another (parent) schema. The specific location 378 is referred to as a mount point, and any container or list node in a 379 schema may serve as a mount point. Mount points are identified via 380 the inclusion of the "mount-point" extension statement as a 381 substatement under a container or list node. Mount point nodes are 382 thus directly identified in a module schema definition and can be 383 identified in a tree diagram as indicated above using the "mp" flag. 385 In the following example taken from [I-D.ietf-rtgwg-ni-model], 386 "vrf-root" is a container that includes the "mount-point" extension 387 statement as part of its definition: 389 module: ietf-network-instance 390 +--rw network-instances 391 +--rw network-instance* [name] 392 +--rw name string 393 +--rw enabled? boolean 394 +--rw description? string 395 +--rw (ni-type)? 396 +--rw (root-type) 397 +--:(vrf-root) 398 | +--mp vrf-root 400 4.1. Representation of Mounted Schema Trees 402 The actual modules made available under a mount point is controlled 403 by a server and is provided to clients. This information is 404 typically provided via the Schema Mount module defined in 405 [I-D.ietf-netmod-schema-mount]. The Schema Mount module supports 406 exposure of both mounted schema and "parent-references". Parent 407 references are used for XPath evaluation within mounted modules and 408 do not represent client-accessible paths; the referenced information 409 is available to clients via the parent schema. Schema mount also 410 defines an "inline" type mount point where mounted modules are 411 exposed via the YANG library module. 413 While the modules made available under a mount point are not 414 specified in YANG modules that include mount points, the document 415 defining the module will describe the intended use of the module and 416 may identify both modules that will be mounted and parent modules 417 that can be referenced by mounted modules. An example of such a 418 description can be found in [I-D.ietf-rtgwg-ni-model]. A specific 419 implementation of a module containing mount points will also support 420 a specific list of mounted and referenced modules. In describing 421 both intended use and actual implementations, it is helpful to show 422 how mounted modules would be instantiated and referenced under a 423 mount point using tree diagrams. 425 In such diagrams, the mount point should be treated much like a 426 container that uses a grouping. The flags should also be set based 427 on the "config" leaf mentioned above, and the mount related options 428 indicated above should be shown for the top level nodes in a mounted 429 or referenced module. The following example, taken from 430 [I-D.ietf-rtgwg-ni-model], represents the prior example with YANG 431 Routing and OSPF modules mounted, YANG Interface module nodes 432 accessible via a parent-reference, and "config" indicating true: 434 module: ietf-network-instance 435 +--rw network-instances 436 +--rw network-instance* [name] 437 +--rw name string 438 +--rw enabled? boolean 439 +--rw description? string 440 +--rw (ni-type)? 441 +--rw (root-type) 442 +--:(vrf-root) 443 +--mp vrf-root 444 +--ro rt:routing-state/ 445 | +--ro router-id? 446 | +--ro control-plane-protocols 447 | +--ro control-plane-protocol* [type name] 448 | +--ro ospf:ospf 449 | +--ro instance* [af] 450 | ... 451 +--rw rt:routing/ 452 | +--rw router-id? 453 | +--rw control-plane-protocols 454 | +--rw control-plane-protocol* [type name] 455 | +--rw ospf:ospf 456 | +--rw instance* [af] 457 | ... 458 +--ro if:interfaces@ 459 | ... 460 +--ro if:interfaces-state@ 461 | ... 463 It is worth highlighting that the OSPF module augments the Routing 464 module, and while it is listed in the Schema Mount module (or inline 465 YANG library) there is no special mount-related notation in the tree 466 diagram. 468 A mount point definition alone is not sufficient to identify if the 469 mounted modules are used for configuration or for non-configuration 470 data. This is determined by the "ietf-yang-schema-mount" module's 471 "config" leaf associated with the specific mount point and is 472 indicated on the top level mounted nodes. For example in the above 473 tree, when the "config" for the routing module indicates false, the 474 nodes in the "rt:routing" subtree would have different flags: 476 +--ro rt:routing/ 477 | +--ro router-id? 478 | +--ro control-plane-protocols 479 ... 481 5. IANA Considerations 483 There are no IANA requests or assignments included in this document. 485 6. Security Considerations 487 There is no security impact related to the tree diagrams defined in 488 this document. 490 7. Informative References 492 [I-D.ietf-netmod-schema-mount] 493 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 494 ietf-netmod-schema-mount-08 (work in progress), October 495 2017. 497 [I-D.ietf-rtgwg-ni-model] 498 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 499 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 500 model-05 (work in progress), December 2017. 502 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 503 Protocol (NETCONF) Access Control Model", RFC 6536, 504 DOI 10.17487/RFC6536, March 2012, . 507 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 508 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 509 . 511 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 512 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 513 December 2014, . 515 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 516 RFC 7950, DOI 10.17487/RFC7950, August 2016, 517 . 519 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 520 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 521 . 523 Authors' Addresses 525 Martin Bjorklund 526 Tail-f Systems 528 Email: mbj@tail-f.com 530 Lou Berger (editor) 531 LabN Consulting, L.L.C. 533 Email: lberger@labn.net