idnits 2.17.1 draft-ietf-netmod-rfc6087bis-12.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC6087, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 286 has weird spacing: '... rw for c...' == Line 287 has weird spacing: '... ro for n...' -- The document date (March 5, 2017) is 2603 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCXXXX' is mentioned on line 403, but not defined == Unused Reference: 'RFC5378' is defined on line 2414, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-17 -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) -- 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 (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Obsoletes: 6087 (if approved) March 5, 2017 5 Intended status: Informational 6 Expires: September 6, 2017 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-12 11 Abstract 13 This memo provides guidelines for authors and reviewers of Standards 14 Track specifications containing YANG data model modules. Applicable 15 portions may be used as a basis for reviews of other YANG data model 16 documents. Recommendations and procedures are defined, which are 17 intended to increase interoperability and usability of Network 18 Configuration Protocol (NETCONF) and RESTCONF protocol 19 implementations that utilize YANG data model modules. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 6, 2017. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 58 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 59 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 60 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 62 4. General Documentation Guidelines . . . . . . . . . . . . . . . 9 63 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9 64 4.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9 65 4.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 10 66 4.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10 67 4.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 68 4.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11 69 4.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 70 4.7. Security Considerations Section . . . . . . . . . . . . . 12 71 4.8. IANA Considerations Section . . . . . . . . . . . . . . . 13 72 4.8.1. Documents that Create a New Namespace . . . . . . . . 13 73 4.8.2. Documents that Extend an Existing Namespace . . . . . 13 74 4.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 13 75 4.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14 76 4.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 14 77 4.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 14 78 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15 79 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15 80 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17 82 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17 83 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18 84 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18 85 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19 86 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19 87 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20 88 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 21 90 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 22 91 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 22 92 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 23 93 5.8. Module Header, Meta, and Revision Statements . . . . . . . 24 94 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 25 95 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 26 96 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 27 97 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 27 98 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 28 99 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 29 100 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 30 101 5.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 31 102 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 32 103 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 33 104 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 33 105 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 35 106 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 35 107 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 36 108 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 36 109 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 37 110 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 37 111 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 37 112 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 38 113 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 38 114 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 38 115 5.19.2. Conditionally Mandatory Data Definition Statements . . 39 116 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 40 117 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 41 118 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 42 119 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43 120 5.24. Performance Considerations . . . . . . . . . . . . . . . . 47 121 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 47 122 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 48 123 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 48 124 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 48 125 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48 126 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48 127 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49 128 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 129 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 130 7.1. Security Considerations Section Template . . . . . . . . . 52 131 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 132 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55 133 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 134 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57 135 10.2. Informative References . . . . . . . . . . . . . . . . . . 57 136 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59 137 A.1. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 59 138 A.2. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 59 139 A.3. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 59 140 A.4. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 59 141 A.5. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59 142 A.6. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 60 143 A.7. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 60 144 A.8. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60 145 A.9. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 61 146 A.10. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 61 147 A.11. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61 148 A.12. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61 149 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 63 150 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 65 151 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 67 153 1. Introduction 155 The standardization of network configuration interfaces for use with 156 the Network Configuration Protocol [RFC6241] and RESTCONF 157 [I-D.ietf-netconf-restconf] requires a modular set of data models, 158 which can be reused and extended over time. 160 This document defines a set of usage guidelines for Standards Track 161 documents containing [RFC7950] data models. YANG is used to define 162 the data structures, protocol operations, and notification content 163 used within a NETCONF and/or RESTCONF server. A server that supports 164 a particular YANG module will support client NETCONF and/or RESTCONF 165 operation requests, as indicated by the specific content defined in 166 the YANG module. 168 This document is similar to the Structure of Management Information 169 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 170 and structure. However, since that document was written a decade 171 after SMIv2 modules had been in use, it was published as a 'Best 172 Current Practice' (BCP). This document is not a BCP, but rather an 173 informational reference, intended to promote consistency in documents 174 containing YANG modules. 176 Many YANG constructs are defined as optional to use, such as the 177 description statement. However, in order to maximize 178 interoperability of NETCONF and RESTCONF implementations utilizing 179 YANG data models, it is desirable to define a set of usage guidelines 180 that may require a higher level of compliance than the minimum level 181 defined in the YANG specification. 183 In addition, YANG allows constructs such as infinite length 184 identifiers and string values, or top-level mandatory nodes, that a 185 compliant server is not required to support. Only constructs that 186 all servers are required to support can be used in IETF YANG modules. 188 This document defines usage guidelines related to the NETCONF 189 operations layer and NETCONF content layer, as defined in [RFC6241], 190 and the RESTCONF methods and RESTCONF resources, as defined in 191 [I-D.ietf-netconf-restconf], 193 These guidelines are intended to be used by authors and reviewers to 194 improve the readability and interoperability of published YANG data 195 models. 197 Note that this document is not a YANG tutorial and the reader is 198 expected to know the YANG data modeling language before using this 199 document. 201 2. Terminology 203 2.1. Requirements Notation 205 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 207 document are to be interpreted as described in [RFC2119]. 209 RFC 2119 language is used here to express the views of the NETMOD 210 working group regarding content for YANG modules. YANG modules 211 complying with this document will treat the RFC 2119 terminology as 212 if it were describing best current practices. 214 2.2. NETCONF Terms 216 The following terms are defined in [RFC6241] and are not redefined 217 here: 219 o capabilities 221 o client 223 o operation 225 o server 227 2.3. YANG Terms 229 The following terms are defined in [RFC7950] and are not redefined 230 here: 232 o data node 234 o module 236 o namespace 238 o submodule 240 o version 242 o YANG 244 o YIN 246 Note that the term 'module' may be used as a generic term for a YANG 247 module or submodule. When describing properties that are specific to 248 submodules, the term 'submodule' is used instead. 250 2.4. Terms 252 The following terms are used throughout this document: 254 o published: A stable release of a module or submodule. For example 255 the "Request for Comments" described in section 2.1 of [RFC2026] 256 is considered a stable publication. 258 o unpublished: An unstable release of a module or submodule. For 259 example the "Internet-Draft" described in section 2.2 of [RFC2026] 260 is considered an unstable publication that is a work-in-progress, 261 subject to change at any time. 263 o YANG fragment: A set of YANG statements that are not intended to 264 represent a complete YANG module or submodule. These statements 265 are not intended for actual use, except to provide an example of 266 YANG statement usage. The invalid syntax "..." is sometimes used 267 to indicate that additional YANG statements would be present in a 268 real YANG module. 270 3. YANG Tree Diagrams 272 YANG tree diagrams provide a concise representation of a YANG module 273 to help readers understand the module structure. 275 The meaning of the symbols in YANG tree diagrams is as follows. Each 276 node is printed as: 278 280 is one of: 281 + for current 282 x for deprecated 283 o for obsolete 285 is one of: 286 rw for configuration data 287 ro for non-configuration data 288 -x for rpcs and actions 289 -n for notifications 291 is the name of the node 292 () means that the node is a choice node 293 :() means that the node is a case node 295 If the node is augmented into the tree from another module, 296 its name is printed as :. 298 is one of: 299 ? for an optional leaf, choice, anydata or anyxml 300 ! for a presence container 301 * for a leaf-list or list 302 [] for a list's keys 304 is the name of the type for leafs and leaf-lists 306 If the type is a leafref, the type is printed as "-> TARGET", 307 where TARGET is either the leafref path, with prefixed removed 308 if possible. 310 is the list of features this node depends on, 311 printed within curly brackets and a question mark "{...}?" 313 4. General Documentation Guidelines 315 YANG data model modules under review are likely to be contained in 316 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 317 followed. The RFC Editor provides guidelines for authors of RFCs, 318 which are first published as Internet-Drafts. These guidelines 319 should be followed and are defined in [RFC7322] and updated in 320 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 322 The following sections MUST be present in an Internet-Draft 323 containing a module: 325 o Narrative sections 327 o Definitions section 329 o Security Considerations section 331 o IANA Considerations section 333 o References section 335 There are three usage scenarios for YANG that can appear in an 336 Internet-Draft or RFC: 338 o normative module or submodule 340 o example module or submodule 342 o example YANG fragment not part of any module or submodule 344 The guidelines in this document refer mainly to a normative complete 345 module or submodule, but may be applicable to example modules and 346 YANG fragments as well. 348 4.1. Module Copyright 350 The module description statement MUST contain a reference to the 351 latest approved IETF Trust Copyright statement, which is available 352 online at: 354 http://trustee.ietf.org/license-info/ 356 4.2. Code Components 358 Each normative YANG module or submodule contained within an Internet- 359 Draft or RFC is considered to be a code component. The strings 360 "" and "" MUST be used to identify each code 361 component. 363 The "" tag SHOULD be followed by a string identifying 364 the file name specified in Section 5.2 of [RFC7950]. The following 365 example is for the '2010-01-18' revision of the 'ietf-foo' module: 367 file "ietf-foo@2016-03-20.yang" 369 module ietf-foo { 370 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 371 prefix "foo"; 372 organization "..."; 373 contact "..."; 374 description "..."; 375 revision 2016-03-20 { 376 description "Latest revision"; 377 reference "RFC XXXX"; 378 } 379 // ... more statements 380 } 382 384 4.2.1. Example Modules 386 Example modules are not code components. The 387 convention MUST NOT be used for example modules. 389 An example module SHOULD be named using the term "example", followed 390 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 392 4.3. Terminology Section 394 A terminology section MUST be present if any terms are defined in the 395 document or if any terms are imported from other documents. 397 If YANG tree diagrams are used, then a sub-section explaining the 398 YANG tree diagram syntax MUST be present, containing the following 399 text: 401 A simplified graphical representation of the data model is used in 402 this document. The meaning of the symbols in these diagrams is 403 defined in [RFCXXXX]. 405 -- RFC Editor: Replace XXXX with RFC number and remove note 407 4.4. Tree Diagrams 409 YANG tree diagrams provide a concise representation of a YANG module, 410 and SHOULD be included to help readers understand YANG module 411 structure. Tree diagrams MAY be split into sections to correspond to 412 document structure. 414 The following example shows a simple YANG tree diagram: 416 +--rw top-level-config-container 417 | +--rw config-list* [key-name] 418 | +--rw key-name string 419 | +--rw optional-parm? string 420 | +--rw mandatory-parm identityref 421 | +--ro read-only-leaf string 422 +--ro top-level-nonconfig-container 423 +--ro nonconfig-list* [name] 424 +--ro name string 425 +--ro type string 427 The 'pyang' compiler can be used to produce the tree diagram, using 428 the '-f tree' command line parameter. 430 If the YANG module is comprised of groupings only, then the tree 431 diagram SHOULD contain the groupings. The 'pyang' compiler can be 432 used to produce a tree diagram with groupings using the '-f tree 433 --tree-print-groupings" command line parameters. 435 If the YANG module contains notifications, then the tree diagram 436 SHOULD contain the notifications. If the YANG module contains RPC 437 statements, then the tree diagram SHOULD contain the RPC statements. 439 4.5. Narrative Sections 441 The narrative part MUST include an overview section that describes 442 the scope and field of application of the module(s) defined by the 443 specification and that specifies the relationship (if any) of these 444 modules to other standards, particularly to standards containing 445 other YANG modules. The narrative part SHOULD include one or more 446 sections to briefly describe the structure of the modules defined in 447 the specification. 449 If the module(s) defined by the specification imports definitions 450 from other modules (except for those defined in the [RFC7950] or 451 [RFC6991] documents), or are always implemented in conjunction with 452 other modules, then those facts MUST be noted in the overview 453 section, as MUST be noted any special interpretations of definitions 454 in other modules. 456 4.6. Definitions Section 458 This section contains the module(s) defined by the specification. 459 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 460 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 461 semantics are needed in the module. 463 A YIN syntax version of the module MAY also be present in the 464 document. There MAY also be other types of modules present in the 465 document, such as SMIv2, which are not affected by these guidelines. 467 Note that all YANG statements within a YANG module are considered 468 normative, if the module itself is considered normative, and not an 469 example module. The use of keywords defined in [RFC2119] apply to 470 YANG description statements in normative modules exactly as they 471 would in any other normative section. 473 Example YANG modules MUST NOT contain any normative text, including 474 any reserved words from [RFC2119]. 476 See Section 5 for guidelines on YANG usage. 478 4.7. Security Considerations Section 480 Each specification that defines one or more modules MUST contain a 481 section that discusses security considerations relevant to those 482 modules. 484 This section MUST be patterned after the latest approved template 485 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 486 yang-security-guidelines). Section 7.1 contains the security 487 considerations template dated 2013-05-08. Authors MUST check the WEB 488 page at the URL listed above in case there is a more recent version 489 available. 491 In particular: 493 o Writable data nodes that could be especially disruptive if abused 494 MUST be explicitly listed by name and the associated security 495 risks MUST be explained. 497 o Readable data nodes that contain especially sensitive information 498 or that raise significant privacy concerns MUST be explicitly 499 listed by name and the reasons for the sensitivity/privacy 500 concerns MUST be explained. 502 o Operations (i.e., YANG 'rpc' statements) that are potentially 503 harmful to system behavior or that raise significant privacy 504 concerns MUST be explicitly listed by name and the reasons for the 505 sensitivity/privacy concerns MUST be explained. 507 4.8. IANA Considerations Section 509 In order to comply with IESG policy as set forth in 510 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 511 is submitted to the IESG for publication MUST contain an IANA 512 Considerations section. The requirements for this section vary 513 depending on what actions are required of the IANA. If there are no 514 IANA considerations applicable to the document, then the IANA 515 Considerations section stating that there are no actions is removed 516 by the RFC Editor before publication. Refer to the guidelines in 517 [RFC5226] for more details. 519 4.8.1. Documents that Create a New Namespace 521 If an Internet-Draft defines a new namespace that is to be 522 administered by the IANA, then the document MUST include an IANA 523 Considerations section that specifies how the namespace is to be 524 administered. 526 Specifically, if any YANG module namespace statement value contained 527 in the document is not already registered with IANA, then a new YANG 528 Namespace registry entry MUST be requested from the IANA. The 529 [RFC7950] specification includes the procedure for this purpose in 530 its IANA Considerations section. 532 4.8.2. Documents that Extend an Existing Namespace 534 It is possible to extend an existing namespace using a YANG submodule 535 that belongs to an existing module already administered by IANA. In 536 this case, the document containing the main module MUST be updated to 537 use the latest revision of the submodule. 539 4.9. Reference Sections 541 For every import or include statement that appears in a module 542 contained in the specification, which identifies a module in a 543 separate document, a corresponding normative reference to that 544 document MUST appear in the Normative References section. The 545 reference MUST correspond to the specific module version actually 546 used within the specification. 548 For every normative reference statement that appears in a module 549 contained in the specification, which identifies a separate document, 550 a corresponding normative reference to that document SHOULD appear in 551 the Normative References section. The reference SHOULD correspond to 552 the specific document version actually used within the specification. 553 If the reference statement identifies an informative reference, which 554 identifies a separate document, a corresponding informative reference 555 to that document MAY appear in the Informative References section. 557 4.10. Validation Tools 559 All modules need to be validated before submission in an Internet 560 Draft. The 'pyang' YANG compiler is freely available from github: 562 https://github.com/mbj4668/pyang 564 If the 'pyang' compiler is used to validate a normative module, then 565 the "--ietf" command line option MUST be used to identify any IETF 566 guideline issues. 568 If the 'pyang' compiler is used to validate an example module, then 569 the "--ietf" command line option MAY be used to identify any IETF 570 guideline issues. 572 4.11. Module Extraction Tools 574 A version of 'rfcstrip' is available which will extract YANG modules 575 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 576 YANG module extraction is freely available: 578 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 580 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 582 can be extracted correctly. 584 4.12. Module Usage Examples 586 Each specification that defines one or more modules SHOULD contain 587 usage examples, either throughout the document or in an appendix. 588 This includes example XML instance document snippets to demonstrate 589 the intended usage of the YANG module(s). 591 5. YANG Usage Guidelines 593 Modules in IETF Standards Track specifications MUST comply with all 594 syntactic and semantic requirements of YANG [RFC7950]. The 595 guidelines in this section are intended to supplement the YANG 596 specification, which is intended to define a minimum set of 597 conformance requirements. 599 In order to promote interoperability and establish a set of practices 600 based on previous experience, the following sections establish usage 601 guidelines for specific YANG constructs. 603 Only guidelines that clarify or restrict the minimum conformance 604 requirements are included here. 606 5.1. Module Naming Conventions 608 Normative modules contained in Standards Track documents MUST be 609 named according to the guidelines in the IANA Considerations section 610 of [RFC7950]. 612 A distinctive word or acronym (e.g., protocol name or working group 613 acronym) SHOULD be used in the module name. If new definitions are 614 being defined to extend one or more existing modules, then the same 615 word or acronym should be reused, instead of creating a new one. 617 All published module names MUST be unique. For a YANG module 618 published in an RFC, this uniqueness is guaranteed by IANA. For 619 unpublished modules, the authors need to check that no other work in 620 progress is using the same module name. 622 Example modules are non-normative, and SHOULD be named with the 623 prefix "example-". 625 It is suggested that a stable prefix be selected representing the 626 entire organization. All normative YANG modules published by the 627 IETF MUST begin with the prefix "ietf-". Another standards 628 organization, such as the IEEE, might use the prefix "ieee-" for all 629 YANG modules. 631 Once a module name is published, it MUST NOT be reused, even if the 632 RFC containing the module is reclassified to 'Historic' status. A 633 module name cannot be changed in YANG, and this would be treated as a 634 a new module, not a name change. 636 5.2. Prefixes 638 All YANG definitions are scoped by the module containing the 639 definition being referenced. This allows definitions from multiple 640 modules to be used, even if the names are not unique. In the example 641 below, the identifier "foo" is used in all 3 modules: 643 module example-foo { 644 namespace "http://example.com/ns/foo"; 645 prefix f; 647 container foo; 648 } 650 module example-bar { 651 namespace "http://example.com/ns/bar"; 652 prefix b; 654 typedef foo { type uint32; } 655 } 657 module example-one { 658 namespace "http://example.com/ns/one"; 659 prefix one; 660 import example-foo { prefix f; } 661 import example-bar { prefix b; } 663 augment "/f:foo" { 664 leaf foo { type b:foo; } 665 } 666 } 668 YANG defines the following rules for prefix usage: 670 o Prefixes are never allowed for built in data types and YANG 671 keywords. 673 o A prefix MUST be used for any external statement (i.e., a 674 statement defined with the YANG "extension" statement) 676 o The proper module prefix MUST be used for all identifiers imported 677 from other modules 679 o The proper module prefix MUST be used for all identifiers included 680 from a submodule. 682 The following guidelines apply to prefix usage of the current (local) 683 module: 685 o The local module prefix SHOULD be used instead of no prefix in all 686 path expressions. 688 o The local module prefix MUST be used instead of no prefix in all 689 "default" statements for an "identityref" or "instance-identifier" 690 data type 692 o The local module prefix MAY be used for references to typedefs, 693 groupings, extensions, features, and identities defined in the 694 module. 696 Prefix values SHOULD be short, but also likely to be unique. Prefix 697 values SHOULD NOT conflict with known modules that have been 698 previously published. 700 5.3. Identifiers 702 Identifiers for all YANG identifiers in published modules MUST be 703 between 1 and 64 characters in length. These include any construct 704 specified as an 'identifier-arg-str' token in the ABNF in Section 13 705 of [RFC7950]. 707 5.3.1. Identifier Naming Conventions 709 Identifiers SHOULD follow a consistent naming pattern throughout the 710 module. Only lower-case letters, numbers, and dashes SHOULD be used 711 in identifier names. Upper-case characters and the underscore 712 character MAY be used if the identifier represents a well-known value 713 that uses these characters. 715 Identifiers SHOULD include complete words and/or well-known acronyms 716 or abbreviations. Child nodes within a container or list SHOULD NOT 717 replicate the parent identifier. YANG identifiers are hierarchical 718 and are only meant to be unique within the the set of sibling nodes 719 defined in the same module namespace. 721 It is permissible to use common identifiers such as "name" or "id" in 722 data definition statements, especially if these data nodes share a 723 common data type. 725 Identifiers SHOULD NOT carry any special semantics that identify data 726 modelling properties. Only YANG statements and YANG extension 727 statements are designed to convey machine readable data modelling 728 properties. For example, naming an object "config" or "state" does 729 not change whether it is configuration data or state data. Only 730 defined YANG statements or YANG extension statements can be used to 731 assign semantics in a machine readable format in YANG. 733 5.4. Defaults 735 In general, it is suggested that substatements containing very common 736 default values SHOULD NOT be present. The following substatements 737 are commonly used with the default value, which would make the module 738 difficult to read if used everywhere they are allowed. 740 +--------------+---------------+ 741 | Statement | Default Value | 742 +--------------+---------------+ 743 | config | true | 744 | mandatory | false | 745 | max-elements | unbounded | 746 | min-elements | 0 | 747 | ordered-by | system | 748 | status | current | 749 | yin-element | false | 750 +--------------+---------------+ 752 Statement Defaults 754 5.5. Conditional Statements 756 A module may be conceptually partitioned in several ways, using the 757 'if-feature' and/or 'when' statements. 759 Data model designers need to carefully consider all modularity 760 aspects, including the use of YANG conditional statements. 762 If a data definition is optional, depending on server support for a 763 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 764 statement SHOULD be defined to indicate that the NETCONF or RESTCONF 765 capability is supported within the data model. 767 If any notification data, or any data definition, for a non- 768 configuration data node is not mandatory, then the server may or may 769 not be required to return an instance of this data node. If any 770 conditional requirements exist for returning the data node in a 771 notification payload or retrieval request, they MUST be documented 772 somewhere. For example, a 'when' or 'if-feature' statement could 773 apply to the data node, or the conditional requirements could be 774 explained in a 'description' statement within the data node or one of 775 its ancestors (if any). 777 If any 'if-feature' statements apply to a list node, then the same 778 'if-feature' statements MUST apply to any key leaf nodes for the 779 list. There MUST NOT be any 'if-feature' statements applied to any 780 key leaf that do not also apply to the parent list node. 782 There SHOULD NOT be any 'when' statements applied to a key leaf node. 783 It is possible that a 'when' statement for an ancestor node of a key 784 leaf will have the exact node-set result as the key leaf. In such a 785 case, the 'when' statement for the key leaf is redundant and SHOULD 786 be avoided. 788 5.6. XPath Usage 790 This section describes guidelines for using the XML Path Language 791 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 793 5.6.1. XPath Evaluation Contexts 795 YANG defines 5 separate contexts for evaluation of XPath statements: 797 1) The "running" datastore: collection of all YANG configuration data 798 nodes. The document root is the conceptual container, (e.g., 799 "config" in the "edit-config" operation), which is the parent of all 800 top-level data definition statements with a "config" statement value 801 of "true". 803 2) State data + the "running" datastore: collection of all YANG data 804 nodes. The document root is the conceptual container, parent of all 805 top-level data definition statements. 807 3) Notification: an event notification document. The document root 808 is the notification element. 810 4) RPC Input: The document root is the conceptual "input" node, which 811 is the parent of all RPC input parameter definitions. 813 5) RPC Output: The document root is the conceptual "output" node, 814 which is the parent of all RPC output parameter definitions. 816 Note that these XPath contexts cannot be mixed. For example, a 817 "when" statement in a notification context cannot reference 818 configuration data. 820 notification foo { 821 leaf mtu { 822 // NOT OK because when-stmt context is this notification 823 when "/if:interfaces/if:interface[name='eth0']"; 824 type leafref { 825 // OK because path-stmt has a different context 826 path "/if:interfaces/if:interface/if:mtu"; 827 } 828 } 829 } 831 It is especially important to consider the XPath evaluation context 832 for XPath expressions defined in groupings. An XPath expression 833 defined in a grouping may not be portable, meaning it cannot be used 834 in multiple contexts and produce proper results. 836 If the XPath expressions defined in a grouping are intended for a 837 particular context, then this context SHOULD be identified in the 838 "description" statement for the grouping. 840 5.6.2. Function Library 842 The 'position' and 'last' functions SHOULD NOT be used. This applies 843 to implicit use of the 'position' function as well (e.g., 844 '//chapter[42]'). A server is only required to maintain the relative 845 XML document order of all instances of a particular user-ordered list 846 or leaf-list. The 'position' and 'last' functions MAY be used if 847 they are evaluated in a context where the context node is a user- 848 ordered 'list' or 'leaf-list'. 850 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 851 present in YANG documents so this function has no meaning. The YANG 852 compiler SHOULD return an empty string for this function. 854 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 855 Expanded names in XPath are different than YANG. A specific 856 canonical representation of a YANG expanded name does not exist. 858 The 'lang' function SHOULD NOT be used. This function does not apply 859 to YANG because there is no 'lang' attribute set with the document. 860 The YANG compiler SHOULD return 'false' for this function. 862 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 863 functions SHOULD NOT be used if the argument is a node-set. If so, 864 the function result will be determined by the document order of the 865 node-set. Since this order can be different on each server, the 866 function results can also be different. Any function call that 867 implicitly converts a node-set to a string will also have this issue. 869 The 'local-name' function SHOULD NOT be used to reference local names 870 outside of the YANG module defining the must or when expression 871 containing the 'local-name' function. Example of a local-name 872 function that should not be used: 874 /*[local-name()='foo'] 876 5.6.3. Axes 878 The 'attribute' and 'namespace' axes are not supported in YANG, and 879 MAY be empty in a NETCONF or RESTCONF server implementation. 881 The 'preceding', and 'following' axes SHOULD NOT be used. These 882 constructs rely on XML document order within a NETCONF or RESTCONF 883 server configuration database, which may not be supported 884 consistently or produce reliable results across implementations. 885 Predicate expressions based on static node properties (e.g., element 886 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 887 instead. The 'preceding' and 'following' axes MAY be used if 888 document order is not relevant to the outcome of the expression 889 (e.g., check for global uniqueness of a parameter value). 891 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 892 however they MAY be used if document order is not relevant to the 893 outcome of the expression. 895 A server is only required to maintain the relative XML document order 896 of all instances of a particular user-ordered list or leaf-list. The 897 'preceding-sibling' and 'following-sibling' axes MAY be used if they 898 are evaluated in a context where the context node is a user-ordered 899 'list' or 'leaf-list'. 901 5.6.4. Types 903 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 904 be used within numeric or boolean expressions. There are boundary 905 conditions in which the translation from the YANG 64-bit type to an 906 XPath number can cause incorrect results. Specifically, an XPath 907 'double' precision floating point number cannot represent very large 908 positive or negative 64-bit numbers because it only provides a total 909 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 910 used in numeric expressions if the value can be represented with no 911 more than 53 bits of precision. 913 Data modelers need to be careful not to confuse the YANG value space 914 and the XPath value space. The data types are not the same in both, 915 and conversion between YANG and XPath data types SHOULD be considered 916 carefully. 918 Explicit XPath data type conversions MAY be used (e.g., 'string', 919 'boolean', or 'number' functions), instead of implicit XPath data 920 type conversions. 922 XPath expressions that contain a literal value representing a YANG 923 identity SHOULD always include the declared prefix of the module 924 where the identity is defined. 926 XPath expressions for 'when' statements SHOULD NOT reference the 927 context node or any descendant nodes of the context node. They MAY 928 reference descendant nodes if the 'when' statement is contained 929 within an 'augment' statement, and the referenced nodes are not 930 defined within the 'augment' statement. 932 Example: 934 augment "/rt:active-route/rt:input/rt:destination-address" { 935 when "rt:address-family='v4ur:ipv4-unicast'" { 936 description 937 "This augment is valid only for IPv4 unicast."; 938 } 939 // nodes defined here within the augment-stmt 940 // cannot be referenced in the when-stmt 941 } 943 5.6.5. Wildcards 945 It is possible to construct XPath expressions that will evaluate 946 differently when combined with several modules within a server 947 implementation, then when evaluated within the single module. This 948 is due to augmenting nodes from other modules. 950 Wildcard expansion is done within a server against all the nodes from 951 all namespaces, so it is possible for a 'must' or 'when' expression 952 that uses the '*' operator will always evaluate to false if processed 953 within a single YANG module. In such cases, the 'description' 954 statement SHOULD clarify that augmenting objects are expected to 955 match the wildcard expansion. 957 when /foo/services/*/active { 958 description 959 "No services directly defined in this module. 960 Matches objects that have augmented the services container."; 961 } 963 5.6.6. Boolean Expressions 965 The YANG "must" and "when" statements use an XPath boolean expression 966 to define the test condition for the statement. It is important to 967 specify these expressions in a way that will not cause inadvertent 968 changes in the result if the objects referenced in the expression are 969 updated in future revisions of the module. 971 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 972 to "one" or "three": 974 leaf foo1 { 975 type enumeration { 976 enum one; 977 enum two; 978 enum three; 979 } 980 } 982 leaf foo2 { 983 // INCORRECT 984 must "/f:foo1 != 'two'"; 985 type string; 986 } 988 leaf foo2 { 989 // CORRECT 990 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 991 type string; 992 } 994 In the next revision of the module, leaf "foo1" is extended with a 995 new enum named "four": 997 leaf foo1 { 998 type enumeration { 999 enum one; 1000 enum two; 1001 enum three; 1002 enum four; 1003 } 1004 } 1006 Now the first XPath expression will allow the enum "four" to be 1007 accepted in addition to the "one" and "three" enum values. 1009 5.7. Lifecycle Management 1011 The status statement MUST be present if its value is 'deprecated' or 1012 'obsolete'. The status SHOULD NOT be changed from 'current' directly 1013 to 'obsolete'. An object SHOULD be available for at least one year 1014 with 'deprecated' status before it is changed to 'obsolete'. 1016 The module or submodule name MUST NOT be changed, once the document 1017 containing the module or submodule is published. 1019 The module namespace URI value MUST NOT be changed, once the document 1020 containing the module is published. 1022 The revision-date substatement within the import statement SHOULD be 1023 present if any groupings are used from the external module. 1025 The revision-date substatement within the include statement SHOULD be 1026 present if any groupings are used from the external submodule. 1028 If submodules are used, then the document containing the main module 1029 MUST be updated so that the main module revision date is equal or 1030 more recent than the revision date of any submodule that is (directly 1031 or indirectly) included by the main module. 1033 Definitions for future use SHOULD NOT be specified in a module. Do 1034 not specify placeholder objects like the "reserved" example below: 1036 leaf reserved { 1037 type string; 1038 description 1039 "This object has no purpose at this time, but a future 1040 revision of this module might define a purpose 1041 for this object."; 1042 } 1043 } 1045 5.8. Module Header, Meta, and Revision Statements 1047 For published modules, the namespace MUST be a globally unique URI, 1048 as defined in [RFC3986]. This value is usually assigned by the IANA. 1050 The organization statement MUST be present. If the module is 1051 contained in a document intended for IETF Standards Track status, 1052 then the organization SHOULD be the IETF working group chartered to 1053 write the document. For other standards organizations, a similar 1054 approach is also suggested. 1056 The contact statement MUST be present. If the module is contained in 1057 a document intended for Standards Track status, then the working 1058 group web and mailing information MUST be present, and the main 1059 document author or editor contact information SHOULD be present. If 1060 additional authors or editors exist, their contact information MAY be 1061 present. 1063 The description statement MUST be present. For modules published 1064 within IETF documents, the appropriate IETF Trust Copyright text MUST 1065 be present, as described in Section 4.1. 1067 If the module relies on information contained in other documents, 1068 which are not the same documents implied by the import statements 1069 present in the module, then these documents MUST be identified in the 1070 reference statement. 1072 A revision statement MUST be present for each published version of 1073 the module. The revision statement MUST have a reference 1074 substatement. It MUST identify the published document that contains 1075 the module. Modules are often extracted from their original 1076 documents, and it is useful for developers and operators to know how 1077 to find the original source document in a consistent manner. The 1078 revision statement MAY have a description substatement. 1080 It is not required to keep the full revision history of draft 1081 versions (e.g., modules contained within Internet-Drafts). That is, 1082 within a sequence of draft versions, only the most recent revision 1083 need be recorded in the module. However, whenever a new (i.e. 1084 changed) version is made available (e.g., via a new version of an 1085 Internet-Draft), the revision date of that new version MUST be 1086 updated to a date later than that of the previous version. 1088 5.9. Namespace Assignments 1090 It is RECOMMENDED that only valid YANG modules be included in 1091 documents, whether or not they are published yet. This allows: 1093 o the module to compile correctly instead of generating disruptive 1094 fatal errors. 1096 o early implementors to use the modules without picking a random 1097 value for the XML namespace. 1099 o early interoperability testing since independent implementations 1100 will use the same XML namespace value. 1102 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1103 provided for the namespace statement in a YANG module. A value 1104 SHOULD be selected that is not likely to collide with other YANG 1105 namespaces. Standard module names, prefixes, and URI strings already 1106 listed in the YANG Module Registry MUST NOT be used. 1108 A standard namespace statement value SHOULD have the following form: 1110 : 1112 The following URN prefix string SHOULD be used for published and 1113 unpublished YANG modules: 1115 urn:ietf:params:xml:ns:yang: 1117 The following example URNs would be valid namespace statement values 1118 for Standards Track modules: 1120 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1122 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1124 urn:ietf:params:xml:ns:yang:ietf-netconf 1126 Note that a different URN prefix string SHOULD be used for non- 1127 Standards-Track modules. The string SHOULD be selected according to 1128 the guidelines in [RFC7950]. 1130 The following URIs exemplify what might be used by non Standards 1131 Track modules. Note that the domain "example.com" SHOULD be used by 1132 example modules in IETF drafts. 1134 Example URIs using URLs per RFC 3986 [RFC3986]: 1136 http://example.com/ns/example-interfaces 1138 http://example.com/ns/example-system 1140 Example URIs using tags per RFC 4151 [RFC4151]: 1142 tag:example.com,2017:example-interfaces 1144 tag:example.com,2017:example-system 1146 5.10. Top-Level Data Definitions 1148 The top-level data organization SHOULD be considered carefully, in 1149 advance. Data model designers need to consider how the functionality 1150 for a given protocol or protocol family will grow over time. 1152 The separation of configuration data and operational data SHOULD be 1153 considered carefully. It is sometimes useful to define separate top- 1154 level containers for configuration and non-configuration data. For 1155 some existing top-level data nodes, configuration data was not in 1156 scope, so only one container representing operational data was 1157 created. 1159 The number of top-level data nodes within a module SHOULD be 1160 minimized. It is often useful to retrieve related information within 1161 a single subtree. If data is too distributed, is becomes difficult 1162 to retrieve all at once. 1164 The names and data organization SHOULD reflect persistent 1165 information, such as the name of a protocol. The name of the working 1166 group SHOULD NOT be used because this may change over time. 1168 A mandatory database data definition is defined as a node that a 1169 client must provide for the database to be valid. The server is not 1170 required to provide a value. 1172 Top-level database data definitions MUST NOT be mandatory. If a 1173 mandatory node appears at the top level, it will immediately cause 1174 the database to be invalid. This can occur when the server boots or 1175 when a module is loaded dynamically at runtime. 1177 5.11. Data Types 1179 Selection of an appropriate data type (i.e., built-in type, existing 1180 derived type, or new derived type) is very subjective, and therefore 1181 few requirements can be specified on that subject. 1183 Data model designers SHOULD use the most appropriate built-in data 1184 type for the particular application. 1186 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1187 'int64') SHOULD NOT be used unless negative values are allowed for 1188 the desired semantics. 1190 5.11.1. Fixed Value Extensibility 1192 If the set of values is fixed and the data type contents are 1193 controlled by a single naming authority, then an enumeration data 1194 type SHOULD be used. 1196 leaf foo { 1197 type enumeration { 1198 enum one; 1199 enum two; 1200 } 1201 } 1203 If extensibility of enumerated values is required, then the 1204 'identityref' data type SHOULD be used instead of an enumeration or 1205 other built-in type. 1207 identity foo-type { 1208 description "Base for the extensible type"; 1209 } 1211 identity one { 1212 base f:foo-type; 1213 } 1214 identity two { 1215 base f:foo-type; 1216 } 1218 leaf foo { 1219 type identityref { 1220 base f:foo-type; 1221 } 1222 } 1224 Note that any module can declare an identity with base "foo-type" 1225 that is valid for the "foo" leaf. Identityref values are considered 1226 to be qualified names. 1228 5.11.2. Patterns and Ranges 1230 For string data types, if a machine-readable pattern can be defined 1231 for the desired semantics, then one or more pattern statements SHOULD 1232 be present. A single quoted string SHOULD be used to specify the 1233 pattern, since a double-quoted string can modify the content. 1235 The following typedef from [RFC6991] demonstrates the proper use of 1236 the "pattern" statement: 1238 typedef ipv4-address-no-zone { 1239 type inet:ipv4-address { 1240 pattern '[0-9\.]*'; 1241 } 1242 ... 1243 } 1245 For string data types, if the length of the string is required to be 1246 bounded in all implementations, then a length statement MUST be 1247 present. 1249 The following typedef from [RFC6991] demonstrates the proper use of 1250 the "length" statement: 1252 typedef yang-identifier { 1253 type string { 1254 length "1..max"; 1255 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1256 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1257 } 1258 ... 1259 } 1261 For numeric data types, if the values allowed by the intended 1262 semantics are different than those allowed by the unbounded intrinsic 1263 data type (e.g., 'int32'), then a range statement SHOULD be present. 1265 The following typedef from [RFC6991] demonstrates the proper use of 1266 the "range" statement: 1268 typedef dscp { 1269 type uint8 { 1270 range "0..63"; 1271 } 1272 ... 1273 } 1275 5.11.3. Enumerations and Bits 1277 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1278 or 'bit' SHOULD be documented. A separate description statement 1279 (within each 'enum' or 'bit' statement) SHOULD be present. 1281 leaf foo { 1282 // INCORRECT 1283 type enumeration { 1284 enum one; 1285 enum two; 1286 } 1287 description 1288 "The foo enum... 1289 one: The first enum 1290 two: The second enum"; 1291 } 1293 leaf foo { 1294 // CORRECT 1295 type enumeration { 1296 enum one { 1297 description "The first enum"; 1298 } 1299 enum two { 1300 description "The second enum"; 1301 } 1302 } 1303 description 1304 "The foo enum... "; 1305 } 1307 5.11.4. Union Types 1309 The YANG "union" type is evaluated by testing a value against each 1310 member type in the union. The first type definition that accepts a 1311 value as valid is the member type used. In general, member types 1312 SHOULD be ordered from most restrictive to least restrictive types. 1314 In the following example, the "enumeration" type will never be 1315 matched because the preceding "string" type will match everything. 1317 Incorrect: 1319 type union { 1320 type string; 1321 type enumeration { 1322 enum up; 1323 enum down; 1324 } 1325 } 1327 Correct: 1329 type union { 1330 type enumeration { 1331 enum up; 1332 enum down; 1333 } 1334 type string; 1335 } 1337 It is possible for different member types to match, depending on the 1338 input encoding format. In XML, all values are passed as string 1339 nodes, but in JSON there are different value types for numbers, 1340 booleans, and strings. 1342 In the following example, a JSON numeric value will always be matched 1343 by the "int32" type but in XML the string value representing a number 1344 will be matched by the "string" type. The second version will match 1345 the "int32" member type no matter how the input is encoded. 1347 Incorrect: 1349 type union { 1350 type string; 1351 type int32; 1352 } 1354 Correct: 1356 type union { 1357 type int32; 1358 type string; 1359 } 1361 5.11.5. Empty and Boolean 1363 YANG provides an "empty" data type, which has one value (i.e., 1364 present). The default is "not present", which is not actually a 1365 value. When used within a list key, only one value can (and must) 1366 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1367 key leaf since it is pointless. 1369 There is really no difference between a leaf of type "empty" and a 1370 leaf-list of type "empty". Both are limited to one instance. The 1371 type "empty" SHOULD NOT be used for a leaf-list. 1373 The advantage of using type "empty" instead of type "boolean" is that 1374 the default (not present) does not take up any bytes in a 1375 representation. The disadvantage is that the client may not be sure 1376 if an empty leaf is missing because it was filtered somehow or not 1377 implemented. The client may not have a complete and accurate schema 1378 for the data returned by the server, and not be aware of the missing 1379 leaf. 1381 The YANG "boolean" data type provides two values ("true" and 1382 "false"). When used within a list key, two entries can exist for 1383 this key leaf. Default values are ignored for key leafs, but a 1384 default statement is often used for plain boolean leafs. The 1385 advantage of the "boolean" type is that the leaf or leaf-list has a 1386 clear representation for both values. The default value is usually 1387 not returned unless explicitly requested by the client, so no bytes 1388 are used in a typical representation. 1390 In general, the "boolean" data type SHOULD be used instead of the 1391 "empty" data type, as shown in the example below: 1393 Incorrect: 1395 leaf flag1 { 1396 type empty; 1397 } 1399 Correct: 1401 leaf flag2 { 1402 type boolean; 1403 default false; 1404 } 1406 5.12. Reusable Type Definitions 1408 If an appropriate derived type exists in any standard module, such as 1409 [RFC6991], then it SHOULD be used instead of defining a new derived 1410 type. 1412 If an appropriate units identifier can be associated with the desired 1413 semantics, then a units statement SHOULD be present. 1415 If an appropriate default value can be associated with the desired 1416 semantics, then a default statement SHOULD be present. 1418 If a significant number of derived types are defined, and it is 1419 anticipated that these data types will be reused by multiple modules, 1420 then these derived types SHOULD be contained in a separate module or 1421 submodule, to allow easier reuse without unnecessary coupling. 1423 The description statement MUST be present. 1425 If the type definition semantics are defined in an external document 1426 (other than another YANG module indicated by an import statement), 1427 then the reference statement MUST be present. 1429 5.13. Reusable Groupings 1431 A reusable grouping is a YANG grouping that can be imported by 1432 another module, and is intended for use by other modules. This is 1433 not the same as a grouping that is used within the module it is 1434 defined, but happens to be exportable to another module because it is 1435 defined at the top-level of the YANG module. 1437 The following guidelines apply to reusable groupings, in order to 1438 make them as robust as possible: 1440 o Clearly identify the purpose of the grouping in the "description" 1441 statement. 1443 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1444 output, notification, config=true data nodes, and all data nodes). 1445 Clearly identify which XPath contexts are applicable or excluded 1446 for the grouping. 1448 o Do not reference data outside the grouping in any "path", "must", 1449 or "when" statements. 1451 o Do not include a "default" sub-statement on a leaf or choice 1452 unless the value applies on all possible contexts. 1454 o Do not include a "config" sub-statement on a data node unless the 1455 value applies on all possible contexts. 1457 o Clearly identify any external dependencies in the grouping 1458 "description" statement, such as nodes referenced by absolute path 1459 from a "path", "must", or "when" statement. 1461 5.14. Data Definitions 1463 The description statement MUST be present in the following YANG 1464 statements: 1466 o anyxml 1468 o augment 1470 o choice 1471 o container 1473 o extension 1475 o feature 1477 o grouping 1479 o identity 1481 o leaf 1483 o leaf-list 1485 o list 1487 o notification 1489 o rpc 1491 o typedef 1493 If the data definition semantics are defined in an external document, 1494 (other than another YANG module indicated by an import statement), 1495 then a reference statement MUST be present. 1497 The 'anyxml' construct may be useful to represent an HTML banner 1498 containing markup elements, such as '<b>' and '</b>', and 1499 MAY be used in such cases. However, this construct SHOULD NOT be 1500 used if other YANG data node types can be used instead to represent 1501 the desired syntax and semantics. 1503 It has been found that the 'anyxml' statement is not implemented 1504 consistently across all servers. It is possible that mixed mode XML 1505 will not be supported, or configuration anyxml nodes will not 1506 supported. 1508 If there are referential integrity constraints associated with the 1509 desired semantics that can be represented with XPath, then one or 1510 more 'must' statements SHOULD be present. 1512 For list and leaf-list data definitions, if the number of possible 1513 instances is required to be bounded for all implementations, then the 1514 max-elements statements SHOULD be present. 1516 If any 'must' or 'when' statements are used within the data 1517 definition, then the data definition description statement SHOULD 1518 describe the purpose of each one. 1520 The "choice" statement is allowed to be directly present within a 1521 "case" statement in YANG 1.1. This needs to be considered carefully. 1522 Consider simply including the nested "choice" as additional "case" 1523 statements within the parent "choice" statement. Note that the 1524 "mandatory" and "default" statements within a nested "choice" 1525 statement only apply if the "case" containing the nested "choice" 1526 statement is first selected. 1528 5.14.1. Non-Presence Containers 1530 A non-presence container is used to organize data into specific 1531 subtrees. It is not intended to have semantics within the data model 1532 beyond this purpose, although YANG allows it (e.g., "must" statement 1533 within the non-presence container). 1535 Example using container wrappers: 1537 container top { 1538 container foos { 1539 list foo { ... } 1540 } 1541 container bars { 1542 list bar { ... } 1543 } 1544 } 1546 Example without container wrappers: 1548 container top { 1549 list foo { ... } 1550 list bar { ... } 1551 } 1553 Use of non-presence containers to organize data is a subjective 1554 matter similar to use of sub-directories in a file system. The 1555 NETCONF and RESTCONF protocols do not currently support the ability 1556 to delete all list (or leaf-list) entries at once. This deficiency 1557 is sometimes avoided by use of a parent container (i.e., deleting the 1558 container also removes all child entries). 1560 5.14.2. Top-Level Data Nodes 1562 Use of top-level objects needs to be considered carefully 1564 -top-level siblings are not ordered -top-level siblings not are not 1565 static, and depends on the modules that are loaded 1566 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1567 treated as a content-match node for all top-level-siblings 1569 o a top-level list with many instances may impact performance 1571 5.15. Operation Definitions 1573 If the operation semantics are defined in an external document (other 1574 than another YANG module indicated by an import statement), then a 1575 reference statement MUST be present. 1577 If the operation impacts system behavior in some way, it SHOULD be 1578 mentioned in the description statement. 1580 If the operation is potentially harmful to system behavior in some 1581 way, it MUST be mentioned in the Security Considerations section of 1582 the document. 1584 5.16. Notification Definitions 1586 The description statement MUST be present. 1588 If the notification semantics are defined in an external document 1589 (other than another YANG module indicated by an import statement), 1590 then a reference statement MUST be present. 1592 If the notification refers to a specific resource instance, then this 1593 instance SHOULD be identified in the notification data. This is 1594 usually done by including 'leafref' leaf nodes with the key leaf 1595 values for the resource instance. For example: 1597 notification interface-up { 1598 description "Sent when an interface is activated."; 1599 leaf name { 1600 type leafref { 1601 path "/if:interfaces/if:interface/if:name"; 1602 } 1603 } 1604 } 1606 Note that there are no formal YANG statements to identify any data 1607 node resources associated with a notification. The description 1608 statement for the notification SHOULD specify if and how the 1609 notification identifies any data node resources associated with the 1610 specific event. 1612 5.17. Feature Definitions 1614 The YANG "feature" statement is used to define a label for a set of 1615 optional functionality within a module. The "if-feature" statement 1616 is used in the YANG statements associated with a feature. 1618 The set of YANG features available in a module should be considered 1619 carefully. The description-stmt within a feature-stmt MUST specify 1620 any interactions with other features. 1622 If there is a large set of objects associated with a YANG feature, 1623 then consider moving those objects to a separate module, instead of 1624 using a YANG feature. Note that the set of features within a module 1625 is easily discovered by the reader, but the set of related modules 1626 within the entire YANG library is not as easy to identity. Module 1627 names with a common prefix can help readers identity the set of 1628 related modules, but this assumes the reader will have discovered and 1629 installed all the relevant modules. 1631 Another consideration for deciding whether to create a new module or 1632 add a YANG feature is the stability of the module in question. It 1633 may be desirable to have a stable base module that is not changed 1634 frequently. If new functionality is placed in a separate module, 1635 then the base module does not need to be republished. If it is 1636 designed as a YANG feature then the module will need to be 1637 republished. 1639 If one feature requires implementation of another feature, then an 1640 "if-feature" statement SHOULD be used in the dependent "feature" 1641 statement. 1643 For example, feature2 requires implementation of feature1: 1645 feature feature1 { 1646 description "Some protocol feature"; 1647 } 1649 feature feature2 { 1650 if-feature "feature1"; 1651 description "Another protocol feature"; 1652 } 1654 5.18. YANG Data Node Constraints 1656 5.18.1. Controlling Quantity 1658 The "min-elements" and "max-elements" statements can be use to 1659 control how many list or leaf-list instances are required for a 1660 particular data node. YANG constraint statements SHOULD be used to 1661 identify conditions that apply to all implementations of the data 1662 model. If platform-specific limitations (e.g., the "max-elements" 1663 supported for a particular list) are relevant to operations, then a 1664 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1665 used to identify the limit. 1667 5.18.2. must vs. when 1669 The "must" and "when" YANG statements are used to provide cross- 1670 object referential tests. They have very different behavior. The 1671 "when" statement causes data node instances to be silently deleted as 1672 soon as the condition becomes false. A false "when" expression is 1673 not considered to be an error. 1675 The "when" statement SHOULD be used together with the "augment" or 1676 "uses" statements to achieve conditional model composition. The 1677 condition SHOULD be based on static properties of the augmented entry 1678 (e.g., list key leafs). 1680 The "must" statement causes a datastore validation error if the 1681 condition is false. This statement SHOULD be used for enforcing 1682 parameter value restrictions that involve more than one data node 1683 (e.g., end-time parameter must be after the start-time parameter). 1685 5.19. Augment Statements 1687 The YANG "augment" statement is used to define a set of data 1688 definition statements that will be added as child nodes of a target 1689 data node. The module namespace for these data nodes will be the 1690 augmenting module, not the augmented module. 1692 A top-level "augment" statement SHOULD NOT be used if the target data 1693 node is in the same module or submodule as the evaluated "augment" 1694 statement. The data definition statements SHOULD be added inline 1695 instead. 1697 5.19.1. Conditional Augment Statements 1699 The "augment" statement is often used together with the "when" 1700 statement and/or "if-feature" statement to make the augmentation 1701 conditional on some portion of the data model. 1703 The following example from [RFC7223] shows how a conditional 1704 container called "ethernet" is added to the "interface" list only for 1705 entries of the type "ethernetCsmacd". 1707 augment "/if:interfaces/if:interface" { 1708 when "if:type = 'ianaift:ethernetCsmacd'"; 1710 container ethernet { 1711 leaf duplex { 1712 ... 1713 } 1714 } 1715 } 1717 5.19.2. Conditionally Mandatory Data Definition Statements 1719 YANG has very specific rules about how configuration data can be 1720 updated in new releases of a module. These rules allow an "old 1721 client" to continue interoperating with a "new server". 1723 If data nodes are added to an existing entry, the old client MUST NOT 1724 be required to provide any mandatory parameters that were not in the 1725 original module definition. 1727 It is possible to add conditional augment statements such that the 1728 old client would not know about the new condition, and would not 1729 specify the new condition. The conditional augment statement can 1730 contain mandatory objects only if the condition is false unless 1731 explicitly requested by the client. 1733 Only a conditional augment statement that uses the "when" statement 1734 form of condition can be used in this manner. The YANG features 1735 enabled on the server cannot be controlled by the client in any way, 1736 so it is not safe to add mandatory augmenting data nodes based on the 1737 "if-feature" statement. 1739 The XPath "when" statement condition MUST NOT reference data outside 1740 of target data node because the client does not have any control over 1741 this external data. 1743 In the following dummy example, it is OK to augment the "interface" 1744 entry with "mandatory-leaf" because the augmentation depends on 1745 support for "some-new-iftype". The old client does not know about 1746 this type so it would never select this type, and therefore not be 1747 adding a mandatory data node. 1749 module example-module { 1750 namespace "http://example.com/ns/example-module"; 1751 prefix mymod; 1753 import iana-if-type { prefix iana; } 1754 import ietf-interfaces { prefix if; } 1756 identity some-new-iftype { 1757 base iana:iana-interface-type; 1758 } 1760 augment "/if:interfaces/if:interface" { 1761 when "if:type = 'mymod:some-new-iftype'"; 1763 leaf mandatory-leaf { 1764 mandatory true; 1765 ... 1766 } 1767 } 1768 } 1770 Note that this practice is safe only for creating data resources. It 1771 is not safe for replacing or modifying resources if the client does 1772 not know about the new condition. The YANG data model MUST be 1773 packaged in a way that requires the client to be aware of the 1774 mandatory data nodes if it is aware of the condition for this data. 1775 In the example above, the "some-new-iftype" identity is defined in 1776 the same module as the "mandatory-leaf" data definition statement. 1778 This practice is not safe for identities defined in a common module 1779 such as "iana-if-type" because the client is not required to know 1780 about "my-module" just because it knows about the "iana-if-type" 1781 module. 1783 5.20. Deviation Statements 1785 The YANG "deviation" statement cannot appear in IETF YANG modules, 1786 but it can be useful for documenting server capabilities. Deviation 1787 statements are not reusable and typically not shared across all 1788 platforms. 1790 There are several reasons that deviations might be needed in an 1791 implementation, e.g., an object cannot be supported on all platforms, 1792 or feature delivery is done in multiple development phases. 1793 Deviation statements can also be used to add annotations to a module, 1794 which does not affect the conformance requirements for the module. 1796 It is suggested that deviation statements be defined in separate 1797 modules from regular YANG definitions. This allows the deviations to 1798 be platform-specific and/or temporary. 1800 The order that deviation statements are evaluated can affect the 1801 result. Therefore multiple deviation statements in the same module, 1802 for the same target object, SHOULD NOT be used. 1804 The "max-elements" statement is intended to describe an architectural 1805 limit to the number of list entries. It is not intended to describe 1806 platform limitations. It is better to use a "deviation" statement 1807 for the platforms that have a hard resource limit. 1809 Example documenting platform resource limits: 1811 Wrong: (max-elements in the list itself) 1813 container backups { 1814 list backup { 1815 ... 1816 max-elements 10; 1817 ... 1818 } 1819 } 1821 Correct: (max-elements in a deviation) 1823 deviation /bk:backups/bk:backup { 1824 deviate add { 1825 max-elements 10; 1826 } 1827 } 1829 5.21. Extension Statements 1831 The YANG "extension" statement is used to specify external 1832 definitions. This appears in the YANG syntax as an 1833 "unknown-statement". Usage of extension statements in a published 1834 module needs to be considered carefully. 1836 The following guidelines apply to the usage of YANG extensions: 1838 o The semantics of the extension MUST NOT contradict any YANG 1839 statements. Extensions can add semantics not covered by the 1840 normal YANG statements. 1842 o The module containing the extension statement MUST clearly 1843 identify the conformance requirements for the extension. It 1844 should be clear whether all implementations of the YANG module 1845 containing the extension need to also implement the extension. If 1846 not, identify what conditions apply that would require 1847 implementation of the extension. 1849 o The extension MUST clearly identify where it can be used within 1850 other YANG statements. 1852 o The extension MUST clearly identify if YANG statements or other 1853 extensions are allowed or required within the extension as sub- 1854 statements. 1856 5.22. Data Correlation 1858 Data can be correlated in various ways, using common data types, 1859 common data naming, and common data organization. There are several 1860 ways to extend the functionality of a module, based on the degree of 1861 coupling between the old and new functionality: 1863 o inline: update the module with new protocol-accessible objects. 1864 The naming and data organization of the original objects is used. 1865 The new objects are in the original module namespace. 1867 o augment: create a new module with new protocol-accessible objects 1868 that augment the original data structure. The naming and data 1869 organization of the original objects is used. The new objects are 1870 in the new module namespace. 1872 o mirror: create new objects in a new module or the original module, 1873 except use new a naming scheme and data location. The naming can 1874 be coupled in different ways. Tight coupling is achieved with a 1875 "leafref" data type, with the "require-instance" sub-statement set 1876 to "true". This method SHOULD be used. 1878 If the new data instances are not limited to the values in use in the 1879 original data structure, then the "require-instance" sub-statement 1880 MUST be set to "false". Loose coupling is achieved by using key 1881 leafs with the same data type as the original data structure. This 1882 has the same semantics as setting the "require-instance" sub- 1883 statement to "false". 1885 It is sometimes useful to separate configuration and operational 1886 data, so that they do not not even share the exact same naming 1887 characteristics. The correlation between configuration the 1888 operational data that is affected by changes in configuration is a 1889 complex problem. There may not be a simple 1:1 relationship between 1890 a configuration data node and an operational data node. Further work 1891 is needed in YANG to clarify this relationship. Protocol work may 1892 also be needed to allow a client to retrieve this type of information 1893 from a server. At this time the best practice is to clearly document 1894 any relationship to other data structures in the "description" 1895 statement. 1897 5.23. Operational Data 1899 In YANG, any data that has a "config" statement value of "false" 1900 could be considered operational data. The relationship between 1901 configuration (i.e., "config" statement has a value of "true") and 1902 operational data can be complex. 1904 One challenge for client developers is determining if the configured 1905 value is being used, which requires the developer to know which 1906 operational data parameters are associated with the particular 1907 configuration object(s). 1909 If possible, operational data SHOULD be combined with its associated 1910 configuration data. This prevents duplication of key leafs and 1911 ancestor nodes. It also prevents race conditions for retrieval of 1912 dynamic entries, and allows configuration and operational data to be 1913 retrieved together with minimal message overhead. 1915 Not preferred: 1917 list foo { 1918 ... 1919 } 1921 list foo-state { 1922 config false; 1923 ... 1924 } 1926 Preferred: 1928 list foo { 1929 container foo-state { 1930 config false; 1931 ... 1932 } 1933 } 1935 If it is not possible to combine configuration and operational data, 1936 then the keys used to represent list entries SHOULD be the same type. 1937 The "leafref" data type SHOULD be used in operational data for key 1938 leafs that have corresponding configuration instances. The 1939 "require-instance" statement MAY be set to "false" (in YANG 1.1 1940 modules only) to indicate instances are allowed in the operational 1941 state that do not exist in the associated configuration data. 1943 The following example shows the use of the "leafref" data type: 1945 Not preferred: 1947 list foo { 1948 key name; 1949 leaf name { 1950 type string; 1951 } 1952 ... 1953 } 1955 list foo-state { 1956 key name; 1957 config false; 1958 leaf name { 1959 type string; 1960 } 1961 ... 1962 } 1964 Preferred: 1966 list foo { 1967 key name; 1968 leaf name { 1969 type string; 1970 } 1971 ... 1972 } 1974 list foo-state { 1975 key name; 1976 config false; 1977 leaf name { 1978 type leafref { 1979 path "/foo/name"; 1980 require-instance false; 1981 } 1982 } 1983 ... 1984 } 1986 In the simplest use-cases, there is no interaction between 1987 configuration and operational data. For example, the arbitrary 1988 administrative name or sequence number assigned to an access control 1989 rule. The configured value is always the value that is being used by 1990 the system. 1992 However, some configuration parameters interact with routing and 1993 other signalling protocols, such that the operational value in use by 1994 the system may not be the same as the configured value. Other 1995 parameters specify the desired state, but environmental and other 1996 factors can cause the actual state to be different. 1998 For example a "temperature" configuration setting only represents the 1999 desired temperature. An operational data parameter is needed that 2000 reports the actual temperature in order to determine if the cooling 2001 system is operating correctly. YANG has no mechanism other than the 2002 "description" statement to associate the desired temperature and the 2003 actual temperature. 2005 Careful consideration needs to be given to the location of 2006 operational data. It can either be located within the configuration 2007 subtree for which it applies, or it can be located outside the 2008 particular configuration subtree. Placing operational data within 2009 the configuration subtree is appropriate if the operational values 2010 can only exist if the configuration exists. Placing operational data 2011 outside the configuration subtree is appropriate if the operational 2012 values can exist without corresponding configuration (e.g., system 2013 generated interfaces). 2015 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 2016 are an example of a complex relationship between configuration and 2017 operational data. The operational values can include interface 2018 entries that have been discovered or initialized by the system. An 2019 interface may be in use that has not been configured at all. 2020 Therefore, the operational data for an interface cannot be located 2021 within the configuration for that same interface. 2023 Sometimes the configured value represents some sort of procedure to 2024 be followed, in which the system will select an actual value, based 2025 on protocol negotiation. In this case it is RECOMMENDED to have a 2026 separate config false value to represented the resulting state. For 2027 instance: 2029 leaf duplex-admin-mode { 2030 type enumeration { 2031 enum auto; 2032 enum half; 2033 enum full; 2034 } 2035 } 2037 leaf duplex-oper-mode { 2038 config false; 2039 type enumeration { 2040 enum half; 2041 enum full; 2042 } 2043 } 2045 For example a "duplex" mode configuration may be "auto" to auto- 2046 negotiate the actual value to be used. The operational parameter 2047 will never contain the value "auto". It will always contain the 2048 result of the auto-negotiation, such as "half" or "full". This is 2049 just one way in which the configuration data model is not exactly the 2050 same as the operational data model. Another is if the detailed 2051 properties of the data are different for configured vs. learned 2052 entries. 2054 If all the data model properties are aligned between configuration 2055 and operational data, then it can be useful to define the 2056 configuration parameters within a grouping, and then replicate that 2057 grouping within the operational data portion of the data model. 2059 grouping parms { 2060 // do not use config-stmt in any of the nodes 2061 // placed in this grouping 2062 } 2064 container foo { 2065 uses parms; // these are all config=true by default 2066 state { 2067 config false; // only exists if foo config exists 2068 uses parms; 2069 } 2070 } 2072 Note that this mechanism can also be used if the configuration and 2073 operational data are in separate sub-trees: 2075 container bar { // bar config can exist without bar-state 2076 config true; 2077 uses parms; 2078 } 2080 container bar-state { // bar-state can exist without bar 2081 config false; 2082 uses parms; 2083 } 2085 The need to replicate objects or define different operational data 2086 objects depends on the data model. It is not possible to define one 2087 approach that will be optimal for all data models. Designers SHOULD 2088 describe the relationship in detail between configuration objects and 2089 any associated operational data objects. The "description" 2090 statements for both the configuration and the operational data SHOULD 2091 be used for this purpose. 2093 5.24. Performance Considerations 2095 It is generally likely that certain YANG statements require more 2096 runtime resources than other statements. Although there are no 2097 performance requirements for YANG validation, the following 2098 information MAY be considered when designing YANG data models: 2100 o Lists are generally more expensive than containers 2102 o "when-stmt" evaluation is generally more expensive than 2103 "if-feature" or "choice" statements 2105 o "must" statement is generally more expensive than "min-entries", 2106 "max-entries", "mandatory", or "unique" statements 2108 o "identityref" leafs are generally more expensive than 2109 "enumeration" leafs 2111 o "leafref" and "instance-identifier" types with "require-instance" 2112 set to true are generally more expensive than if 2113 "require-instance" is set to false 2115 5.25. Open Systems Considerations 2117 A YANG module MUST NOT be designed such that the set of modules found 2118 on a server implementation can be predetermined in advance. Only the 2119 modules imported by a particular module can be assumed to be present 2120 in an implementation. An open system MAY include any combination of 2121 YANG modules. 2123 5.26. YANG 1.1 Guidelines 2125 The set of YANG 1.1 guidelines will grow as operational experience is 2126 gained with the new language features. This section contains an 2127 initial set of guidelines. 2129 5.26.1. Importing Multiple Revisions 2131 Standard modules SHOULD NOT import multiple revisions of the same 2132 module into a module. This MAY be done if the authors can 2133 demonstrate that the "avoided" definitions from the most recent of 2134 the multiple revisions are somehow broken or harmful to 2135 interoperability. 2137 5.26.2. Using Feature Logic 2139 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2140 "description" statement SHOULD describe the "if-feature" logic in 2141 text, to help readers understand the module. 2143 YANG features SHOULD be used instead of the "when" statement, if 2144 possible. Features are advertised by the server and objects 2145 conditional by if-feature are conceptually grouped together. There 2146 is no such commonality supported for "when" statements. 2148 Features generally require less server implementation complexity and 2149 runtime resources than objects that use "when" statements. Features 2150 are generally static (i.e., set when module is loaded and not changed 2151 at runtime). However every client edit might cause a "when" 2152 statement result to change. 2154 5.26.3. anyxml vs. anydata 2156 The "anyxml" statement MUST NOT be used to represent a conceptual 2157 subtree of YANG data nodes. The "anydata" statement MUST be used for 2158 this purpose. 2160 5.26.4. action vs. rpc 2162 The use of "action" statements or "rpc" statements is a subjective 2163 design decision. RPC operations are not associated with any 2164 particular data node. Actions are associated with a specific data 2165 node definition. An "action" statement SHOULD be used if the 2166 protocol operation is specific to a subset of all data nodes instead 2167 of all possible data nodes. 2169 The same action name MAY be used in different definitions within 2170 different data node. For example, a "reset" action defined with a 2171 data node definition for an interface might have different parameters 2172 than for a power supply or a VLAN. The same action name SHOULD be 2173 used to represent similar semantics. 2175 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2176 parameter access control for RPC operations. The user is given 2177 permission (or not) to invoke the RPC operation with any parameters. 2178 For example, if each client is only allowed to reset their own 2179 interface, then NACM cannot be used. 2181 For example, NACM cannot enforce access access control based on the 2182 value of the "interface" parameter, only the "reset" operation 2183 itself: 2185 rpc reset { 2186 input { 2187 leaf interface { 2188 type if:interface-ref; 2189 mandatory true; 2190 description "The interface to reset."; 2191 } 2192 } 2193 } 2195 However, NACM can enforce access access control for individual 2196 interface instances, using a "reset" action, If the user does not 2197 have read access to the specific "interface" instance, then it cannot 2198 invoke the "reset" action for that interface instance: 2200 container interfaces { 2201 list interface { 2202 ... 2203 action reset { } 2204 } 2205 } 2207 5.27. Updating YANG Modules (Published vs. Unpublished) 2209 YANG modules can change over time. Typically, new data model 2210 definitions are needed to support new features. YANG update rules 2211 defined in section 11 of [RFC7950] MUST be followed for published 2212 modules. They MAY be followed for unpublished modules. 2214 The YANG update rules only apply to published module revisions. Each 2215 organization will have their own way to identify published work which 2216 is considered to be stable, and unpublished work which is considered 2217 to be unstable. For example, in the IETF, the RFC document is used 2218 for published work, and the Internet-Draft is used for unpublished 2219 work. 2221 6. IANA Considerations 2223 -- RFC Ed: These registries need to be updated to reference this 2224 RFC instead of RFC 6087 for the ietf-template module, and 2225 remove this note. 2227 This document registers one URI in the IETF XML registry [RFC3688]. 2229 The following registration has been made in [RFC6087] and updated by 2230 this document. 2232 URI: urn:ietf:params:xml:ns:yang:ietf-template 2234 Registrant Contact: The NETMOD WG of the IETF. 2236 XML: N/A, the requested URI is an XML namespace. 2238 The following assignment has been made in [RFC6087] and updated by 2239 this document in the YANG Module Names Registry, or the YANG module 2240 template in Appendix C. 2242 +-----------+-------------------------------------------+ 2243 | Field | Value | 2244 +-----------+-------------------------------------------+ 2245 | Name | ietf-template | 2246 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2247 | Prefix | temp | 2248 | Reference | RFC XXXX | 2249 +-----------+-------------------------------------------+ 2251 YANG Registry Assignment 2253 7. Security Considerations 2255 This document defines documentation guidelines for NETCONF or 2256 RESTCONF content defined with the YANG data modeling language. The 2257 guidelines for how to write a Security Considerations section for a 2258 YANG module are defined in the online document 2260 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2261 yang-security-guidelines 2263 This document does not introduce any new or increased security risks 2264 into the management system. 2266 The following section contains the security considerations template 2267 dated 2010-06-16. Be sure to check the webpage at the URL listed 2268 above in case there is a more recent version available. 2270 Each specification that defines one or more YANG modules MUST contain 2271 a section that discusses security considerations relevant to those 2272 modules. This section MUST be patterned after the latest approved 2273 template (available at 2275 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2277 In particular, writable data nodes that could be especially 2278 disruptive if abused MUST be explicitly listed by name and the 2279 associated security risks MUST be spelled out. 2281 Similarly, readable data nodes that contain especially sensitive 2282 information or that raise significant privacy concerns MUST be 2283 explicitly listed by name and the reasons for the sensitivity/privacy 2284 concerns MUST be explained. 2286 Further, if new RPC operations have been defined, then the security 2287 considerations of each new RPC operation MUST be explained. 2289 7.1. Security Considerations Section Template 2291 X. Security Considerations 2293 The YANG module defined in this memo is designed to be accessed via 2294 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2295 secure transport layer and the mandatory-to-implement secure 2296 transport is SSH [RFC6242]. 2298 -- if you have any writable data nodes (those are all the 2299 -- "config true" nodes, and remember, that is the default) 2300 -- describe their specific sensitivity or vulnerability. 2302 There are a number of data nodes defined in this YANG module which 2303 are writable/creatable/deletable (i.e., config true, which is the 2304 default). These data nodes may be considered sensitive or vulnerable 2305 in some network environments. Write operations (e.g., edit-config) 2306 to these data nodes without proper protection can have a negative 2307 effect on network operations. These are the subtrees and data nodes 2308 and their sensitivity/vulnerability: 2310 2312 -- for all YANG modules you must evaluate whether any readable data 2313 -- nodes (those are all the "config false" nodes, but also all other 2314 -- nodes, because they can also be read via operations like get or 2315 -- get-config) are sensitive or vulnerable (for instance, if they 2316 -- might reveal customer information or violate personal privacy 2317 -- laws such as those of the European Union if exposed to 2318 -- unauthorized parties) 2320 Some of the readable data nodes in this YANG module may be considered 2321 sensitive or vulnerable in some network environments. It is thus 2322 important to control read access (e.g., via get, get-config, or 2323 notification) to these data nodes. These are the subtrees and data 2324 nodes and their sensitivity/vulnerability: 2326 2328 -- if your YANG module has defined any rpc operations 2329 -- describe their specific sensitivity or vulnerability. 2331 Some of the RPC operations in this YANG module may be considered 2332 sensitive or vulnerable in some network environments. It is thus 2333 important to control access to these operations. These are the 2334 operations and their sensitivity/vulnerability: 2336 2338 8. Acknowledgments 2340 The structure and contents of this document are adapted from 2341 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2343 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2344 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 2345 contributions to this document. 2347 9. Changes Since RFC 6087 2349 The following changes have been made to the guidelines published in 2350 [RFC6087]: 2352 o Updated NETCONF reference from RFC 4741 to RFC 6241 2354 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2356 o Updated YANG Types reference from RFC 6021 to RFC 6991 2358 o Updated obsolete URLs for IETF resources 2360 o Changed top-level data node guideline 2362 o Clarified XPath usage for a literal value representing a YANG 2363 identity 2365 o Clarified XPath usage for a when-stmt 2367 o Clarified XPath usage for 'proceeding-sibling' and 2368 'following-sibling' axes 2370 o Added terminology guidelines 2372 o Added YANG tree diagram definition and guideline 2374 o Updated XPath guidelines for type conversions and function library 2375 usage. 2377 o Updated data types section 2379 o Updated notifications section 2381 o Clarified conditional key leaf nodes 2383 o Clarify usage of 'uint64' and 'int64' data types 2385 o Added text on YANG feature usage 2387 o Added Identifier Naming Conventions 2389 o Clarified use of mandatory nodes with conditional augmentations 2391 o Clarified namespace and domain conventions for example modules 2393 o Clarified conventions for identifying code components 2394 o Added YANG 1.1 guidelines 2396 o Added Data Model Constraints section 2398 o Added mention of RESTCONF protocol 2400 10. References 2402 10.1. Normative References 2404 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2405 Requirement Levels", BCP 14, RFC 2119, March 1997. 2407 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2408 January 2004. 2410 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2411 Resource Identifier (URI): Generic Syntax", STD 66, 2412 RFC 3986, January 2005. 2414 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2415 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2417 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2418 Network Configuration Protocol (NETCONF)", RFC 6020, 2419 October 2010. 2421 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2422 July 2013. 2424 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2425 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2426 . 2428 [W3C.REC-xpath-19991116] 2429 Clark, J. and S. DeRose, "XML Path Language (XPath) 2430 Version 1.0", World Wide Web Consortium 2431 Recommendation REC-xpath-19991116, November 1999, 2432 . 2434 10.2. Informative References 2436 [I-D.ietf-netconf-restconf] 2437 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2438 Protocol", draft-ietf-netconf-restconf-17 (work in 2439 progress), September 2016. 2441 [RFC-STYLE] 2442 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2443 Style", September 2009, 2444 . 2446 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2447 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2448 . 2450 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2451 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2452 . 2454 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2455 Documents", BCP 111, RFC 4181, September 2005. 2457 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2458 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2459 May 2008. 2461 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2462 Data Model Documents", RFC 6087, January 2011. 2464 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2465 and A. Bierman, Ed., "Network Configuration Protocol 2466 (NETCONF)", RFC 6241, June 2011. 2468 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2469 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2470 . 2472 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2473 Protocol (NETCONF) Access Control Model", RFC 6536, 2474 March 2012. 2476 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2477 Management", RFC 7223, May 2014. 2479 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2480 DOI 10.17487/RFC7322, September 2014, 2481 . 2483 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2484 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2485 DOI 10.17487/RFC7841, May 2016, 2486 . 2488 Appendix A. Change Log 2490 -- RFC Ed.: remove this section before publication. 2492 A.1. v11 to v12 2494 o fix incoorect location of new Module Usage Examples section 2496 A.2. v10 to v11 2498 o updated YANG tree diagram syntax to align with pyang 1.7.1 2500 o added general guideline to include module usage examples 2502 A.3. v09 to v10 2504 o clarified is only for normative modules 2506 o clarified example module namespace URI conventions 2508 o clarified pyang usage for normative and example modules 2510 o updated YANG tree diagrams section with text from RFC 8022 2512 A.4. v08 to v09 2514 o fixed references 2516 o added mention of RESTCONF to abstract and intro 2518 o created separate section for code components 2520 o fixed document status 2522 A.5. v07 to v08 2524 o changed CODE BEGINS guideline for example modules 2526 o updated tree diagram guidelines 2528 o clarified published and unpublished terms 2530 o added section on Empty and Boolean data types 2532 o clarified how to update the revision statement 2534 o updated operational state guidelines 2535 o added 'YANG fragment' to terminology section 2537 A.6. v06 to v07 2539 o update contact statement guideline 2541 o update example modules guidelines 2543 o add guidelines on top-level data nodes 2545 o add guideline on use of NP containers 2547 o added guidelines on union types 2549 o add guideline on deviations 2551 o added section on open systems considerations 2553 o added guideline about definitions reserved for future use 2555 A.7. v05 to v06 2557 o Changed example 'my-module' to 'example-module' 2559 o Added section Updating YANG Modules (Published vs. Unpublished) 2561 o Added Example Modules section 2563 o Added "" convention for full example modules 2565 o Added section on using action vs. rpc 2567 o Changed term "operational state" to "operational data" 2569 o Added section on YANG Data Node Constraints 2571 o Added guidelines on using must vs. when statements 2573 o Made ietf-foo module validate for I-D submission 2575 A.8. v04 to v05 2577 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2578 no YANG 1.1 features needed 2580 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2581 standards track documents only) 2583 o Clarified module naming conventions for normative modules, example 2584 modules, and modules from other SDOs. 2586 o Added prefix value selection guidelines 2588 o Added new section on guidelines for reusable groupings 2590 o Made header guidelines less IETF-specific 2592 o Added new section on guidelines for extension statements 2594 o Added guidelines for nested "choice" statement within a "case" 2595 statement 2597 A.9. v03 ot v04 2599 o Added sections for deviation statements and performance 2600 considerations 2602 o Added YANG 1.1 section 2604 o Updated YANG reference from 1.0 to 1.1 2606 A.10. v02 to v03 2608 o Updated draft based on github data tracker issues added by Benoit 2609 Clause (Issues 12 - 18) 2611 A.11. v01 to v02 2613 o Updated draft based on mailing list comments. 2615 A.12. v00 to v01 2617 All issues from the issue tracker have been addressed. 2619 https://github.com/netmod-wg/rfc6087bis/issues 2621 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 2622 can use an Informative reference to this RFC for tree diagrams. 2623 Updated guidelines to reference this RFC when tree diagrams are 2624 used 2626 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2627 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2628 functions 2630 o Issue 3: XPath function document order issues: Added paragraph in 2631 XPath usage section about node-set ordering for 'local-name', 2632 'namespace-uri', 'name', 'string' and 'number' functions. Also 2633 any function that implicitly converts a node-set to a string. 2635 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2636 and text in XPath usage section already has proposed text from 2637 Lada. 2639 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2640 exception and example in XPath Usage section for augmented nodes. 2642 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2643 to 'numeric and boolean expressions' 2645 o Issue 7: XPath module containment: Added sub-section on XPath 2646 wildcards 2648 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2649 section about transitioning from active to deprecated and then to 2650 obsolete. 2652 o Issue 9: resource identification in notifications: Add text to 2653 Notifications section about identifying resources and using the 2654 leafref data type. 2656 o Issue 10: single quoted strings: Added text to Data Types section 2657 about using a single-quoted string for patterns. 2659 Appendix B. Module Review Checklist 2661 This section is adapted from RFC 4181. 2663 The purpose of a YANG module review is to review the YANG module both 2664 for technical correctness and for adherence to IETF documentation 2665 requirements. The following checklist may be helpful when reviewing 2666 an Internet-Draft: 2668 o I-D Boilerplate -- verify that the draft contains the required 2669 Internet-Draft boilerplate (see 2670 http://www.ietf.org/id-info/guidelines.html), including the 2671 appropriate statement to permit publication as an RFC, and that 2672 I-D boilerplate does not contain references or section numbers. 2674 o Abstract -- verify that the abstract does not contain references, 2675 that it does not have a section number, and that its content 2676 follows the guidelines in 2677 http://www.ietf.org/id-info/guidelines.html. 2679 o Copyright Notice -- verify that the draft has the appropriate text 2680 regarding the rights that document contributers provide to the 2681 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2682 copyright notice at the beginning of the document. The IETF Trust 2683 Legal Provisions (TLP) can be found at: 2685 http://trustee.ietf.org/license-info/ 2687 o Security Considerations section -- verify that the draft uses the 2688 latest approved template from the OPS area website (http:// 2689 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2690 and that the guidelines therein have been followed. 2692 o IANA Considerations section -- this section must always be 2693 present. For each module within the document, ensure that the 2694 IANA Considerations section contains entries for the following 2695 IANA registries: 2697 XML Namespace Registry: Register the YANG module namespace. 2699 YANG Module Registry: Register the YANG module name, prefix, 2700 namespace, and RFC number, according to the rules specified 2701 in [RFC7950]. 2703 o References -- verify that the references are properly divided 2704 between normative and informative references, that RFC 2119 is 2705 included as a normative reference if the terminology defined 2706 therein is used in the document, that all references required by 2707 the boilerplate are present, that all YANG modules containing 2708 imported items are cited as normative references, and that all 2709 citations point to the most current RFCs unless there is a valid 2710 reason to do otherwise (for example, it is OK to include an 2711 informative reference to a previous version of a specification to 2712 help explain a feature included for backward compatibility). Be 2713 sure citations for all imported modules are present somewhere in 2714 the document text (outside the YANG module). 2716 o License -- verify that the draft contains the Simplified BSD 2717 License in each YANG module or submodule. Some guidelines related 2718 to this requirement are described in Section 4.1. Make sure that 2719 the correct year is used in all copyright dates. Use the approved 2720 text from the latest Trust Legal Provisions (TLP) document, which 2721 can be found at: 2723 http://trustee.ietf.org/license-info/ 2725 o Other Issues -- check for any issues mentioned in 2726 http://www.ietf.org/id-info/checklist.html that are not covered 2727 elsewhere. 2729 o Technical Content -- review the actual technical content for 2730 compliance with the guidelines in this document. The use of a 2731 YANG module compiler is recommended when checking for syntax 2732 errors. A list of freely available tools and other information 2733 can be found at: 2735 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2737 Checking for correct syntax, however, is only part of the job. 2738 It is just as important to actually read the YANG module document 2739 from the point of view of a potential implementor. It is 2740 particularly important to check that description statements are 2741 sufficiently clear and unambiguous to allow interoperable 2742 implementations to be created. 2744 Appendix C. YANG Module Template 2746 file "ietf-template@2016-03-20.yang" 2748 module ietf-template { 2750 // replace this string with a unique namespace URN value 2751 namespace 2752 "urn:ietf:params:xml:ns:yang:ietf-template"; 2754 // replace this string, and try to pick a unique prefix 2755 prefix "temp"; 2757 // import statements here: e.g., 2758 // import ietf-yang-types { prefix yang; } 2759 // import ietf-inet-types { prefix inet; } 2761 // identify the IETF working group if applicable 2762 organization 2763 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2765 // update this contact statement with your info 2766 contact 2767 "WG Web: 2768 WG List: 2770 Editor: your-name 2771 "; 2773 // replace the first sentence in this description statement. 2774 // replace the copyright notice with the most recent 2775 // version, if it has been updated since the publication 2776 // of this document 2777 description 2778 "This module defines a template for other YANG modules. 2780 Copyright (c) IETF Trust and the persons 2781 identified as authors of the code. All rights reserved. 2783 Redistribution and use in source and binary forms, with or 2784 without modification, is permitted pursuant to, and subject 2785 to the license terms contained in, the Simplified BSD License 2786 set forth in Section 4.c of the IETF Trust's Legal Provisions 2787 Relating to IETF Documents 2788 (http://trustee.ietf.org/license-info). 2790 This version of this YANG module is part of RFC XXXX; see 2791 the RFC itself for full legal notices."; 2793 // RFC Ed.: replace XXXX with actual RFC number and remove 2794 // this note 2796 reference "RFC XXXX"; 2798 // RFC Ed.: remove this note 2799 // Note: extracted from RFC XXXX 2801 // replace '2016-03-20' with the module publication date 2802 // The format is (year-month-day) 2803 revision "2016-03-20" { 2804 description "what changed in this revision"; 2805 reference "document containing this module"; 2806 } 2808 // extension statements 2810 // feature statements 2812 // identity statements 2814 // typedef statements 2816 // grouping statements 2818 // data definition statements 2820 // augment statements 2822 // rpc statements 2824 // notification statements 2826 // DO NOT put deviation statements in a published module 2828 } 2830 2832 Author's Address 2834 Andy Bierman 2835 YumaWorks 2837 Email: andy@yumaworks.com