idnits 2.17.1 draft-ietf-netmod-yang-tree-diagrams-04.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 248 has weird spacing: '... rw for c...' == Line 249 has weird spacing: '... ro for n...' == Line 253 has weird spacing: '... mp for n...' -- The document date (December 21, 2017) is 2318 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: June 24, 2018 LabN Consulting, L.L.C. 6 December 21, 2017 8 YANG Tree Diagrams 9 draft-ietf-netmod-yang-tree-diagrams-04 11 Abstract 13 This document captures the current syntax used in YANG module Tree 14 Diagrams. The purpose of the 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 June 24, 2018. 35 Copyright Notice 37 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.2. Groupings . . . . . . . . . . . . . . . . . . . . . . . . 6 56 2.3. yang-data . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.4. Collapsed Node Representation . . . . . . . . . . . . . . 6 58 2.5. Comments . . . . . . . . . . . . . . . . . . . . . . . . 6 59 2.6. Node Representation . . . . . . . . . . . . . . . . . . . 6 60 3. Usage Guidelines For RFCs . . . . . . . . . . . . . . . . . . 7 61 3.1. Wrapping Long Lines . . . . . . . . . . . . . . . . . . . 7 62 3.2. Groupings . . . . . . . . . . . . . . . . . . . . . . . . 8 63 3.3. Long Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 64 4. YANG Schema Mount Tree Diagrams . . . . . . . . . . . . . . . 9 65 4.1. Representation of Mounted Schema Trees . . . . . . . . . 9 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 68 7. Informative References . . . . . . . . . . . . . . . . . . . 12 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 YANG Tree Diagrams were first published in [RFC6536]. Such diagrams 74 are commonly used to provided a simplified graphical representation 75 of a data model and can be automatically generated via tools such as 76 "pyang". (See ). This document 77 provides the syntax used in YANG Tree Diagrams. It is expected that 78 this document will be updated or replaced as changes to the YANG 79 language, see [RFC7950], necessitate. 81 Today's common practice is include the definition of the syntax used 82 to represent a YANG module in every document that provides a tree 83 diagram. This practice has several disadvantages and the purpose of 84 the document is to provide a single location for this definition. It 85 is not the intent of this document to restrict future changes, but 86 rather to ensure such changes are easily identified and suitably 87 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 provides 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 4 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: 147 +-- 148 | +-- 149 | +-- 150 +-- 151 +-- 152 +-- 154 augment : 155 +-- 156 +-- 157 +-- 158 +-- 159 augment : 160 +-- 162 rpcs: 163 +-- 164 +-- 165 +-- 166 | +-- 167 +-- 169 notifications: 170 +-- 171 +-- 172 +-- 173 | +-- 174 +-- 176 grouping : 177 +-- 178 +-- 179 | +-- 180 +-- 181 grouping : 182 +-- 184 yang-data : 185 +-- 186 +-- 187 | +-- 188 +-- 189 yang-data : 190 +-- 192 2.1. Submodules 194 Submodules are represented in the same fashion as modules, but are 195 identified by "submodule:" followed the (sub)module-name. For 196 example: 198 submodule: 199 +-- 200 | +-- 201 | +-- 203 2.2. Groupings 205 Nodes within a used grouping are normally expanded as if the nodes 206 were defined at the location of the "uses" statement. However, it is 207 also possible to not expand the "uses" statement, but instead print 208 the name of the grouping. 210 Groupings may optionally be present in the "groupings" section. 212 2.3. yang-data 214 If the module defines a "yang-data" structure [RFC8040], these 215 structures may optionally be present in the "yang-data" section. 217 2.4. Collapsed Node Representation 219 At times when the composition of the nodes within a module schema are 220 not important in the context of the presented tree, sibling nodes and 221 their children can be collapsed using the notation "..." in place of 222 the text lines used to represent the summarized nodes. For example: 224 +-- 225 | ... 226 +-- 227 +-- 228 +-- 230 2.5. Comments 232 Single line comments, starting with "//" and ending at the end of the 233 line, may be used in the tree notation. 235 2.6. Node Representation 237 Each node in a YANG module is printed as: 239 241 is one of: 243 + for current 244 x for deprecated 245 o for obsolete 247 is one of: 248 rw for configuration data 249 ro for non-configuration data 250 -u for uses of a grouping 251 -x for rpcs and actions 252 -n for notifications 253 mp for nodes containing a "mount-point" extension statment 255 is the name of the node 256 () means that the node is a choice node 257 :() means that the node is a case node 259 If the node is augmented into the tree from another module, 260 its name is printed as :. 262 is one of: 263 ? for an optional leaf, choice, anydata or anyxml 264 ! for a presence container 265 * for a leaf-list or list 266 [] for a list's keys 267 / for a top-level data node in a mounted module 268 @ for a top-level data node in a parent referenced module 270 is the name of the type for leafs and leaf-lists 272 If the type is a leafref, the type is either printed as 273 "-> TARGET", where TARGET is the leafref path, with prefixes 274 removed if possible, or printed as "leafref". 276 is the list of features this node depends on, 277 printed within curly brackets and a question mark "{...}?" 279 3. Usage Guidelines For RFCs 281 This section provides general guidelines related to the use of tree 282 diagrams in RFCs. 284 3.1. Wrapping Long Lines 286 Internet Drafts and RFCs limit the number of characters that may in a 287 line of text to 72 characters. When the tree representation of a 288 node results in line being longer than this limit the line should be 289 broken between and . The type should be indented so 290 that the new line starts below with a white space offset of at 291 least two characters. For example: 293 notifications: 294 +---n yang-library-change 295 +--ro module-set-id 296 -> /modules-state/module-set-id 298 Long paths (e.g., leafref paths or augment targets) can be split and 299 printed on more than one line. For example: 301 augment /nat:nat/nat:instances/nat:instance/nat:mapping-table 302 /nat:mapping-entry: 304 The previously mentioned "pyang" command can be helpful in producing 305 such output, for example the notification diagram above was produced 306 using: 308 pyang -f tree --tree-line-length 50 ietf-yang-library.yang 310 When a tree diagram is included as a figure in an Internet Draft or 311 RFC, "--tree-line-length 69" works well. 313 3.2. Groupings 315 If the YANG module is comprised of groupings only, then the tree 316 diagram should contain the groupings. The 'pyang' compiler can be 317 used to produce a tree diagram with groupings using the "-f tree -- 318 tree-print-groupings" command line parameters. 320 3.3. Long Diagrams 322 Tree diagrams can be split into sections to correspond to document 323 structure. As tree diagrams are intended to provide a simplified 324 view of a module, diagrams longer than a page should generally be 325 avoided. If the complete tree diagram for a module becomes too long, 326 the diagram can be split into several smaller diagrams. For example, 327 it might be possible to have one diagram with the data node and 328 another with all notifications. If the data nodes tree is too long, 329 it is also possible to split the diagram into smaller diagrams for 330 different subtrees. When long diagrams are included in a document, 331 authors should consider whether to include the long diagram in the 332 main body of the document or in an appendix. 334 An example of such a split can be found in [RFC7407], where section 335 2.4 shows the diagram for "engine configuration": 337 +--rw snmp 338 +--rw engine 339 // more parameters from the "engine" subtree here 341 Further, section 2.5 shows the diagram for "target configuration": 343 +--rw snmp 344 +--rw target* [name] 345 // more parameters from the "target" subtree here 347 The previously mentioned "pyang" command can be helpful in producing 348 such output, for example the above example was produced using: 350 pyang -f tree --tree-path /snmp/target ietf-snmp.yang 352 4. YANG Schema Mount Tree Diagrams 354 YANG Schema Mount is defined in [I-D.ietf-netmod-schema-mount] and 355 warrants some specific discussion. Schema mount is a generic 356 mechanism that allows for mounting of one or more YANG modules at a 357 specified location of another (parent) schema. The specific location 358 is referred to as a mount point, and any container or list node in a 359 schema may serve as a mount point. Mount points are identified via 360 the inclusion of the "mount-point" extension statement as a 361 substament under a container or list node. Mount point nodes are 362 thus directly identified in a module schema definition and can be 363 identified in a tree diagram as indicated above using the "mp" flag. 365 In the following example taken from [I-D.ietf-rtgwg-ni-model], 366 "vrf-root" is a container that includes the "mount-point" extension 367 statement as part of its definition: 369 module: ietf-network-instance 370 +--rw network-instances 371 +--rw network-instance* [name] 372 +--rw name string 373 +--rw enabled? boolean 374 +--rw description? string 375 +--rw (ni-type)? 376 +--rw (root-type) 377 +--:(vrf-root) 378 | +--mp vrf-root 380 4.1. Representation of Mounted Schema Trees 382 The actual modules made available under a mount point is controlled 383 by a server and is provided to clients. This information is 384 typically provided via the Schema Mount module defined in 385 [I-D.ietf-netmod-schema-mount]. The Schema Mount module supports 386 exposure of both mounted schema and "parent-references". Parent 387 references are used for XPath evaluation within mounted modules and 388 do not represent client-accessible paths; the referenced information 389 is available to clients via the parent schema. Schema mount also 390 defines an "inline" type mount point where mounted modules are 391 exposed via the YANG library module. 393 While the modules made available under a mount point are not 394 specified in YANG modules that include mount points, the document 395 defining the module will describe the intended use of the module and 396 may identify both modules that will be mounted and parent modules 397 that can be referenced by mounted modules. An example of such a 398 description can be found in [I-D.ietf-rtgwg-ni-model]. A specific 399 implementation of a module containing mount points will also support 400 a specific list of mounted and referenced modules. In describing 401 both intended use and actual implementations, it is helpful to show 402 how mounted modules would be instantiated and referenced under a 403 mount point using tree diagrams. 405 In such diagrams, the mount point should be treated much like a 406 container that uses a grouping. The flags should also be set based 407 on the "config" leaf mentioned above, and the mount related options 408 indicated above should be shown for the top level nodes in a mounted 409 or referenced module. The following example, taken from 410 [I-D.ietf-rtgwg-ni-model], represents the prior example with YANG 411 Routing and OSPF modules mounted, YANG Interface module nodes 412 accessible via a parent-reference, and "config" indicating true: 414 module: ietf-network-instance 415 +--rw network-instances 416 +--rw network-instance* [name] 417 +--rw name string 418 +--rw enabled? boolean 419 +--rw description? string 420 +--rw (ni-type)? 421 +--rw (root-type) 422 +--:(vrf-root) 423 +--mp vrf-root 424 +--ro rt:routing-state/ 425 | +--ro router-id? 426 | +--ro control-plane-protocols 427 | +--ro control-plane-protocol* [type name] 428 | +--ro ospf:ospf 429 | +--ro instance* [af] 430 | ... 431 +--rw rt:routing/ 432 | +--rw router-id? 433 | +--rw control-plane-protocols 434 | +--rw control-plane-protocol* [type name] 435 | +--rw ospf:ospf 436 | +--rw instance* [af] 437 | ... 438 +--ro if:interfaces@ 439 | ... 440 +--ro if:interfaces-state@ 441 | ... 443 It is worth highlighting that the OSPF module augments the Routing 444 module, and while it is listed in the Schema Mount module (or inline 445 YANG library) there is no special mount-related notation in the tree 446 diagram. 448 A mount point definition alone is not sufficient to identify if the 449 mounted modules are used for configuration or for non-configuration 450 data. This is determined by the "ietf-yang-schema-mount" module's 451 "config" leaf associated with the specific mount point and is 452 indicated on the top level mounted nodes. For example in the above 453 tree, when the "config" for the routing module indicates false, the 454 nodes in the "rt:routing" subtree would have different flags: 456 +--ro rt:routing/ 457 | +--ro router-id? 458 | +--ro control-plane-protocols 459 ... 461 5. IANA Considerations 463 There are no IANA requests or assignments included in this document. 465 6. Security Considerations 467 There is no security impact related to the tree diagrams defined in 468 this document. 470 7. Informative References 472 [I-D.ietf-netmod-schema-mount] 473 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 474 ietf-netmod-schema-mount-08 (work in progress), October 475 2017. 477 [I-D.ietf-rtgwg-ni-model] 478 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 479 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 480 model-05 (work in progress), December 2017. 482 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 483 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 484 10.17487/RFC6536, March 2012, . 487 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 488 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 489 . 491 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 492 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 493 December 2014, . 495 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 496 RFC 7950, DOI 10.17487/RFC7950, August 2016, 497 . 499 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 500 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 501 . 503 Authors' Addresses 505 Martin Bjorklund 506 Tail-f Systems 508 Email: mbj@tail-f.com 509 Lou Berger (editor) 510 LabN Consulting, L.L.C. 512 Email: lberger@labn.net