idnits 2.17.1 draft-ietf-netmod-rfc6087bis-09.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 -- The document date (October 25, 2016) is 2740 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 378, but not defined == 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 (~~), 3 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) October 25, 2016 5 Intended status: Informational 6 Expires: April 28, 2017 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-09 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 April 28, 2017. 38 Copyright Notice 40 Copyright (c) 2016 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 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15 78 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15 79 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17 81 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17 82 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18 83 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18 84 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19 85 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19 86 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20 87 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 21 88 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 21 89 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 22 90 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 22 91 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 23 92 5.8. Module Header, Meta, and Revision Statements . . . . . . . 24 93 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 25 94 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 26 95 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 27 96 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 27 97 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 28 98 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 29 99 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 30 100 5.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 31 101 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 32 102 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 33 103 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 33 104 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 35 105 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 35 106 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 36 107 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 36 108 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 37 109 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 37 110 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 37 111 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 38 112 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 38 113 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 38 114 5.19.2. Conditionally Mandatory Data Definition Statements . . 39 115 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 40 116 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 41 117 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 42 118 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43 119 5.24. Performance Considerations . . . . . . . . . . . . . . . . 47 120 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 47 121 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 48 122 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 48 123 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 48 124 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48 125 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48 126 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49 127 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 128 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 129 7.1. Security Considerations Section Template . . . . . . . . . 52 130 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 131 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55 132 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 133 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57 134 10.2. Informative References . . . . . . . . . . . . . . . . . . 57 135 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59 136 A.1. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 59 137 A.2. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59 138 A.3. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 59 139 A.4. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 60 140 A.5. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60 141 A.6. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 60 142 A.7. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 61 143 A.8. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61 144 A.9. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61 145 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 63 146 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 65 147 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 67 149 1. Introduction 151 The standardization of network configuration interfaces for use with 152 the Network Configuration Protocol [RFC6241] and RESTCONF 153 [I-D.ietf-netconf-restconf] requires a modular set of data models, 154 which can be reused and extended over time. 156 This document defines a set of usage guidelines for Standards Track 157 documents containing [RFC7950] data models. YANG is used to define 158 the data structures, protocol operations, and notification content 159 used within a NETCONF and/or RESTCONF server. A server that supports 160 a particular YANG module will support client NETCONF and/or RESTCONF 161 operation requests, as indicated by the specific content defined in 162 the YANG module. 164 This document is similar to the Structure of Management Information 165 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 166 and structure. However, since that document was written a decade 167 after SMIv2 modules had been in use, it was published as a 'Best 168 Current Practice' (BCP). This document is not a BCP, but rather an 169 informational reference, intended to promote consistency in documents 170 containing YANG modules. 172 Many YANG constructs are defined as optional to use, such as the 173 description statement. However, in order to maximize 174 interoperability of NETCONF and RESTCONF implementations utilizing 175 YANG data models, it is desirable to define a set of usage guidelines 176 that may require a higher level of compliance than the minimum level 177 defined in the YANG specification. 179 In addition, YANG allows constructs such as infinite length 180 identifiers and string values, or top-level mandatory nodes, that a 181 compliant server is not required to support. Only constructs that 182 all servers are required to support can be used in IETF YANG modules. 184 This document defines usage guidelines related to the NETCONF 185 operations layer and NETCONF content layer, as defined in [RFC6241], 186 and the RESTCONF methods and RESTCONF resources, as defined in 187 [I-D.ietf-netconf-restconf], 189 These guidelines are intended to be used by authors and reviewers to 190 improve the readability and interoperability of published YANG data 191 models. 193 Note that this document is not a YANG tutorial and the reader is 194 expected to know the YANG data modeling language before using this 195 document. 197 2. Terminology 199 2.1. Requirements Notation 201 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 202 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 203 document are to be interpreted as described in [RFC2119]. 205 RFC 2119 language is used here to express the views of the NETMOD 206 working group regarding content for YANG modules. YANG modules 207 complying with this document will treat the RFC 2119 terminology as 208 if it were describing best current practices. 210 2.2. NETCONF Terms 212 The following terms are defined in [RFC6241] and are not redefined 213 here: 215 o capabilities 217 o client 219 o operation 221 o server 223 2.3. YANG Terms 225 The following terms are defined in [RFC7950] and are not redefined 226 here: 228 o data node 230 o module 232 o namespace 234 o submodule 236 o version 238 o YANG 240 o YIN 242 Note that the term 'module' may be used as a generic term for a YANG 243 module or submodule. When describing properties that are specific to 244 submodules, the term 'submodule' is used instead. 246 2.4. Terms 248 The following terms are used throughout this document: 250 o published: A stable release of a module or submodule. For example 251 the "Request for Comments" described in section 2.1 of [RFC2026] 252 is considered a stable publication. 254 o unpublished: An unstable release of a module or submodule. For 255 example the "Internet-Draft" described in section 2.2 of [RFC2026] 256 is considered an unstable publication that is a work-in-progress, 257 subject to change at any time. 259 o YANG fragment: A set of YANG statements that are not intended to 260 represent a complete YANG module or submodule. These statements 261 are not intended for actual use, except to provide an example of 262 YANG statement usage. The invalid syntax "..." is sometimes used 263 to indicate that additional YANG statements would be present in a 264 real YANG module. 266 3. YANG Tree Diagrams 268 YANG tree diagrams provide a concise representation of a YANG module 269 to help readers understand the module structure. 271 The meaning of the symbols in YANG tree diagrams is as follows: 273 o Brackets "[" and "]" enclose list keys. 275 o Abbreviations before data node names: "rw" means configuration 276 (read-write) and "ro" state data (read-only). 278 o Symbols after data node names: "?" means an optional node, "!" 279 means a presence container, and "*" denotes a list and leaf-list. 281 o Parentheses enclose choice and case nodes, and case nodes are also 282 marked with a colon (":"). 284 o Ellipsis ("...") stands for contents of subtrees that are not 285 shown. 287 4. General Documentation Guidelines 289 YANG data model modules under review are likely to be contained in 290 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 291 followed. The RFC Editor provides guidelines for authors of RFCs, 292 which are first published as Internet-Drafts. These guidelines 293 should be followed and are defined in [RFC7322] and updated in 294 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 296 The following sections MUST be present in an Internet-Draft 297 containing a module: 299 o Narrative sections 301 o Definitions section 303 o Security Considerations section 305 o IANA Considerations section 307 o References section 309 There are three usage scenarios for YANG that can appear in an 310 Internet-Draft or RFC: 312 o normative module or submodule 314 o example module or submodule 316 o example YANG fragment not part of any module or submodule 318 The guidelines in this document refer mainly to a normative complete 319 module or submodule, but may be applicable to example modules and 320 YANG fragments as well. 322 4.1. Module Copyright 324 The module description statement MUST contain a reference to the 325 latest approved IETF Trust Copyright statement, which is available 326 online at: 328 http://trustee.ietf.org/license-info/ 330 4.2. Code Components 332 Each YANG module or submodule contained within an Internet-Draft or 333 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 335 component. 337 The "" tag SHOULD be followed by a string identifying 338 the file name specified in Section 5.2 of [RFC7950]. The following 339 example is for the '2010-01-18' revision of the 'ietf-foo' module: 341 file "ietf-foo@2016-03-20.yang" 343 module ietf-foo { 344 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 345 prefix "foo"; 346 organization "..."; 347 contact "..."; 348 description "..."; 349 revision 2016-03-20 { 350 description "Latest revision"; 351 reference "RFC XXXX"; 352 } 353 // ... more statements 354 } 356 358 4.2.1. Example Modules 360 The convention SHOULD be used for complete example 361 modules, but not YANG fragments. This allows module extraction tools 362 to ignore partial YANG modules that are not intended to be compiled. 364 An example module SHOULD be named using the term "example", followed 365 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 367 4.3. Terminology Section 369 A terminology section MUST be present if any terms are defined in the 370 document or if any terms are imported from other documents. 372 If YANG tree diagrams are used, then a sub-section explaining the 373 YANG tree diagram syntax MUST be present, containing the following 374 text: 376 A simplified graphical representation of the data model is used in 377 this document. The meaning of the symbols in these diagrams is 378 defined in [RFCXXXX]. 380 -- RFC Editor: Replace XXXX with RFC number and remove note 382 4.4. Tree Diagrams 384 YANG tree diagrams provide a concise representation of a YANG module, 385 and SHOULD be included to help readers understand YANG module 386 structure. Tree diagrams MAY be split into sections to correspond to 387 document structure. 389 The following example shows a simple YANG tree diagram: 391 +--rw top-level-config-container 392 | +--rw config-list* [key-name] 393 | +--rw key-name string 394 | +--rw optional-parm? string 395 | +--rw mandatory-parm identityref 396 | +--ro read-only-leaf string 397 +--ro top-level-nonconfig-container 398 +--ro nonconfig-list* [name] 399 +--ro name string 400 +--ro type string 402 The 'pyang' compiler can be used to produce the tree diagram, using 403 the '-f tree' command line parameter. 405 If the YANG module is comprised of groupings only, then the tree 406 diagram SHOULD contain the groupings. The 'pyang' compiler can be 407 used to produce a tree diagram with groupings using the '-f tree 408 --tree-print-groupings" command line parameters. 410 If the YANG module contains notifications, then the tree diagram 411 SHOULD contain the notifications. If the YANG module contains RPC 412 statements, then the tree diagram SHOULD contain the RPC statements. 414 4.5. Narrative Sections 416 The narrative part MUST include an overview section that describes 417 the scope and field of application of the module(s) defined by the 418 specification and that specifies the relationship (if any) of these 419 modules to other standards, particularly to standards containing 420 other YANG modules. The narrative part SHOULD include one or more 421 sections to briefly describe the structure of the modules defined in 422 the specification. 424 If the module(s) defined by the specification imports definitions 425 from other modules (except for those defined in the [RFC7950] or 426 [RFC6991] documents), or are always implemented in conjunction with 427 other modules, then those facts MUST be noted in the overview 428 section, as MUST be noted any special interpretations of definitions 429 in other modules. 431 4.6. Definitions Section 433 This section contains the module(s) defined by the specification. 434 These modules SHOULD be written using the YANG syntax defined in 435 [RFC7950]. YANG 1.0 [RFC6020] MAY be used if no YANG 1.1 constructs 436 or semantics are needed in the module. 438 A YIN syntax version of the module MAY also be present in the 439 document. There MAY also be other types of modules present in the 440 document, such as SMIv2, which are not affected by these guidelines. 442 Note that all YANG statements within a YANG module are considered 443 normative, if the module itself is considered normative, and not an 444 example module. The use of keywords defined in [RFC2119] apply to 445 YANG description statements in normative modules exactly as they 446 would in any other normative section. 448 Example YANG modules MUST NOT contain any normative text, including 449 any reserved words from [RFC2119]. 451 See Section 5 for guidelines on YANG usage. 453 4.7. Security Considerations Section 455 Each specification that defines one or more modules MUST contain a 456 section that discusses security considerations relevant to those 457 modules. 459 This section MUST be patterned after the latest approved template 460 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 461 yang-security-guidelines). Section 7.1 contains the security 462 considerations template dated 2013-05-08. Authors MUST check the WEB 463 page at the URL listed above in case there is a more recent version 464 available. 466 In particular: 468 o Writable data nodes that could be especially disruptive if abused 469 MUST be explicitly listed by name and the associated security 470 risks MUST be explained. 472 o Readable data nodes that contain especially sensitive information 473 or that raise significant privacy concerns MUST be explicitly 474 listed by name and the reasons for the sensitivity/privacy 475 concerns MUST be explained. 477 o Operations (i.e., YANG 'rpc' statements) that are potentially 478 harmful to system behavior or that raise significant privacy 479 concerns MUST be explicitly listed by name and the reasons for the 480 sensitivity/privacy concerns MUST be explained. 482 4.8. IANA Considerations Section 484 In order to comply with IESG policy as set forth in 485 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 486 is submitted to the IESG for publication MUST contain an IANA 487 Considerations section. The requirements for this section vary 488 depending on what actions are required of the IANA. If there are no 489 IANA considerations applicable to the document, then the IANA 490 Considerations section stating that there are no actions is removed 491 by the RFC Editor before publication. Refer to the guidelines in 492 [RFC5226] for more details. 494 4.8.1. Documents that Create a New Namespace 496 If an Internet-Draft defines a new namespace that is to be 497 administered by the IANA, then the document MUST include an IANA 498 Considerations section that specifies how the namespace is to be 499 administered. 501 Specifically, if any YANG module namespace statement value contained 502 in the document is not already registered with IANA, then a new YANG 503 Namespace registry entry MUST be requested from the IANA. The 504 [RFC7950] specification includes the procedure for this purpose in 505 its IANA Considerations section. 507 4.8.2. Documents that Extend an Existing Namespace 509 It is possible to extend an existing namespace using a YANG submodule 510 that belongs to an existing module already administered by IANA. In 511 this case, the document containing the main module MUST be updated to 512 use the latest revision of the submodule. 514 4.9. Reference Sections 516 For every import or include statement that appears in a module 517 contained in the specification, which identifies a module in a 518 separate document, a corresponding normative reference to that 519 document MUST appear in the Normative References section. The 520 reference MUST correspond to the specific module version actually 521 used within the specification. 523 For every normative reference statement that appears in a module 524 contained in the specification, which identifies a separate document, 525 a corresponding normative reference to that document SHOULD appear in 526 the Normative References section. The reference SHOULD correspond to 527 the specific document version actually used within the specification. 528 If the reference statement identifies an informative reference, which 529 identifies a separate document, a corresponding informative reference 530 to that document MAY appear in the Informative References section. 532 4.10. Validation Tools 534 All modules need to be validated before submission in an Internet 535 Draft. The 'pyang' YANG compiler is freely available from github: 537 https://github.com/mbj4668/pyang 539 If the 'pyang' compiler is used, then the "--ietf" command line 540 option SHOULD be used to identify any IETF guideline issues. 542 4.11. Module Extraction Tools 544 A version of 'rfcstrip' is available which will extract YANG modules 545 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 546 YANG module extraction is freely available: 548 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 550 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 552 can be extracted correctly. 554 5. YANG Usage Guidelines 556 In general, modules in IETF Standards Track specifications MUST 557 comply with all syntactic and semantic requirements of YANG 558 [RFC7950]. The guidelines in this section are intended to supplement 559 the YANG specification, which is intended to define a minimum set of 560 conformance requirements. 562 In order to promote interoperability and establish a set of practices 563 based on previous experience, the following sections establish usage 564 guidelines for specific YANG constructs. 566 Only guidelines that clarify or restrict the minimum conformance 567 requirements are included here. 569 5.1. Module Naming Conventions 571 Normative modules contained in Standards Track documents MUST be 572 named according to the guidelines in the IANA Considerations section 573 of [RFC7950]. 575 A distinctive word or acronym (e.g., protocol name or working group 576 acronym) SHOULD be used in the module name. If new definitions are 577 being defined to extend one or more existing modules, then the same 578 word or acronym should be reused, instead of creating a new one. 580 All published module names MUST be unique. For a YANG module 581 published in an RFC, this uniqueness is guaranteed by IANA. For 582 unpublished modules, the authors need to check that no other work in 583 progress is using the same module name. 585 Example modules are non-normative, and SHOULD be named with the 586 prefix "example-". 588 It is suggested that a stable prefix be selected representing the 589 entire organization. All normative YANG modules published by the 590 IETF MUST begin with the prefix "ietf-". Another standards 591 organization, such as the IEEE, might use the prefix "ieee-" for all 592 YANG modules. 594 Once a module name is published, it MUST NOT be reused, even if the 595 RFC containing the module is reclassified to 'Historic' status. A 596 module name cannot be changed in YANG, and this would be treated as a 597 a new module, not a name change. 599 5.2. Prefixes 601 All YANG definitions are scoped by the module containing the 602 definition being referenced. This allows definitions from multiple 603 modules to be used, even if the names are not unique. In the example 604 below, the identifier "foo" is used in all 3 modules: 606 module example-foo { 607 namespace "http://example.com/ns/foo"; 608 prefix f; 610 container foo; 611 } 613 module example-bar { 614 namespace "http://example.com/ns/bar"; 615 prefix b; 617 typedef foo { type uint32; } 618 } 620 module example-one { 621 namespace "http://example.com/ns/one"; 622 prefix one; 623 import example-foo { prefix f; } 624 import example-bar { prefix b; } 626 augment "/f:foo" { 627 leaf foo { type b:foo; } 628 } 629 } 631 YANG defines the following rules for prefix usage: 633 o Prefixes are never allowed for built in data types and YANG 634 keywords. 636 o A prefix MUST be used for any external statement (i.e., a 637 statement defined with the YANG "extension" statement) 639 o The proper module prefix MUST be used for all identifiers imported 640 from other modules 642 o The proper module prefix MUST be used for all identifiers included 643 from a submodule. 645 The following guidelines apply to prefix usage of the current (local) 646 module: 648 o The local module prefix SHOULD be used instead of no prefix in all 649 path expressions. 651 o The local module prefix MUST be used instead of no prefix in all 652 "default" statements for an "identityref" or "instance-identifier" 653 data type 655 o The local module prefix MAY be used for references to typedefs, 656 groupings, extensions, features, and identities defined in the 657 module. 659 Prefix values SHOULD be short, but also likely to be unique. Prefix 660 values SHOULD NOT conflict with known modules that have been 661 previously published. 663 5.3. Identifiers 665 Identifiers for all YANG identifiers in published modules MUST be 666 between 1 and 64 characters in length. These include any construct 667 specified as an 'identifier-arg-str' token in the ABNF in Section 13 668 of [RFC7950]. 670 5.3.1. Identifier Naming Conventions 672 Identifiers SHOULD follow a consistent naming pattern throughout the 673 module. Only lower-case letters, numbers, and dashes SHOULD be used 674 in identifier names. Upper-case characters and the underscore 675 character MAY be used if the identifier represents a well-known value 676 that uses these characters. 678 Identifiers SHOULD include complete words and/or well-known acronyms 679 or abbreviations. Child nodes within a container or list SHOULD NOT 680 replicate the parent identifier. YANG identifiers are hierarchical 681 and are only meant to be unique within the the set of sibling nodes 682 defined in the same module namespace. 684 It is permissible to use common identifiers such as "name" or "id" in 685 data definition statements, especially if these data nodes share a 686 common data type. 688 Identifiers SHOULD NOT carry any special semantics that identify data 689 modelling properties. Only YANG statements and YANG extension 690 statements are designed to convey machine readable data modelling 691 properties. For example, naming an object "config" or "state" does 692 not change whether it is configuration data or state data. Only 693 defined YANG statements or YANG extension statements can be used to 694 assign semantics in a machine readable format in YANG. 696 5.4. Defaults 698 In general, it is suggested that substatements containing very common 699 default values SHOULD NOT be present. The following substatements 700 are commonly used with the default value, which would make the module 701 difficult to read if used everywhere they are allowed. 703 +--------------+---------------+ 704 | Statement | Default Value | 705 +--------------+---------------+ 706 | config | true | 707 | mandatory | false | 708 | max-elements | unbounded | 709 | min-elements | 0 | 710 | ordered-by | system | 711 | status | current | 712 | yin-element | false | 713 +--------------+---------------+ 715 Statement Defaults 717 5.5. Conditional Statements 719 A module may be conceptually partitioned in several ways, using the 720 'if-feature' and/or 'when' statements. 722 Data model designers need to carefully consider all modularity 723 aspects, including the use of YANG conditional statements. 725 If a data definition is optional, depending on server support for a 726 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 727 statement SHOULD be defined to indicate that the NETCONF or RESTCONF 728 capability is supported within the data model. 730 If any notification data, or any data definition, for a non- 731 configuration data node is not mandatory, then the server may or may 732 not be required to return an instance of this data node. If any 733 conditional requirements exist for returning the data node in a 734 notification payload or retrieval request, they MUST be documented 735 somewhere. For example, a 'when' or 'if-feature' statement could 736 apply to the data node, or the conditional requirements could be 737 explained in a 'description' statement within the data node or one of 738 its ancestors (if any). 740 If any 'if-feature' statements apply to a list node, then the same 741 'if-feature' statements MUST apply to any key leaf nodes for the 742 list. There MUST NOT be any 'if-feature' statements applied to any 743 key leaf that do not also apply to the parent list node. 745 There SHOULD NOT be any 'when' statements applied to a key leaf node. 746 It is possible that a 'when' statement for an ancestor node of a key 747 leaf will have the exact node-set result as the key leaf. In such a 748 case, the 'when' statement for the key leaf is redundant and SHOULD 749 be avoided. 751 5.6. XPath Usage 753 This section describes guidelines for using the XML Path Language 754 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 756 5.6.1. XPath Evaluation Contexts 758 YANG defines 5 separate contexts for evaluation of XPath statements: 760 1) The "running" datastore: collection of all YANG configuration data 761 nodes. The document root is the conceptual container, (e.g., 762 "config" in the "edit-config" operation), which is the parent of all 763 top-level data definition statements with a "config" statement value 764 of "true". 766 2) State data + the "running" datastore: collection of all YANG data 767 nodes. The document root is the conceptual container, parent of all 768 top-level data definition statements. 770 3) Notification: an event notification document. The document root 771 is the notification element. 773 4) RPC Input: The document root is the conceptual "input" node, which 774 is the parent of all RPC input parameter definitions. 776 5) RPC Output: The document root is the conceptual "output" node, 777 which is the parent of all RPC output parameter definitions. 779 Note that these XPath contexts cannot be mixed. For example, a 780 "when" statement in a notification context cannot reference 781 configuration data. 783 notification foo { 784 leaf mtu { 785 // NOT OK because when-stmt context is this notification 786 when "/if:interfaces/if:interface[name='eth0']"; 787 type leafref { 788 // OK because path-stmt has a different context 789 path "/if:interfaces/if:interface/if:mtu"; 790 } 791 } 792 } 794 It is especially important to consider the XPath evaluation context 795 for XPath expressions defined in groupings. An XPath expression 796 defined in a grouping may not be portable, meaning it cannot be used 797 in multiple contexts and produce proper results. 799 If the XPath expressions defined in a grouping are intended for a 800 particular context, then this context SHOULD be identified in the 801 "description" statement for the grouping. 803 5.6.2. Function Library 805 The 'position' and 'last' functions SHOULD NOT be used. This applies 806 to implicit use of the 'position' function as well (e.g., 807 '//chapter[42]'). A server is only required to maintain the relative 808 XML document order of all instances of a particular user-ordered list 809 or leaf-list. The 'position' and 'last' functions MAY be used if 810 they are evaluated in a context where the context node is a user- 811 ordered 'list' or 'leaf-list'. 813 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 814 present in YANG documents so this function has no meaning. The YANG 815 compiler SHOULD return an empty string for this function. 817 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 818 Expanded names in XPath are different than YANG. A specific 819 canonical representation of a YANG expanded name does not exist. 821 The 'lang' function SHOULD NOT be used. This function does not apply 822 to YANG because there is no 'lang' attribute set with the document. 823 The YANG compiler SHOULD return 'false' for this function. 825 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 826 functions SHOULD NOT be used if the argument is a node-set. If so, 827 the function result will be determined by the document order of the 828 node-set. Since this order can be different on each server, the 829 function results can also be different. Any function call that 830 implicitly converts a node-set to a string will also have this issue. 832 The 'local-name' function SHOULD NOT be used to reference local names 833 outside of the YANG module defining the must or when expression 834 containing the 'local-name' function. Example of a local-name 835 function that should not be used: 837 /*[local-name()='foo'] 839 5.6.3. Axes 841 The 'attribute' and 'namespace' axes are not supported in YANG, and 842 MAY be empty in a NETCONF or RESTCONF server implementation. 844 The 'preceding', and 'following' axes SHOULD NOT be used. These 845 constructs rely on XML document order within a NETCONF or RESTCONF 846 server configuration database, which may not be supported 847 consistently or produce reliable results across implementations. 848 Predicate expressions based on static node properties (e.g., element 849 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 850 instead. The 'preceding' and 'following' axes MAY be used if 851 document order is not relevant to the outcome of the expression 852 (e.g., check for global uniqueness of a parameter value). 854 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 855 however they MAY be used if document order is not relevant to the 856 outcome of the expression. 858 A server is only required to maintain the relative XML document order 859 of all instances of a particular user-ordered list or leaf-list. The 860 'preceding-sibling' and 'following-sibling' axes MAY be used if they 861 are evaluated in a context where the context node is a user-ordered 862 'list' or 'leaf-list'. 864 5.6.4. Types 866 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 867 be used within numeric or boolean expressions. There are boundary 868 conditions in which the translation from the YANG 64-bit type to an 869 XPath number can cause incorrect results. Specifically, an XPath 870 'double' precision floating point number cannot represent very large 871 positive or negative 64-bit numbers because it only provides a total 872 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 873 used in numeric expressions if the value can be represented with no 874 more than 53 bits of precision. 876 Data modelers need to be careful not to confuse the YANG value space 877 and the XPath value space. The data types are not the same in both, 878 and conversion between YANG and XPath data types SHOULD be considered 879 carefully. 881 Explicit XPath data type conversions MAY be used (e.g., 'string', 882 'boolean', or 'number' functions), instead of implicit XPath data 883 type conversions. 885 XPath expressions that contain a literal value representing a YANG 886 identity SHOULD always include the declared prefix of the module 887 where the identity is defined. 889 XPath expressions for 'when' statements SHOULD NOT reference the 890 context node or any descendant nodes of the context node. They MAY 891 reference descendant nodes if the 'when' statement is contained 892 within an 'augment' statement, and the referenced nodes are not 893 defined within the 'augment' statement. 895 Example: 897 augment "/rt:active-route/rt:input/rt:destination-address" { 898 when "rt:address-family='v4ur:ipv4-unicast'" { 899 description 900 "This augment is valid only for IPv4 unicast."; 901 } 902 // nodes defined here within the augment-stmt 903 // cannot be referenced in the when-stmt 904 } 906 5.6.5. Wildcards 908 It is possible to construct XPath expressions that will evaluate 909 differently when combined with several modules within a server 910 implementation, then when evaluated within the single module. This 911 is due to augmenting nodes from other modules. 913 Wildcard expansion is done within a server against all the nodes from 914 all namespaces, so it is possible for a 'must' or 'when' expression 915 that uses the '*' operator will always evaluate to false if processed 916 within a single YANG module. In such cases, the 'description' 917 statement SHOULD clarify that augmenting objects are expected to 918 match the wildcard expansion. 920 when /foo/services/*/active { 921 description 922 "No services directly defined in this module. 923 Matches objects that have augmented the services container."; 924 } 926 5.6.6. Boolean Expressions 928 The YANG "must" and "when" statements use an XPath boolean expression 929 to define the test condition for the statement. It is important to 930 specify these expressions in a way that will not cause inadvertent 931 changes in the result if the objects referenced in the expression are 932 updated in future revisions of the module. 934 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 935 to "one" or "three": 937 leaf foo1 { 938 type enumeration { 939 enum one; 940 enum two; 941 enum three; 942 } 943 } 945 leaf foo2 { 946 // INCORRECT 947 must "/f:foo1 != 'two'"; 948 type string; 949 } 951 leaf foo2 { 952 // CORRECT 953 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 954 type string; 955 } 957 In the next revision of the module, leaf "foo1" is extended with a 958 new enum named "four": 960 leaf foo1 { 961 type enumeration { 962 enum one; 963 enum two; 964 enum three; 965 enum four; 966 } 967 } 969 Now the first XPath expression will allow the enum "four" to be 970 accepted in addition to the "one" and "three" enum values. 972 5.7. Lifecycle Management 974 The status statement MUST be present if its value is 'deprecated' or 975 'obsolete'. The status SHOULD NOT be changed from 'current' directly 976 to 'obsolete'. An object SHOULD be available for at least one year 977 with 'deprecated' status before it is changed to 'obsolete'. 979 The module or submodule name MUST NOT be changed, once the document 980 containing the module or submodule is published. 982 The module namespace URI value MUST NOT be changed, once the document 983 containing the module is published. 985 The revision-date substatement within the import statement SHOULD be 986 present if any groupings are used from the external module. 988 The revision-date substatement within the include statement SHOULD be 989 present if any groupings are used from the external submodule. 991 If submodules are used, then the document containing the main module 992 MUST be updated so that the main module revision date is equal or 993 more recent than the revision date of any submodule that is (directly 994 or indirectly) included by the main module. 996 Definitions for future use SHOULD NOT be specified in a module. Do 997 not specify placeholder objects like the "reserved" example below: 999 leaf reserved { 1000 type string; 1001 description 1002 "This object has no purpose at this time, but a future 1003 revision of this module might define a purpose 1004 for this object."; 1005 } 1006 } 1008 5.8. Module Header, Meta, and Revision Statements 1010 For published modules, the namespace MUST be a globally unique URI, 1011 as defined in [RFC3986]. This value is usually assigned by the IANA. 1013 The organization statement MUST be present. If the module is 1014 contained in a document intended for IETF Standards Track status, 1015 then the organization SHOULD be the IETF working group chartered to 1016 write the document. For other standards organizations, a similar 1017 approach is also suggested. 1019 The contact statement MUST be present. If the module is contained in 1020 a document intended for Standards Track status, then the working 1021 group web and mailing information MUST be present, and the main 1022 document author or editor contact information SHOULD be present. If 1023 additional authors or editors exist, their contact information MAY be 1024 present. 1026 The description statement MUST be present. For modules published 1027 within IETF documents, the appropriate IETF Trust Copyright text MUST 1028 be present, as described in Section 4.1. 1030 If the module relies on information contained in other documents, 1031 which are not the same documents implied by the import statements 1032 present in the module, then these documents MUST be identified in the 1033 reference statement. 1035 A revision statement MUST be present for each published version of 1036 the module. The revision statement MUST have a reference 1037 substatement. It MUST identify the published document that contains 1038 the module. Modules are often extracted from their original 1039 documents, and it is useful for developers and operators to know how 1040 to find the original source document in a consistent manner. The 1041 revision statement MAY have a description substatement. 1043 It is not required to keep the full revision history of draft 1044 versions (e.g., modules contained within Internet-Drafts). That is, 1045 within a sequence of draft versions, only the most recent revision 1046 need be recorded in the module. However, whenever a new (i.e. 1047 changed) version is made available (e.g., via a new version of an 1048 Internet-Draft), the revision date of that new version MUST be 1049 updated to a date later than that of the previous version. 1051 5.9. Namespace Assignments 1053 It is RECOMMENDED that only valid YANG modules be included in 1054 documents, whether or not they are published yet. This allows: 1056 o the module to compile correctly instead of generating disruptive 1057 fatal errors. 1059 o early implementors to use the modules without picking a random 1060 value for the XML namespace. 1062 o early interoperability testing since independent implementations 1063 will use the same XML namespace value. 1065 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1066 provided for the namespace statement in a YANG module. A value 1067 SHOULD be selected that is not likely to collide with other YANG 1068 namespaces. Standard module names, prefixes, and URI strings already 1069 listed in the YANG Module Registry MUST NOT be used. 1071 A standard namespace statement value SHOULD have the following form: 1073 : 1075 The following URN prefix string SHOULD be used for published and 1076 unpublished YANG modules: 1078 urn:ietf:params:xml:ns:yang: 1080 The following example URNs would be valid namespace statement values 1081 for Standards Track modules: 1083 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1085 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1087 urn:ietf:params:xml:ns:yang:ietf-netconf 1089 Note that a different URN prefix string SHOULD be used for non- 1090 Standards-Track modules. The string SHOULD be selected according to 1091 the guidelines in [RFC7950]. 1093 The following examples are for non-Standards-Track modules. The 1094 domain "example.com" SHOULD be used in all namespace URIs for example 1095 modules. 1097 http://example.com/ns/example-interfaces 1099 http://example.com/ns/example-system 1101 5.10. Top-Level Data Definitions 1103 The top-level data organization SHOULD be considered carefully, in 1104 advance. Data model designers need to consider how the functionality 1105 for a given protocol or protocol family will grow over time. 1107 The separation of configuration data and operational data SHOULD be 1108 considered carefully. It is sometimes useful to define separate top- 1109 level containers for configuration and non-configuration data. For 1110 some existing top-level data nodes, configuration data was not in 1111 scope, so only one container representing operational data was 1112 created. 1114 The number of top-level data nodes within a module SHOULD be 1115 minimized. It is often useful to retrieve related information within 1116 a single subtree. If data is too distributed, is becomes difficult 1117 to retrieve all at once. 1119 The names and data organization SHOULD reflect persistent 1120 information, such as the name of a protocol. The name of the working 1121 group SHOULD NOT be used because this may change over time. 1123 A mandatory database data definition is defined as a node that a 1124 client must provide for the database to be valid. The server is not 1125 required to provide a value. 1127 Top-level database data definitions MUST NOT be mandatory. If a 1128 mandatory node appears at the top level, it will immediately cause 1129 the database to be invalid. This can occur when the server boots or 1130 when a module is loaded dynamically at runtime. 1132 5.11. Data Types 1134 Selection of an appropriate data type (i.e., built-in type, existing 1135 derived type, or new derived type) is very subjective, and therefore 1136 few requirements can be specified on that subject. 1138 Data model designers SHOULD use the most appropriate built-in data 1139 type for the particular application. 1141 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1142 'int64') SHOULD NOT be used unless negative values are allowed for 1143 the desired semantics. 1145 5.11.1. Fixed Value Extensibility 1147 If the set of values is fixed and the data type contents are 1148 controlled by a single naming authority, then an enumeration data 1149 type SHOULD be used. 1151 leaf foo { 1152 type enumeration { 1153 enum one; 1154 enum two; 1155 } 1156 } 1158 If extensibility of enumerated values is required, then the 1159 'identityref' data type SHOULD be used instead of an enumeration or 1160 other built-in type. 1162 identity foo-type { 1163 description "Base for the extensible type"; 1164 } 1166 identity one { 1167 base f:foo-type; 1168 } 1169 identity two { 1170 base f:foo-type; 1171 } 1173 leaf foo { 1174 type identityref { 1175 base f:foo-type; 1176 } 1177 } 1179 Note that any module can declare an identity with base "foo-type" 1180 that is valid for the "foo" leaf. Identityref values are considered 1181 to be qualified names. 1183 5.11.2. Patterns and Ranges 1185 For string data types, if a machine-readable pattern can be defined 1186 for the desired semantics, then one or more pattern statements SHOULD 1187 be present. A single quoted string SHOULD be used to specify the 1188 pattern, since a double-quoted string can modify the content. 1190 The following typedef from [RFC6991] demonstrates the proper use of 1191 the "pattern" statement: 1193 typedef ipv4-address-no-zone { 1194 type inet:ipv4-address { 1195 pattern '[0-9\.]*'; 1196 } 1197 ... 1198 } 1200 For string data types, if the length of the string is required to be 1201 bounded in all implementations, then a length statement MUST be 1202 present. 1204 The following typedef from [RFC6991] demonstrates the proper use of 1205 the "length" statement: 1207 typedef yang-identifier { 1208 type string { 1209 length "1..max"; 1210 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1211 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1212 } 1213 ... 1214 } 1216 For numeric data types, if the values allowed by the intended 1217 semantics are different than those allowed by the unbounded intrinsic 1218 data type (e.g., 'int32'), then a range statement SHOULD be present. 1220 The following typedef from [RFC6991] demonstrates the proper use of 1221 the "range" statement: 1223 typedef dscp { 1224 type uint8 { 1225 range "0..63"; 1226 } 1227 ... 1228 } 1230 5.11.3. Enumerations and Bits 1232 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1233 or 'bit' SHOULD be documented. A separate description statement 1234 (within each 'enum' or 'bit' statement) SHOULD be present. 1236 leaf foo { 1237 // INCORRECT 1238 type enumeration { 1239 enum one; 1240 enum two; 1241 } 1242 description 1243 "The foo enum... 1244 one: The first enum 1245 two: The second enum"; 1246 } 1248 leaf foo { 1249 // CORRECT 1250 type enumeration { 1251 enum one { 1252 description "The first enum"; 1253 } 1254 enum two { 1255 description "The second enum"; 1256 } 1257 } 1258 description 1259 "The foo enum... "; 1260 } 1262 5.11.4. Union Types 1264 The YANG "union" type is evaluated by testing a value against each 1265 member type in the union. The first type definition that accepts a 1266 value as valid is the member type used. In general, member types 1267 SHOULD be ordered from most restrictive to least restrictive types. 1269 In the following example, the "enumeration" type will never be 1270 matched because the preceding "string" type will match everything. 1272 Incorrect: 1274 type union { 1275 type string; 1276 type enumeration { 1277 enum up; 1278 enum down; 1279 } 1280 } 1282 Correct: 1284 type union { 1285 type enumeration { 1286 enum up; 1287 enum down; 1288 } 1289 type string; 1290 } 1292 It is possible for different member types to match, depending on the 1293 input encoding format. In XML, all values are passed as string 1294 nodes, but in JSON there are different value types for numbers, 1295 booleans, and strings. 1297 In the following example, a JSON numeric value will always be matched 1298 by the "int32" type but in XML the string value representing a number 1299 will be matched by the "string" type. The second version will match 1300 the "int32" member type no matter how the input is encoded. 1302 Incorrect: 1304 type union { 1305 type string; 1306 type int32; 1307 } 1309 Correct: 1311 type union { 1312 type int32; 1313 type string; 1314 } 1316 5.11.5. Empty and Boolean 1318 YANG provides an "empty" data type, which has one value (i.e., 1319 present). The default is "not present", which is not actually a 1320 value. When used within a list key, only one value can (and must) 1321 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1322 key leaf since it is pointless. 1324 There is really no difference between a leaf of type "empty" and a 1325 leaf-list of type "empty". Both are limited to one instance. The 1326 type "empty" SHOULD NOT be used for a leaf-list. 1328 The advantage of using type "empty" instead of type "boolean" is that 1329 the default (not present) does not take up any bytes in a 1330 representation. The disadvantage is that the client may not be sure 1331 if an empty leaf is missing because it was filtered somehow or not 1332 implemented. The client may not have a complete and accurate schema 1333 for the data returned by the server, and not be aware of the missing 1334 leaf. 1336 The YANG "boolean" data type provides two values ("true" and 1337 "false"). When used within a list key, two entries can exist for 1338 this key leaf. Default values are ignored for key leafs, but a 1339 default statement is often used for plain boolean leafs. The 1340 advantage of the "boolean" type is that the leaf or leaf-list has a 1341 clear representation for both values. The default value is usually 1342 not returned unless explicitly requested by the client, so no bytes 1343 are used in a typical representation. 1345 In general, the "boolean" data type SHOULD be used instead of the 1346 "empty" data type, as shown in the example below: 1348 Incorrect: 1350 leaf flag1 { 1351 type empty; 1352 } 1354 Correct: 1356 leaf flag2 { 1357 type boolean; 1358 default false; 1359 } 1361 5.12. Reusable Type Definitions 1363 If an appropriate derived type exists in any standard module, such as 1364 [RFC6991], then it SHOULD be used instead of defining a new derived 1365 type. 1367 If an appropriate units identifier can be associated with the desired 1368 semantics, then a units statement SHOULD be present. 1370 If an appropriate default value can be associated with the desired 1371 semantics, then a default statement SHOULD be present. 1373 If a significant number of derived types are defined, and it is 1374 anticipated that these data types will be reused by multiple modules, 1375 then these derived types SHOULD be contained in a separate module or 1376 submodule, to allow easier reuse without unnecessary coupling. 1378 The description statement MUST be present. 1380 If the type definition semantics are defined in an external document 1381 (other than another YANG module indicated by an import statement), 1382 then the reference statement MUST be present. 1384 5.13. Reusable Groupings 1386 A reusable grouping is a YANG grouping that can be imported by 1387 another module, and is intended for use by other modules. This is 1388 not the same as a grouping that is used within the module it is 1389 defined, but happens to be exportable to another module because it is 1390 defined at the top-level of the YANG module. 1392 The following guidelines apply to reusable groupings, in order to 1393 make them as robust as possible: 1395 o Clearly identify the purpose of the grouping in the "description" 1396 statement. 1398 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1399 output, notification, config=true data nodes, and all data nodes). 1400 Clearly identify which XPath contexts are applicable or excluded 1401 for the grouping. 1403 o Do not reference data outside the grouping in any "path", "must", 1404 or "when" statements. 1406 o Do not include a "default" sub-statement on a leaf or choice 1407 unless the value applies on all possible contexts. 1409 o Do not include a "config" sub-statement on a data node unless the 1410 value applies on all possible contexts. 1412 o Clearly identify any external dependencies in the grouping 1413 "description" statement, such as nodes referenced by absolute path 1414 from a "path", "must", or "when" statement. 1416 5.14. Data Definitions 1418 The description statement MUST be present in the following YANG 1419 statements: 1421 o anyxml 1423 o augment 1425 o choice 1426 o container 1428 o extension 1430 o feature 1432 o grouping 1434 o identity 1436 o leaf 1438 o leaf-list 1440 o list 1442 o notification 1444 o rpc 1446 o typedef 1448 If the data definition semantics are defined in an external document, 1449 (other than another YANG module indicated by an import statement), 1450 then a reference statement MUST be present. 1452 The 'anyxml' construct may be useful to represent an HTML banner 1453 containing markup elements, such as '<b>' and '</b>', and 1454 MAY be used in such cases. However, this construct SHOULD NOT be 1455 used if other YANG data node types can be used instead to represent 1456 the desired syntax and semantics. 1458 It has been found that the 'anyxml' statement is not implemented 1459 consistently across all servers. It is possible that mixed mode XML 1460 will not be supported, or configuration anyxml nodes will not 1461 supported. 1463 If there are referential integrity constraints associated with the 1464 desired semantics that can be represented with XPath, then one or 1465 more 'must' statements SHOULD be present. 1467 For list and leaf-list data definitions, if the number of possible 1468 instances is required to be bounded for all implementations, then the 1469 max-elements statements SHOULD be present. 1471 If any 'must' or 'when' statements are used within the data 1472 definition, then the data definition description statement SHOULD 1473 describe the purpose of each one. 1475 The "choice" statement is allowed to be directly present within a 1476 "case" statement in YANG 1.1. This needs to be considered carefully. 1477 Consider simply including the nested "choice" as additional "case" 1478 statements within the parent "choice" statement. Note that the 1479 "mandatory" and "default" statements within a nested "choice" 1480 statement only apply if the "case" containing the nested "choice" 1481 statement is first selected. 1483 5.14.1. Non-Presence Containers 1485 A non-presence container is used to organize data into specific 1486 subtrees. It is not intended to have semantics within the data model 1487 beyond this purpose, although YANG allows it (e.g., "must" statement 1488 within the non-presence container). 1490 Example using container wrappers: 1492 container top { 1493 container foos { 1494 list foo { ... } 1495 } 1496 container bars { 1497 list bar { ... } 1498 } 1499 } 1501 Example without container wrappers: 1503 container top { 1504 list foo { ... } 1505 list bar { ... } 1506 } 1508 Use of non-presence containers to organize data is a subjective 1509 matter similar to use of sub-directories in a file system. The 1510 NETCONF and RESTCONF protocols do not currently support the ability 1511 to delete all list (or leaf-list) entries at once. This deficiency 1512 is sometimes avoided by use of a parent container (i.e., deleting the 1513 container also removes all child entries). 1515 5.14.2. Top-Level Data Nodes 1517 Use of top-level objects needs to be considered carefully 1519 -top-level siblings are not ordered -top-level siblings not are not 1520 static, and depends on the modules that are loaded 1521 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1522 treated as a content-match node for all top-level-siblings 1524 o a top-level list with many instances may impact performance 1526 5.15. Operation Definitions 1528 If the operation semantics are defined in an external document (other 1529 than another YANG module indicated by an import statement), then a 1530 reference statement MUST be present. 1532 If the operation impacts system behavior in some way, it SHOULD be 1533 mentioned in the description statement. 1535 If the operation is potentially harmful to system behavior in some 1536 way, it MUST be mentioned in the Security Considerations section of 1537 the document. 1539 5.16. Notification Definitions 1541 The description statement MUST be present. 1543 If the notification semantics are defined in an external document 1544 (other than another YANG module indicated by an import statement), 1545 then a reference statement MUST be present. 1547 If the notification refers to a specific resource instance, then this 1548 instance SHOULD be identified in the notification data. This is 1549 usually done by including 'leafref' leaf nodes with the key leaf 1550 values for the resource instance. For example: 1552 notification interface-up { 1553 description "Sent when an interface is activated."; 1554 leaf name { 1555 type leafref { 1556 path "/if:interfaces/if:interface/if:name"; 1557 } 1558 } 1559 } 1561 Note that there are no formal YANG statements to identify any data 1562 node resources associated with a notification. The description 1563 statement for the notification SHOULD specify if and how the 1564 notification identifies any data node resources associated with the 1565 specific event. 1567 5.17. Feature Definitions 1569 The YANG "feature" statement is used to define a label for a set of 1570 optional functionality within a module. The "if-feature" statement 1571 is used in the YANG statements associated with a feature. 1573 The set of YANG features available in a module should be considered 1574 carefully. The description-stmt within a feature-stmt MUST specify 1575 any interactions with other features. 1577 If there is a large set of objects associated with a YANG feature, 1578 then consider moving those objects to a separate module, instead of 1579 using a YANG feature. Note that the set of features within a module 1580 is easily discovered by the reader, but the set of related modules 1581 within the entire YANG library is not as easy to identity. Module 1582 names with a common prefix can help readers identity the set of 1583 related modules, but this assumes the reader will have discovered and 1584 installed all the relevant modules. 1586 Another consideration for deciding whether to create a new module or 1587 add a YANG feature is the stability of the module in question. It 1588 may be desirable to have a stable base module that is not changed 1589 frequently. If new functionality is placed in a separate module, 1590 then the base module does not need to be republished. If it is 1591 designed as a YANG feature then the module will need to be 1592 republished. 1594 If one feature requires implementation of another feature, then an 1595 "if-feature" statement SHOULD be used in the dependent "feature" 1596 statement. 1598 For example, feature2 requires implementation of feature1: 1600 feature feature1 { 1601 description "Some protocol feature"; 1602 } 1604 feature feature2 { 1605 if-feature "feature1"; 1606 description "Another protocol feature"; 1607 } 1609 5.18. YANG Data Node Constraints 1611 5.18.1. Controlling Quantity 1613 The "min-elements" and "max-elements" statements can be use to 1614 control how many list or leaf-list instances are required for a 1615 particular data node. YANG constraint statements SHOULD be used to 1616 identify conditions that apply to all implementations of the data 1617 model. If platform-specific limitations (e.g., the "max-elements" 1618 supported for a particular list) are relevant to operations, then a 1619 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1620 used to identify the limit. 1622 5.18.2. must vs. when 1624 The "must" and "when" YANG statements are used to provide cross- 1625 object referential tests. They have very different behavior. The 1626 "when" statement causes data node instances to be silently deleted as 1627 soon as the condition becomes false. A false "when" expression is 1628 not considered to be an error. 1630 The "when" statement SHOULD be used together with the "augment" or 1631 "uses" statements to achieve conditional model composition. The 1632 condition SHOULD be based on static properties of the augmented entry 1633 (e.g., list key leafs). 1635 The "must" statement causes a datastore validation error if the 1636 condition is false. This statement SHOULD be used for enforcing 1637 parameter value restrictions that involve more than one data node 1638 (e.g., end-time parameter must be after the start-time parameter). 1640 5.19. Augment Statements 1642 The YANG "augment" statement is used to define a set of data 1643 definition statements that will be added as child nodes of a target 1644 data node. The module namespace for these data nodes will be the 1645 augmenting module, not the augmented module. 1647 A top-level "augment" statement SHOULD NOT be used if the target data 1648 node is in the same module or submodule as the evaluated "augment" 1649 statement. The data definition statements SHOULD be added inline 1650 instead. 1652 5.19.1. Conditional Augment Statements 1654 The "augment" statement is often used together with the "when" 1655 statement and/or "if-feature" statement to make the augmentation 1656 conditional on some portion of the data model. 1658 The following example from [RFC7223] shows how a conditional 1659 container called "ethernet" is added to the "interface" list only for 1660 entries of the type "ethernetCsmacd". 1662 augment "/if:interfaces/if:interface" { 1663 when "if:type = 'ianaift:ethernetCsmacd'"; 1665 container ethernet { 1666 leaf duplex { 1667 ... 1668 } 1669 } 1670 } 1672 5.19.2. Conditionally Mandatory Data Definition Statements 1674 YANG has very specific rules about how configuration data can be 1675 updated in new releases of a module. These rules allow an "old 1676 client" to continue interoperating with a "new server". 1678 If data nodes are added to an existing entry, the old client MUST NOT 1679 be required to provide any mandatory parameters that were not in the 1680 original module definition. 1682 It is possible to add conditional augment statements such that the 1683 old client would not know about the new condition, and would not 1684 specify the new condition. The conditional augment statement can 1685 contain mandatory objects only if the condition is false unless 1686 explicitly requested by the client. 1688 Only a conditional augment statement that uses the "when" statement 1689 form of condition can be used in this manner. The YANG features 1690 enabled on the server cannot be controlled by the client in any way, 1691 so it is not safe to add mandatory augmenting data nodes based on the 1692 "if-feature" statement. 1694 The XPath "when" statement condition MUST NOT reference data outside 1695 of target data node because the client does not have any control over 1696 this external data. 1698 In the following dummy example, it is OK to augment the "interface" 1699 entry with "mandatory-leaf" because the augmentation depends on 1700 support for "some-new-iftype". The old client does not know about 1701 this type so it would never select this type, and therefore not be 1702 adding a mandatory data node. 1704 module example-module { 1705 namespace "http://example.com/ns/example-module"; 1706 prefix mymod; 1708 import iana-if-type { prefix iana; } 1709 import ietf-interfaces { prefix if; } 1711 identity some-new-iftype { 1712 base iana:iana-interface-type; 1713 } 1715 augment "/if:interfaces/if:interface" { 1716 when "if:type = 'mymod:some-new-iftype'"; 1718 leaf mandatory-leaf { 1719 mandatory true; 1720 ... 1721 } 1722 } 1723 } 1725 Note that this practice is safe only for creating data resources. It 1726 is not safe for replacing or modifying resources if the client does 1727 not know about the new condition. The YANG data model MUST be 1728 packaged in a way that requires the client to be aware of the 1729 mandatory data nodes if it is aware of the condition for this data. 1730 In the example above, the "some-new-iftype" identity is defined in 1731 the same module as the "mandatory-leaf" data definition statement. 1733 This practice is not safe for identities defined in a common module 1734 such as "iana-if-type" because the client is not required to know 1735 about "my-module" just because it knows about the "iana-if-type" 1736 module. 1738 5.20. Deviation Statements 1740 The YANG "deviation" statement cannot appear in IETF YANG modules, 1741 but it can be useful for documenting server capabilities. Deviation 1742 statements are not reusable and typically not shared across all 1743 platforms. 1745 There are several reasons that deviations might be needed in an 1746 implementation, e.g., an object cannot be supported on all platforms, 1747 or feature delivery is done in multiple development phases. 1748 Deviation statements can also be used to add annotations to a module, 1749 which does not affect the conformance requirements for the module. 1751 It is suggested that deviation statements be defined in separate 1752 modules from regular YANG definitions. This allows the deviations to 1753 be platform-specific and/or temporary. 1755 The order that deviation statements are evaluated can affect the 1756 result. Therefore multiple deviation statements in the same module, 1757 for the same target object, SHOULD NOT be used. 1759 The "max-elements" statement is intended to describe an architectural 1760 limit to the number of list entries. It is not intended to describe 1761 platform limitations. It is better to use a "deviation" statement 1762 for the platforms that have a hard resource limit. 1764 Example documenting platform resource limits: 1766 Wrong: (max-elements in the list itself) 1768 container backups { 1769 list backup { 1770 ... 1771 max-elements 10; 1772 ... 1773 } 1774 } 1776 Correct: (max-elements in a deviation) 1778 deviation /bk:backups/bk:backup { 1779 deviate add { 1780 max-elements 10; 1781 } 1782 } 1784 5.21. Extension Statements 1786 The YANG "extension" statement is used to specify external 1787 definitions. This appears in the YANG syntax as an 1788 "unknown-statement". Usage of extension statements in a published 1789 module needs to be considered carefully. 1791 The following guidelines apply to the usage of YANG extensions: 1793 o The semantics of the extension MUST NOT contradict any YANG 1794 statements. Extensions can add semantics not covered by the 1795 normal YANG statements. 1797 o The module containing the extension statement MUST clearly 1798 identify the conformance requirements for the extension. It 1799 should be clear whether all implementations of the YANG module 1800 containing the extension need to also implement the extension. If 1801 not, identify what conditions apply that would require 1802 implementation of the extension. 1804 o The extension MUST clearly identify where it can be used within 1805 other YANG statements. 1807 o The extension MUST clearly identify if YANG statements or other 1808 extensions are allowed or required within the extension as sub- 1809 statements. 1811 5.22. Data Correlation 1813 Data can be correlated in various ways, using common data types, 1814 common data naming, and common data organization. There are several 1815 ways to extend the functionality of a module, based on the degree of 1816 coupling between the old and new functionality: 1818 o inline: update the module with new protocol-accessible objects. 1819 The naming and data organization of the original objects is used. 1820 The new objects are in the original module namespace. 1822 o augment: create a new module with new protocol-accessible objects 1823 that augment the original data structure. The naming and data 1824 organization of the original objects is used. The new objects are 1825 in the new module namespace. 1827 o mirror: create new objects in a new module or the original module, 1828 except use new a naming scheme and data location. The naming can 1829 be coupled in different ways. Tight coupling is achieved with a 1830 "leafref" data type, with the "require-instance" sub-statement set 1831 to "true". This method SHOULD be used. 1833 If the new data instances are not limited to the values in use in the 1834 original data structure, then the "require-instance" sub-statement 1835 MUST be set to "false". Loose coupling is achieved by using key 1836 leafs with the same data type as the original data structure. This 1837 has the same semantics as setting the "require-instance" sub- 1838 statement to "false". 1840 It is sometimes useful to separate configuration and operational 1841 data, so that they do not not even share the exact same naming 1842 characteristics. The correlation between configuration the 1843 operational data that is affected by changes in configuration is a 1844 complex problem. There may not be a simple 1:1 relationship between 1845 a configuration data node and an operational data node. Further work 1846 is needed in YANG to clarify this relationship. Protocol work may 1847 also be needed to allow a client to retrieve this type of information 1848 from a server. At this time the best practice is to clearly document 1849 any relationship to other data structures in the "description" 1850 statement. 1852 5.23. Operational Data 1854 In YANG, any data that has a "config" statement value of "false" 1855 could be considered operational data. The relationship between 1856 configuration (i.e., "config" statement has a value of "true") and 1857 operational data can be complex. 1859 One challenge for client developers is determining if the configured 1860 value is being used, which requires the developer to know which 1861 operational data parameters are associated with the particular 1862 configuration object(s). 1864 If possible, operational data SHOULD be combined with its associated 1865 configuration data. This prevents duplication of key leafs and 1866 ancestor nodes. It also prevents race conditions for retrieval of 1867 dynamic entries, and allows configuration and operational data to be 1868 retrieved together with minimal message overhead. 1870 Not preferred: 1872 list foo { 1873 ... 1874 } 1876 list foo-state { 1877 config false; 1878 ... 1879 } 1881 Preferred: 1883 list foo { 1884 container foo-state { 1885 config false; 1886 ... 1887 } 1888 } 1890 If it is not possible to combine configuration and operational data, 1891 then the keys used to represent list entries SHOULD be the same type. 1892 The "leafref" data type SHOULD be used in operational data for key 1893 leafs that have corresponding configuration instances. The 1894 "require-instance" statement MAY be set to "false" (in YANG 1.1 1895 modules only) to indicate instances are allowed in the operational 1896 state that do not exist in the associated configuration data. 1898 The following example shows the use of the "leafref" data type: 1900 Not preferred: 1902 list foo { 1903 key name; 1904 leaf name { 1905 type string; 1906 } 1907 ... 1908 } 1910 list foo-state { 1911 key name; 1912 config false; 1913 leaf name { 1914 type string; 1915 } 1916 ... 1917 } 1919 Preferred: 1921 list foo { 1922 key name; 1923 leaf name { 1924 type string; 1925 } 1926 ... 1927 } 1929 list foo-state { 1930 key name; 1931 config false; 1932 leaf name { 1933 type leafref { 1934 path "/foo/name"; 1935 require-instance false; 1936 } 1937 } 1938 ... 1939 } 1941 In the simplest use-cases, there is no interaction between 1942 configuration and operational data. For example, the arbitrary 1943 administrative name or sequence number assigned to an access control 1944 rule. The configured value is always the value that is being used by 1945 the system. 1947 However, some configuration parameters interact with routing and 1948 other signalling protocols, such that the operational value in use by 1949 the system may not be the same as the configured value. Other 1950 parameters specify the desired state, but environmental and other 1951 factors can cause the actual state to be different. 1953 For example a "temperature" configuration setting only represents the 1954 desired temperature. An operational data parameter is needed that 1955 reports the actual temperature in order to determine if the cooling 1956 system is operating correctly. YANG has no mechanism other than the 1957 "description" statement to associate the desired temperature and the 1958 actual temperature. 1960 Careful consideration needs to be given to the location of 1961 operational data. It can either be located within the configuration 1962 subtree for which it applies, or it can be located outside the 1963 particular configuration subtree. Placing operational data within 1964 the configuration subtree is appropriate if the operational values 1965 can only exist if the configuration exists. Placing operational data 1966 outside the configuration subtree is appropriate if the operational 1967 values can exist without corresponding configuration (e.g., system 1968 generated interfaces). 1970 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1971 are an example of a complex relationship between configuration and 1972 operational data. The operational values can include interface 1973 entries that have been discovered or initialized by the system. An 1974 interface may be in use that has not been configured at all. 1975 Therefore, the operational data for an interface cannot be located 1976 within the configuration for that same interface. 1978 Sometimes the configured value represents some sort of procedure to 1979 be followed, in which the system will select an actual value, based 1980 on protocol negotiation. In this case it is RECOMMENDED to have a 1981 separate config false value to represented the resulting state. For 1982 instance: 1984 leaf duplex-admin-mode { 1985 type enumeration { 1986 enum auto; 1987 enum half; 1988 enum full; 1989 } 1990 } 1992 leaf duplex-oper-mode { 1993 config false; 1994 type enumeration { 1995 enum half; 1996 enum full; 1997 } 1998 } 2000 For example a "duplex" mode configuration may be "auto" to auto- 2001 negotiate the actual value to be used. The operational parameter 2002 will never contain the value "auto". It will always contain the 2003 result of the auto-negotiation, such as "half" or "full". This is 2004 just one way in which the configuration data model is not exactly the 2005 same as the operational data model. Another is if the detailed 2006 properties of the data are different for configured vs. learned 2007 entries. 2009 If all the data model properties are aligned between configuration 2010 and operational data, then it can be useful to define the 2011 configuration parameters within a grouping, and then replicate that 2012 grouping within the operational data portion of the data model. 2014 grouping parms { 2015 // do not use config-stmt in any of the nodes 2016 // placed in this grouping 2017 } 2019 container foo { 2020 uses parms; // these are all config=true by default 2021 state { 2022 config false; // only exists if foo config exists 2023 uses parms; 2024 } 2025 } 2027 Note that this mechanism can also be used if the configuration and 2028 operational data are in separate sub-trees: 2030 container bar { // bar config can exist without bar-state 2031 config true; 2032 uses parms; 2033 } 2035 container bar-state { // bar-state can exist without bar 2036 config false; 2037 uses parms; 2038 } 2040 The need to replicate objects or define different operational data 2041 objects depends on the data model. It is not possible to define one 2042 approach that will be optimal for all data models. Designers SHOULD 2043 describe the relationship in detail between configuration objects and 2044 any associated operational data objects. The "description" 2045 statements for both the configuration and the operational data SHOULD 2046 be used for this purpose. 2048 5.24. Performance Considerations 2050 It is generally likely that certain YANG statements require more 2051 runtime resources than other statements. Although there are no 2052 performance requirements for YANG validation, the following 2053 information MAY be considered when designing YANG data models: 2055 o Lists are generally more expensive than containers 2057 o "when-stmt" evaluation is generally more expensive than 2058 "if-feature" or "choice" statements 2060 o "must" statement is generally more expensive than "min-entries", 2061 "max-entries", "mandatory", or "unique" statements 2063 o "identityref" leafs are generally more expensive than 2064 "enumeration" leafs 2066 o "leafref" and "instance-identifier" types with "require-instance" 2067 set to true are generally more expensive than if 2068 "require-instance" is set to false 2070 5.25. Open Systems Considerations 2072 A YANG module MUST NOT be designed such that the set of modules found 2073 on a server implementation can be predetermined in advance. Only the 2074 modules imported by a particular module can be assumed to be present 2075 in an implementation. An open system MAY include any combination of 2076 YANG modules. 2078 5.26. YANG 1.1 Guidelines 2080 The set of YANG 1.1 guidelines will grow as operational experience is 2081 gained with the new language features. This section contains an 2082 initial set of guidelines. 2084 5.26.1. Importing Multiple Revisions 2086 Standard modules SHOULD NOT import multiple revisions of the same 2087 module into a module. This MAY be done if the authors can 2088 demonstrate that the "avoided" definitions from the most recent of 2089 the multiple revisions are somehow broken or harmful to 2090 interoperability. 2092 5.26.2. Using Feature Logic 2094 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2095 "description" statement SHOULD describe the "if-feature" logic in 2096 text, to help readers understand the module. 2098 YANG features SHOULD be used instead of the "when" statement, if 2099 possible. Features are advertised by the server and objects 2100 conditional by if-feature are conceptually grouped together. There 2101 is no such commonality supported for "when" statements. 2103 Features generally require less server implementation complexity and 2104 runtime resources than objects that use "when" statements. Features 2105 are generally static (i.e., set when module is loaded and not changed 2106 at runtime). However every client edit might cause a "when" 2107 statement result to change. 2109 5.26.3. anyxml vs. anydata 2111 The "anyxml" statement MUST NOT be used to represent a conceptual 2112 subtree of YANG data nodes. The "anydata" statement MUST be used for 2113 this purpose. 2115 5.26.4. action vs. rpc 2117 The use of "action" statements or "rpc" statements is a subjective 2118 design decision. RPC operations are not associated with any 2119 particular data node. Actions are associated with a specific data 2120 node definition. An "action" statement SHOULD be used if the 2121 protocol operation is specific to a subset of all data nodes instead 2122 of all possible data nodes. 2124 The same action name MAY be used in different definitions within 2125 different data node. For example, a "reset" action defined with a 2126 data node definition for an interface might have different parameters 2127 than for a power supply or a VLAN. The same action name SHOULD be 2128 used to represent similar semantics. 2130 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2131 parameter access control for RPC operations. The user is given 2132 permission (or not) to invoke the RPC operation with any parameters. 2133 For example, if each client is only allowed to reset their own 2134 interface, then NACM cannot be used. 2136 For example, NACM cannot enforce access access control based on the 2137 value of the "interface" parameter, only the "reset" operation 2138 itself: 2140 rpc reset { 2141 input { 2142 leaf interface { 2143 type if:interface-ref; 2144 mandatory true; 2145 description "The interface to reset."; 2146 } 2147 } 2148 } 2150 However, NACM can enforce access access control for individual 2151 interface instances, using a "reset" action, If the user does not 2152 have read access to the specific "interface" instance, then it cannot 2153 invoke the "reset" action for that interface instance: 2155 container interfaces { 2156 list interface { 2157 ... 2158 action reset { } 2159 } 2160 } 2162 5.27. Updating YANG Modules (Published vs. Unpublished) 2164 YANG modules can change over time. Typically, new data model 2165 definitions are needed to support new features. YANG update rules 2166 defined in section 11 of [RFC7950] MUST be followed for published 2167 modules. They MAY be followed for unpublished modules. 2169 The YANG update rules only apply to published module revisions. Each 2170 organization will have their own way to identify published work which 2171 is considered to be stable, and unpublished work which is considered 2172 to be unstable. For example, in the IETF, the RFC document is used 2173 for published work, and the Internet-Draft is used for unpublished 2174 work. 2176 6. IANA Considerations 2178 -- RFC Ed: These registries need to be updated to reference this 2179 RFC instead of RFC 6087 for the ietf-template module, and 2180 remove this note. 2182 This document registers one URI in the IETF XML registry [RFC3688]. 2184 The following registration has been made in [RFC6087] and updated by 2185 this document. 2187 URI: urn:ietf:params:xml:ns:yang:ietf-template 2189 Registrant Contact: The NETMOD WG of the IETF. 2191 XML: N/A, the requested URI is an XML namespace. 2193 The following assignment has been made in [RFC6087] and updated by 2194 this document in the YANG Module Names Registry, or the YANG module 2195 template in Appendix C. 2197 +-----------+-------------------------------------------+ 2198 | Field | Value | 2199 +-----------+-------------------------------------------+ 2200 | Name | ietf-template | 2201 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2202 | Prefix | temp | 2203 | Reference | RFC XXXX | 2204 +-----------+-------------------------------------------+ 2206 YANG Registry Assignment 2208 7. Security Considerations 2210 This document defines documentation guidelines for NETCONF or 2211 RESTCONF content defined with the YANG data modeling language. The 2212 guidelines for how to write a Security Considerations section for a 2213 YANG module are defined in the online document 2215 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2216 yang-security-guidelines 2218 This document does not introduce any new or increased security risks 2219 into the management system. 2221 The following section contains the security considerations template 2222 dated 2010-06-16. Be sure to check the webpage at the URL listed 2223 above in case there is a more recent version available. 2225 Each specification that defines one or more YANG modules MUST contain 2226 a section that discusses security considerations relevant to those 2227 modules. This section MUST be patterned after the latest approved 2228 template (available at 2230 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2232 In particular, writable data nodes that could be especially 2233 disruptive if abused MUST be explicitly listed by name and the 2234 associated security risks MUST be spelled out. 2236 Similarly, readable data nodes that contain especially sensitive 2237 information or that raise significant privacy concerns MUST be 2238 explicitly listed by name and the reasons for the sensitivity/privacy 2239 concerns MUST be explained. 2241 Further, if new RPC operations have been defined, then the security 2242 considerations of each new RPC operation MUST be explained. 2244 7.1. Security Considerations Section Template 2246 X. Security Considerations 2248 The YANG module defined in this memo is designed to be accessed via 2249 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2250 secure transport layer and the mandatory-to-implement secure 2251 transport is SSH [RFC6242]. 2253 -- if you have any writable data nodes (those are all the 2254 -- "config true" nodes, and remember, that is the default) 2255 -- describe their specific sensitivity or vulnerability. 2257 There are a number of data nodes defined in this YANG module which 2258 are writable/creatable/deletable (i.e., config true, which is the 2259 default). These data nodes may be considered sensitive or vulnerable 2260 in some network environments. Write operations (e.g., edit-config) 2261 to these data nodes without proper protection can have a negative 2262 effect on network operations. These are the subtrees and data nodes 2263 and their sensitivity/vulnerability: 2265 2267 -- for all YANG modules you must evaluate whether any readable data 2268 -- nodes (those are all the "config false" nodes, but also all other 2269 -- nodes, because they can also be read via operations like get or 2270 -- get-config) are sensitive or vulnerable (for instance, if they 2271 -- might reveal customer information or violate personal privacy 2272 -- laws such as those of the European Union if exposed to 2273 -- unauthorized parties) 2275 Some of the readable data nodes in this YANG module may be considered 2276 sensitive or vulnerable in some network environments. It is thus 2277 important to control read access (e.g., via get, get-config, or 2278 notification) to these data nodes. These are the subtrees and data 2279 nodes and their sensitivity/vulnerability: 2281 2283 -- if your YANG module has defined any rpc operations 2284 -- describe their specific sensitivity or vulnerability. 2286 Some of the RPC operations in this YANG module may be considered 2287 sensitive or vulnerable in some network environments. It is thus 2288 important to control access to these operations. These are the 2289 operations and their sensitivity/vulnerability: 2291 2293 8. Acknowledgments 2295 The structure and contents of this document are adapted from 2296 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2298 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2299 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 2300 contributions to this document. 2302 9. Changes Since RFC 6087 2304 The following changes have been made to the guidelines published in 2305 [RFC6087]: 2307 o Updated NETCONF reference from RFC 4741 to RFC 6241 2309 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2311 o Updated YANG Types reference from RFC 6021 to RFC 6991 2313 o Updated obsolete URLs for IETF resources 2315 o Changed top-level data node guideline 2317 o Clarified XPath usage for a literal value representing a YANG 2318 identity 2320 o Clarified XPath usage for a when-stmt 2322 o Clarified XPath usage for 'proceeding-sibling' and 2323 'following-sibling' axes 2325 o Added terminology guidelines 2327 o Added YANG tree diagram definition and guideline 2329 o Updated XPath guidelines for type conversions and function library 2330 usage. 2332 o Updated data types section 2334 o Updated notifications section 2336 o Clarified conditional key leaf nodes 2338 o Clarify usage of 'uint64' and 'int64' data types 2340 o Added text on YANG feature usage 2342 o Added Identifier Naming Conventions 2344 o Clarified use of mandatory nodes with conditional augmentations 2346 o Clarified namespace and domain conventions for example modules 2348 o Clarified conventions for identifying code components 2349 o Added YANG 1.1 guidelines 2351 o Added Data Model Constraints section 2353 o Added mention of RESTCONF protocol 2355 10. References 2357 10.1. Normative References 2359 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2360 Requirement Levels", BCP 14, RFC 2119, March 1997. 2362 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2363 January 2004. 2365 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2366 Resource Identifier (URI): Generic Syntax", STD 66, 2367 RFC 3986, January 2005. 2369 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2370 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2372 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2373 Network Configuration Protocol (NETCONF)", RFC 6020, 2374 October 2010. 2376 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2377 July 2013. 2379 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2380 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2381 . 2383 [W3C.REC-xpath-19991116] 2384 Clark, J. and S. DeRose, "XML Path Language (XPath) 2385 Version 1.0", World Wide Web Consortium 2386 Recommendation REC-xpath-19991116, November 1999, 2387 . 2389 10.2. Informative References 2391 [I-D.ietf-netconf-restconf] 2392 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2393 Protocol", draft-ietf-netconf-restconf-17 (work in 2394 progress), September 2016. 2396 [RFC-STYLE] 2397 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2398 Style", September 2009, 2399 . 2401 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2402 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2403 . 2405 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2406 Documents", BCP 111, RFC 4181, September 2005. 2408 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2409 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2410 May 2008. 2412 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2413 Data Model Documents", RFC 6087, January 2011. 2415 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2416 and A. Bierman, Ed., "Network Configuration Protocol 2417 (NETCONF)", RFC 6241, June 2011. 2419 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2420 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2421 . 2423 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2424 Protocol (NETCONF) Access Control Model", RFC 6536, 2425 March 2012. 2427 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2428 Management", RFC 7223, May 2014. 2430 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2431 DOI 10.17487/RFC7322, September 2014, 2432 . 2434 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2435 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2436 DOI 10.17487/RFC7841, May 2016, 2437 . 2439 Appendix A. Change Log 2441 -- RFC Ed.: remove this section before publication. 2443 A.1. v08 to v09 2445 o fixed references 2447 o added mention of RESTCONF to abstract and intro 2449 o created separate section for code components 2451 o fixed document status 2453 A.2. v07 to v08 2455 o changed CODE BEGINS guideline for example modules 2457 o updated tree diagram guidelines 2459 o clarified published and unpublished terms 2461 o added section on Empty and Boolean data types 2463 o clarified how to update the revision statement 2465 o updated operational state guidelines 2467 o added 'YANG fragment' to terminology section 2469 A.3. v06 to v07 2471 o update contact statement guideline 2473 o update example modules guidelines 2475 o add guidelines on top-level data nodes 2477 o add guideline on use of NP containers 2479 o added guidelines on union types 2481 o add guideline on deviations 2483 o added section on open systems considerations 2485 o added guideline about definitions reserved for future use 2487 A.4. v05 to v06 2489 o Changed example 'my-module' to 'example-module' 2491 o Added section Updating YANG Modules (Published vs. Unpublished) 2493 o Added Example Modules section 2495 o Added "" convention for full example modules 2497 o Added section on using action vs. rpc 2499 o Changed term "operational state" to "operational data" 2501 o Added section on YANG Data Node Constraints 2503 o Added guidelines on using must vs. when statements 2505 o Made ietf-foo module validate for I-D submission 2507 A.5. v04 to v05 2509 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2510 no YANG 1.1 features needed 2512 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2513 standards track documents only) 2515 o Clarified module naming conventions for normative modules, example 2516 modules, and modules from other SDOs. 2518 o Added prefix value selection guidelines 2520 o Added new section on guidelines for reusable groupings 2522 o Made header guidelines less IETF-specific 2524 o Added new section on guidelines for extension statements 2526 o Added guidelines for nested "choice" statement within a "case" 2527 statement 2529 A.6. v03 ot v04 2531 o Added sections for deviation statements and performance 2532 considerations 2534 o Added YANG 1.1 section 2536 o Updated YANG reference from 1.0 to 1.1 2538 A.7. v02 to v03 2540 o Updated draft based on github data tracker issues added by Benoit 2541 Clause (Issues 12 - 18) 2543 A.8. v01 to v02 2545 o Updated draft based on mailing list comments. 2547 A.9. v00 to v01 2549 All issues from the issue tracker have been addressed. 2551 https://github.com/netmod-wg/rfc6087bis/issues 2553 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 2554 can use an Informative reference to this RFC for tree diagrams. 2555 Updated guidelines to reference this RFC when tree diagrams are 2556 used 2558 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2559 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2560 functions 2562 o Issue 3: XPath function document order issues: Added paragraph in 2563 XPath usage section about node-set ordering for 'local-name', 2564 'namespace-uri', 'name', 'string' and 'number' functions. Also 2565 any function that implicitly converts a node-set to a string. 2567 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2568 and text in XPath usage section already has proposed text from 2569 Lada. 2571 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2572 exception and example in XPath Usage section for augmented nodes. 2574 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2575 to 'numeric and boolean expressions' 2577 o Issue 7: XPath module containment: Added sub-section on XPath 2578 wildcards 2580 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2581 section about transitioning from active to deprecated and then to 2582 obsolete. 2584 o Issue 9: resource identification in notifications: Add text to 2585 Notifications section about identifying resources and using the 2586 leafref data type. 2588 o Issue 10: single quoted strings: Added text to Data Types section 2589 about using a single-quoted string for patterns. 2591 Appendix B. Module Review Checklist 2593 This section is adapted from RFC 4181. 2595 The purpose of a YANG module review is to review the YANG module both 2596 for technical correctness and for adherence to IETF documentation 2597 requirements. The following checklist may be helpful when reviewing 2598 an Internet-Draft: 2600 o I-D Boilerplate -- verify that the draft contains the required 2601 Internet-Draft boilerplate (see 2602 http://www.ietf.org/id-info/guidelines.html), including the 2603 appropriate statement to permit publication as an RFC, and that 2604 I-D boilerplate does not contain references or section numbers. 2606 o Abstract -- verify that the abstract does not contain references, 2607 that it does not have a section number, and that its content 2608 follows the guidelines in 2609 http://www.ietf.org/id-info/guidelines.html. 2611 o Copyright Notice -- verify that the draft has the appropriate text 2612 regarding the rights that document contributers provide to the 2613 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2614 copyright notice at the beginning of the document. The IETF Trust 2615 Legal Provisions (TLP) can be found at: 2617 http://trustee.ietf.org/license-info/ 2619 o Security Considerations section -- verify that the draft uses the 2620 latest approved template from the OPS area website (http:// 2621 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2622 and that the guidelines therein have been followed. 2624 o IANA Considerations section -- this section must always be 2625 present. For each module within the document, ensure that the 2626 IANA Considerations section contains entries for the following 2627 IANA registries: 2629 XML Namespace Registry: Register the YANG module namespace. 2631 YANG Module Registry: Register the YANG module name, prefix, 2632 namespace, and RFC number, according to the rules specified 2633 in [RFC7950]. 2635 o References -- verify that the references are properly divided 2636 between normative and informative references, that RFC 2119 is 2637 included as a normative reference if the terminology defined 2638 therein is used in the document, that all references required by 2639 the boilerplate are present, that all YANG modules containing 2640 imported items are cited as normative references, and that all 2641 citations point to the most current RFCs unless there is a valid 2642 reason to do otherwise (for example, it is OK to include an 2643 informative reference to a previous version of a specification to 2644 help explain a feature included for backward compatibility). Be 2645 sure citations for all imported modules are present somewhere in 2646 the document text (outside the YANG module). 2648 o License -- verify that the draft contains the Simplified BSD 2649 License in each YANG module or submodule. Some guidelines related 2650 to this requirement are described in Section 4.1. Make sure that 2651 the correct year is used in all copyright dates. Use the approved 2652 text from the latest Trust Legal Provisions (TLP) document, which 2653 can be found at: 2655 http://trustee.ietf.org/license-info/ 2657 o Other Issues -- check for any issues mentioned in 2658 http://www.ietf.org/id-info/checklist.html that are not covered 2659 elsewhere. 2661 o Technical Content -- review the actual technical content for 2662 compliance with the guidelines in this document. The use of a 2663 YANG module compiler is recommended when checking for syntax 2664 errors. A list of freely available tools and other information 2665 can be found at: 2667 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2669 Checking for correct syntax, however, is only part of the job. 2670 It is just as important to actually read the YANG module document 2671 from the point of view of a potential implementor. It is 2672 particularly important to check that description statements are 2673 sufficiently clear and unambiguous to allow interoperable 2674 implementations to be created. 2676 Appendix C. YANG Module Template 2678 file "ietf-template@2016-03-20.yang" 2680 module ietf-template { 2682 // replace this string with a unique namespace URN value 2683 namespace 2684 "urn:ietf:params:xml:ns:yang:ietf-template"; 2686 // replace this string, and try to pick a unique prefix 2687 prefix "temp"; 2689 // import statements here: e.g., 2690 // import ietf-yang-types { prefix yang; } 2691 // import ietf-inet-types { prefix inet; } 2693 // identify the IETF working group if applicable 2694 organization 2695 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2697 // update this contact statement with your info 2698 contact 2699 "WG Web: 2700 WG List: 2702 Editor: your-name 2703 "; 2705 // replace the first sentence in this description statement. 2706 // replace the copyright notice with the most recent 2707 // version, if it has been updated since the publication 2708 // of this document 2709 description 2710 "This module defines a template for other YANG modules. 2712 Copyright (c) IETF Trust and the persons 2713 identified as authors of the code. All rights reserved. 2715 Redistribution and use in source and binary forms, with or 2716 without modification, is permitted pursuant to, and subject 2717 to the license terms contained in, the Simplified BSD License 2718 set forth in Section 4.c of the IETF Trust's Legal Provisions 2719 Relating to IETF Documents 2720 (http://trustee.ietf.org/license-info). 2722 This version of this YANG module is part of RFC XXXX; see 2723 the RFC itself for full legal notices."; 2725 // RFC Ed.: replace XXXX with actual RFC number and remove 2726 // this note 2728 reference "RFC XXXX"; 2730 // RFC Ed.: remove this note 2731 // Note: extracted from RFC XXXX 2733 // replace '2016-03-20' with the module publication date 2734 // The format is (year-month-day) 2735 revision "2016-03-20" { 2736 description "what changed in this revision"; 2737 reference "document containing this module"; 2738 } 2740 // extension statements 2742 // feature statements 2744 // identity statements 2746 // typedef statements 2748 // grouping statements 2750 // data definition statements 2752 // augment statements 2754 // rpc statements 2756 // notification statements 2758 // DO NOT put deviation statements in a published module 2760 } 2762 2764 Author's Address 2766 Andy Bierman 2767 YumaWorks 2769 Email: andy@yumaworks.com