idnits 2.17.1 draft-ietf-netmod-yang-tree-diagrams-02.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 246 has weird spacing: '... rw for c...' == Line 247 has weird spacing: '... ro for n...' == Line 250 has weird spacing: '... mp for n...' -- The document date (October 25, 2017) is 2374 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (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-04 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 2 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: Standards Track L. Berger, Ed. 5 Expires: April 28, 2018 LabN Consulting, L.L.C. 6 October 25, 2017 8 YANG Tree Diagrams 9 draft-ietf-netmod-yang-tree-diagrams-02 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 April 28, 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 . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.3. yang-data . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.4. Collapsed Node Representation . . . . . . . . . . . . . . 5 58 2.5. Comments . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.6. Node Representation . . . . . . . . . . . . . . . . . . . 5 60 3. Usage Guidelines For RFCs . . . . . . . . . . . . . . . . . . 6 61 3.1. Wrapping Long Lines . . . . . . . . . . . . . . . . . . . 7 62 3.2. Long Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 63 4. YANG Schema Mount Tree Diagrams . . . . . . . . . . . . . . . 8 64 4.1. Representation of Instance Data Trees . . . . . . . . . . 8 65 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 67 7. Informative References . . . . . . . . . . . . . . . . . . . 10 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 70 1. Introduction 72 YANG Tree Diagrams were first published in [RFC7223]. Such diagrams 73 are commonly used to provided a simplified graphical representation 74 of a data model and can be automatically generated via tools such as 75 "pyang". (See ). This document 76 provides the syntax used in YANG Tree Diagrams. It is expected that 77 this document will be updated or replaced as changes to the YANG 78 language, see [RFC7950], necessitate. 80 Today's common practice is include the definition of the syntax used 81 to represent a YANG module in every document that provides a tree 82 diagram. This practice has several disadvantages and the purpose of 83 the document is to provide a single location for this definition. It 84 is not the intent of this document to restrict future changes, but 85 rather to ensure such changes are easily identified and suitably 86 agreed upon. 88 An example tree diagram can be found in [RFC7223] Section 3. A 89 portion of which follows: 91 +--rw interfaces 92 | +--rw interface* [name] 93 | +--rw name string 94 | +--rw description? string 95 | +--rw type identityref 96 | +--rw enabled? boolean 97 | +--rw link-up-down-trap-enable? enumeration 99 2. Tree Diagram Syntax 101 This section provides the meaning of the symbols used in YANG Tree 102 diagrams. 104 A full tree diagram of a module represents all elements. It includes 105 the name of the module and sections for top level module statements 106 (typically containers), augmentations, rpcs and notifications all 107 identified under a module statement. Module trees may be included in 108 a document as a whole, by one or more sections, or even subsets of 109 nodes. 111 A module is identified by "module:" followed the module-name. This 112 is followed by one or more sections, in order: 114 1. The top-level data nodes defined in the module, offset by 4 115 spaces. 117 2. Augmentations, offset by 2 spaces and identified by the keyword 118 "augment" followed by the augment target node and a colon (":") 119 character. 121 3. RPCs, offset by 2 spaces and identified by "rpcs:". 123 4. Notifications, offset by 2 spaces and identified by 124 "notifications:". 126 5. Groupings, offset by 2 spaces, and identified by the keyword 127 "grouping" followed by the name of the grouping and a colon (":") 128 character. 130 6. yang-data, offset by 2 spaces, and identified by the keyword 131 "yang-data" followed by the name of the yang-data structure and a 132 colon (":") character. 134 The relative organization of each section is provided using a text- 135 based format that is typical of a file system directory tree display 136 command. Each node in the tree is prefaces with "+--". Schema nodes 137 that are children of another node are offset from the parent by 3 138 spaces. Schema peer nodes separated are listed with the same space 139 offset and, when separated by lines, linked via a vertical bar ("|") 140 character. 142 The full format, including spacing conventions is: 144 module: 145 +-- 146 | +-- 147 | +-- 148 +-- 149 +-- 150 +-- 152 augment : 153 +-- 154 +-- 155 +-- 156 +-- 157 augment : 158 +-- 160 rpcs: 161 +-- 162 +-- 163 +-- 164 | +-- 165 +-- 167 notifications: 168 +-- 169 +-- 170 +-- 171 | +-- 172 +-- 174 grouping : 175 +-- 176 +-- 177 | +-- 178 +-- 179 grouping : 180 +-- 182 yang-data : 183 +-- 184 +-- 185 | +-- 186 +-- 187 yang-data : 188 +-- 190 2.1. Submodules 192 Submodules are represented in the same fashion as modules, but are 193 identified by "submodule:" followed the (sub)module-name. For 194 example: 196 submodule: 198 +-- 199 | +-- 200 | +-- 202 2.2. Groupings 204 Nodes within a used grouping are expanded as if the nodes were 205 defined at the location of the uses statement. 207 Groupings may optionally be present in the "groupings" section. 209 2.3. yang-data 211 If the module defines a "yang-data" structure [RFC8040], these 212 structures may optionally be present in the "yang-data" section. 214 2.4. Collapsed Node Representation 216 At times when the composition of the nodes within a module schema are 217 not important in the context of the presented tree, peer nodes and 218 their children can be collapsed using the notation "..." in place of 219 the text lines used to represent the summarized nodes. For example: 221 +-- 222 | ... 223 +-- 224 +-- 225 +-- 227 2.5. Comments 229 Single line comments, starting with "//" and ending at the end of the 230 line, may be used in the tree notation. 232 2.6. Node Representation 234 Each node in a YANG module is printed as: 236 238 is one of: 240 + for current 242 x for deprecated 243 o for obsolete 245 is one of: 246 rw for configuration data 247 ro for non-configuration data 248 -x for rpcs and actions 249 -n for notifications 250 mp for nodes containing a "mount-point" extension statment 252 is the name of the node 253 () means that the node is a choice node 254 :() means that the node is a case node 256 If the node is augmented into the tree from another module, 257 its name is printed as :. 259 is one of: 260 ? for an optional leaf, choice, anydata or anyxml 261 ! for a presence container 262 * for a leaf-list or list 263 [] for a list's keys 264 / for a top-level data node in a mounted module 265 @ for a top-level data node in a parent referenced module 267 is the name of the type for leafs and leaf-lists 269 If the type is a leafref, the type is printed as "-> TARGET", 270 where TARGET is either the leafref path, with prefixed removed 271 if possible. 273 is the list of features this node depends on, 274 printed within curly brackets and a question mark "{...}?" 276 3. Usage Guidelines For RFCs 278 This section provides general guidelines related to the use of tree 279 diagrams in RFCs. 281 3.1. Wrapping Long Lines 283 Internet Drafts and RFCs limit the number of characters that may in a 284 line of text to 72 characters. When the tree representation of a 285 node results in line being longer than this limit the line should be 286 broken between and . The type should be indented so 287 that the new line starts below with a white space offset of at 288 least two characters. For example: 290 notifications: 291 +---n yang-library-change 292 +--ro module-set-id 293 -> /modules-state/module-set-id 295 The previously mentioned "pyang" command can be helpful in producing 296 such output, for example the above example was produced using: 298 pyang -f tree --tree-line-length 50 ietf-yang-library.yang 300 When a tree diagram is included as a figure in an Internet Draft or 301 RFC, "--tree-line-length 69" works well. 303 3.2. Long Diagrams 305 As tree diagrams are intended to provide a simplified view of a 306 module, diagrams longer than a page should generally be avoided. If 307 the complete tree diagram for a module becomes too long, the diagram 308 can be split into several smaller diagrams. For example, it might be 309 possible to have one diagram with the data node and another with all 310 notifications. If the data nodes tree is too long, it is also 311 possible to split the diagram into smaller diagrams for different 312 subtrees. When long diagrams are included in a document, authors 313 should consider whether to include the long diagram in the main body 314 of the document or in an appendix. 316 An example of such a split can be found in [RFC7407], where section 317 2.4 shows the diagram for "engine configuration": 319 +--rw snmp 320 +--rw engine 321 // more parameters from the "engine" subtree here 323 Further, section 2.5 shows the diagram for "target configuration": 325 +--rw snmp 326 +--rw target* [name] 327 // more parameters from the "target" subtree here 329 The previously mentioned "pyang" command can be helpful in producing 330 such output, for example the above example was produced using: 332 pyang -f tree --tree-path /snmp/target ietf-snmp.yang 334 4. YANG Schema Mount Tree Diagrams 336 YANG Schema Mount is defined in [I-D.ietf-netmod-schema-mount] and 337 warrants some specific discussion. Schema mount is a generic 338 mechanism that allows for mounting of one or more data modules at a 339 specified location of another (parent) schema. The specific location 340 is referred to as a mount point, and any container or list node in a 341 schema may serve as a mount point. Mount points are identified via 342 the inclusion of the "mount-point" extension statement as a 343 substament under a container or list node. Mount point nodes are 344 thus directly identified in a module schema definition and can be 345 identified in a tree diagram as indicated above using the "mp" flag. 347 In the following example taken from [I-D.ietf-rtgwg-ni-model], 348 "vrf-root" is a container that includes the "mount-point" extension 349 statement as part of its definition: 351 module: ietf-network-instance 352 +--rw network-instances 353 +--rw network-instance* [name] 354 +--rw name string 355 +--rw enabled? boolean 356 +--rw description? string 357 +--rw (ni-type)? 358 +--rw (root-type) 359 +--:(vrf-root) 360 | +--mp vrf-root 362 4.1. Representation of Instance Data Trees 364 The actual modules made available under a mount point is controlled 365 by a server and is provided to clients. This information is 366 typically provided via the Schema Mount module defined in 367 [I-D.ietf-netmod-schema-mount]. The Schema Mount module supports 368 exposure of both mounted schema and "parent-references". Parent 369 references are used for XPath evaluation within mounted modules and 370 do not represent client-accessible paths; the referenced information 371 is available to clients via the parent schema. Schema mount also 372 defines an "inline" type mount point where mounted modules are 373 exposed via the YANG library module. 375 While the modules made available under a mount point are not 376 specified in YANG modules that include mount points, the document 377 defining the module will describe the intended use of the module and 378 may identify both modules that will be mounted and parent modules 379 that can be referenced by mounted modules. An example of such a 380 description can be found in [I-D.ietf-rtgwg-ni-model]. A specific 381 implementation of a module containing mount points will also support 382 a specific list of mounted and referenced modules. In describing 383 both intended use and actual implementations, it is helpful to show 384 how mounted modules would be instantiated and referenced under a 385 mount point using tree diagrams. 387 In such diagrams, the mount point should be treated much like a 388 container that uses a grouping. The flags should also be set based 389 on the "config" leaf mentioned above, and the mount realted options 390 indicated above should be shown for the top level nodes in a mounted 391 or referenced module. The following example, taken from 392 [I-D.ietf-rtgwg-ni-model], represents the prior example with YANG 393 Routing and OSPF modules mounted, YANG Interface module nodes 394 accessible via a parent-reference, and "config" indicating true: 396 module: ietf-network-instance 397 +--rw network-instances 398 +--rw network-instance* [name] 399 +--rw name string 400 +--rw enabled? boolean 401 +--rw description? string 402 +--rw (ni-type)? 403 +--rw (root-type) 404 +--:(vrf-root) 405 +--mp vrf-root 406 +--ro rt:routing-state/ 407 | +--ro router-id? 408 | +--ro control-plane-protocols 409 | +--ro control-plane-protocol* [type name] 410 | +--ro ospf:ospf 411 | +--ro instance* [af] 412 | ... 413 +--rw rt:routing/ 414 | +--rw router-id? 415 | +--rw control-plane-protocols 416 | +--rw control-plane-protocol* [type name] 417 | +--rw ospf:ospf 418 | +--rw instance* [af] 419 | ... 420 +--ro if:interfaces@ 421 | ... 422 +--ro if:interfaces-state@ 423 | ... 425 It is worth highlighting that the OSPF module augments the Routing 426 module, and while it is listed in the Schema Mount module (or inline 427 YANG library) there is no special mount-related notation in the tree 428 diagram. 430 A mount point definition alone is not sufficient to identify if the 431 mounted modules are used for configuration or for non-configuration 432 data. This is determined by the "ietf-yang-schema-mount" module's 433 "config" leaf associated with the specific mount point and is 434 indicated on the top level mounted nodes. For example in the above 435 tree, when the "config" for the routing module indicates false, the 436 only change would be to the flag on the rt:routing node: 438 +--ro rt:routing/ 440 5. IANA Considerations 442 There are no IANA requests or assignments included in this document. 444 6. Security Considerations 446 There is no security impact related to the tree diagrams defined in 447 this document. 449 7. Informative References 451 [I-D.ietf-netmod-schema-mount] 452 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 453 ietf-netmod-schema-mount-08 (work in progress), October 454 2017. 456 [I-D.ietf-rtgwg-ni-model] 457 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 458 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 459 model-04 (work in progress), September 2017. 461 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 462 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 463 . 465 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 466 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 467 December 2014, . 469 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 470 RFC 7950, DOI 10.17487/RFC7950, August 2016, 471 . 473 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 474 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 475 . 477 Authors' Addresses 479 Martin Bjorklund 480 Tail-f Systems 482 Email: mbj@tail-f.com 484 Lou Berger (editor) 485 LabN Consulting, L.L.C. 487 Email: lberger@labn.net