idnits 2.17.1 draft-ietf-netmod-yang-tree-diagrams-03.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 19, 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 22, 2018 LabN Consulting, L.L.C. 6 December 19, 2017 8 YANG Tree Diagrams 9 draft-ietf-netmod-yang-tree-diagrams-03 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 22, 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 . . . . . . . . . . . . . . . . . . . . . 11 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 68 7. Informative References . . . . . . . . . . . . . . . . . . . 11 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 printed as "-> TARGET", 273 where TARGET is either the leafref path, with prefixes removed 274 if possible. 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 The previously mentioned "pyang" command can be helpful in producing 299 such output, for example the above example was produced using: 301 pyang -f tree --tree-line-length 50 ietf-yang-library.yang 303 When a tree diagram is included as a figure in an Internet Draft or 304 RFC, "--tree-line-length 69" works well. 306 3.2. Groupings 308 If the YANG module is comprised of groupings only, then the tree 309 diagram should contain the groupings. The 'pyang' compiler can be 310 used to produce a tree diagram with groupings using the "-f tree -- 311 tree-print-groupings" command line parameters. 313 3.3. Long Diagrams 315 Tree diagrams can be split into sections to correspond to document 316 structure. As tree diagrams are intended to provide a simplified 317 view of a module, diagrams longer than a page should generally be 318 avoided. If the complete tree diagram for a module becomes too long, 319 the diagram can be split into several smaller diagrams. For example, 320 it might be possible to have one diagram with the data node and 321 another with all notifications. If the data nodes tree is too long, 322 it is also possible to split the diagram into smaller diagrams for 323 different subtrees. When long diagrams are included in a document, 324 authors should consider whether to include the long diagram in the 325 main body of the document or in an appendix. 327 An example of such a split can be found in [RFC7407], where section 328 2.4 shows the diagram for "engine configuration": 330 +--rw snmp 331 +--rw engine 332 // more parameters from the "engine" subtree here 334 Further, section 2.5 shows the diagram for "target configuration": 336 +--rw snmp 337 +--rw target* [name] 338 // more parameters from the "target" subtree here 340 The previously mentioned "pyang" command can be helpful in producing 341 such output, for example the above example was produced using: 343 pyang -f tree --tree-path /snmp/target ietf-snmp.yang 345 4. YANG Schema Mount Tree Diagrams 347 YANG Schema Mount is defined in [I-D.ietf-netmod-schema-mount] and 348 warrants some specific discussion. Schema mount is a generic 349 mechanism that allows for mounting of one or more YANG modules at a 350 specified location of another (parent) schema. The specific location 351 is referred to as a mount point, and any container or list node in a 352 schema may serve as a mount point. Mount points are identified via 353 the inclusion of the "mount-point" extension statement as a 354 substament under a container or list node. Mount point nodes are 355 thus directly identified in a module schema definition and can be 356 identified in a tree diagram as indicated above using the "mp" flag. 358 In the following example taken from [I-D.ietf-rtgwg-ni-model], 359 "vrf-root" is a container that includes the "mount-point" extension 360 statement as part of its definition: 362 module: ietf-network-instance 363 +--rw network-instances 364 +--rw network-instance* [name] 365 +--rw name string 366 +--rw enabled? boolean 367 +--rw description? string 368 +--rw (ni-type)? 369 +--rw (root-type) 370 +--:(vrf-root) 371 | +--mp vrf-root 373 4.1. Representation of Mounted Schema Trees 375 The actual modules made available under a mount point is controlled 376 by a server and is provided to clients. This information is 377 typically provided via the Schema Mount module defined in 378 [I-D.ietf-netmod-schema-mount]. The Schema Mount module supports 379 exposure of both mounted schema and "parent-references". Parent 380 references are used for XPath evaluation within mounted modules and 381 do not represent client-accessible paths; the referenced information 382 is available to clients via the parent schema. Schema mount also 383 defines an "inline" type mount point where mounted modules are 384 exposed via the YANG library module. 386 While the modules made available under a mount point are not 387 specified in YANG modules that include mount points, the document 388 defining the module will describe the intended use of the module and 389 may identify both modules that will be mounted and parent modules 390 that can be referenced by mounted modules. An example of such a 391 description can be found in [I-D.ietf-rtgwg-ni-model]. A specific 392 implementation of a module containing mount points will also support 393 a specific list of mounted and referenced modules. In describing 394 both intended use and actual implementations, it is helpful to show 395 how mounted modules would be instantiated and referenced under a 396 mount point using tree diagrams. 398 In such diagrams, the mount point should be treated much like a 399 container that uses a grouping. The flags should also be set based 400 on the "config" leaf mentioned above, and the mount related options 401 indicated above should be shown for the top level nodes in a mounted 402 or referenced module. The following example, taken from 403 [I-D.ietf-rtgwg-ni-model], represents the prior example with YANG 404 Routing and OSPF modules mounted, YANG Interface module nodes 405 accessible via a parent-reference, and "config" indicating true: 407 module: ietf-network-instance 408 +--rw network-instances 409 +--rw network-instance* [name] 410 +--rw name string 411 +--rw enabled? boolean 412 +--rw description? string 413 +--rw (ni-type)? 414 +--rw (root-type) 415 +--:(vrf-root) 416 +--mp vrf-root 417 +--ro rt:routing-state/ 418 | +--ro router-id? 419 | +--ro control-plane-protocols 420 | +--ro control-plane-protocol* [type name] 421 | +--ro ospf:ospf 422 | +--ro instance* [af] 423 | ... 424 +--rw rt:routing/ 425 | +--rw router-id? 426 | +--rw control-plane-protocols 427 | +--rw control-plane-protocol* [type name] 428 | +--rw ospf:ospf 429 | +--rw instance* [af] 430 | ... 431 +--ro if:interfaces@ 432 | ... 433 +--ro if:interfaces-state@ 434 | ... 436 It is worth highlighting that the OSPF module augments the Routing 437 module, and while it is listed in the Schema Mount module (or inline 438 YANG library) there is no special mount-related notation in the tree 439 diagram. 441 A mount point definition alone is not sufficient to identify if the 442 mounted modules are used for configuration or for non-configuration 443 data. This is determined by the "ietf-yang-schema-mount" module's 444 "config" leaf associated with the specific mount point and is 445 indicated on the top level mounted nodes. For example in the above 446 tree, when the "config" for the routing module indicates false, the 447 nodes in the "rt:routing" subtree would have different flags: 449 +--ro rt:routing/ 450 | +--ro router-id? 451 | +--ro control-plane-protocols 452 ... 454 5. IANA Considerations 456 There are no IANA requests or assignments included in this document. 458 6. Security Considerations 460 There is no security impact related to the tree diagrams defined in 461 this document. 463 7. Informative References 465 [I-D.ietf-netmod-schema-mount] 466 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 467 ietf-netmod-schema-mount-08 (work in progress), October 468 2017. 470 [I-D.ietf-rtgwg-ni-model] 471 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 472 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 473 model-05 (work in progress), December 2017. 475 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 476 Protocol (NETCONF) Access Control Model", RFC 6536, 477 DOI 10.17487/RFC6536, March 2012, . 480 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 481 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 482 . 484 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 485 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 486 December 2014, . 488 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 489 RFC 7950, DOI 10.17487/RFC7950, August 2016, 490 . 492 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 493 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 494 . 496 Authors' Addresses 498 Martin Bjorklund 499 Tail-f Systems 501 Email: mbj@tail-f.com 503 Lou Berger (editor) 504 LabN Consulting, L.L.C. 506 Email: lberger@labn.net