idnits 2.17.1 draft-ietf-netmod-rfc6087bis-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 1, 2016) is 2784 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 370, but not defined == Missing Reference: 'RFC6242' is mentioned on line 2233, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-07 ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) -- 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: 2 errors (**), 0 flaws (~~), 4 warnings (==), 6 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 Intended status: Standards Track September 1, 2016 5 Expires: March 5, 2017 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-08 10 Abstract 12 This memo provides guidelines for authors and reviewers of Standards 13 Track specifications containing YANG data model modules. Applicable 14 portions may be used as a basis for reviews of other YANG data model 15 documents. Recommendations and procedures are defined, which are 16 intended to increase interoperability and usability of Network 17 Configuration Protocol (NETCONF) implementations that utilize YANG 18 data model modules. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 5, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 57 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 58 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 59 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 8 61 4. General Documentation Guidelines . . . . . . . . . . . . . . . 9 62 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9 63 4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 10 64 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 10 65 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 66 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11 67 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 12 68 4.6. Security Considerations Section . . . . . . . . . . . . . 12 69 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 13 70 4.7.1. Documents that Create a New Namespace . . . . . . . . 13 71 4.7.2. Documents that Extend an Existing Namespace . . . . . 13 72 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 13 73 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14 74 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 14 75 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15 76 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15 77 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17 79 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17 80 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18 81 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18 82 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19 83 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19 84 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20 85 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 21 87 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 22 88 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 22 89 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 23 90 5.8. Module Header, Meta, and Revision Statements . . . . . . . 24 91 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 25 92 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 26 93 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 27 94 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 27 95 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 28 96 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 29 97 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 30 98 5.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 31 99 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 32 100 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 33 101 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 33 102 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 35 103 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 35 104 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 36 105 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 36 106 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 37 107 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 37 108 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 37 109 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 38 110 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 38 111 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 38 112 5.19.2. Conditionally Mandatory Data Definition Statements . . 39 113 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 40 114 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 41 115 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 42 116 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43 117 5.24. Performance Considerations . . . . . . . . . . . . . . . . 47 118 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 47 119 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 48 120 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 48 121 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 48 122 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 48 123 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 48 124 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49 125 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 126 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 127 7.1. Security Considerations Section Template . . . . . . . . . 52 128 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 129 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55 130 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 131 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57 132 10.2. Informative References . . . . . . . . . . . . . . . . . . 58 133 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59 134 A.1. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59 135 A.2. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 59 136 A.3. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 59 137 A.4. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60 138 A.5. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 60 139 A.6. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 60 140 A.7. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61 141 A.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61 142 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 62 143 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 64 144 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 66 146 1. Introduction 148 The standardization of network configuration interfaces for use with 149 the Network Configuration Protocol [RFC6241] requires a modular set 150 of data models, which can be reused and extended over time. 152 This document defines a set of usage guidelines for Standards Track 153 documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG 154 is used to define the data structures, protocol operations, and 155 notification content used within a NETCONF server. A server that 156 supports a particular YANG module will support client NETCONF 157 operation requests, as indicated by the specific content defined in 158 the YANG module. 160 This document is similar to the Structure of Management Information 161 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 162 and structure. However, since that document was written a decade 163 after SMIv2 modules had been in use, it was published as a 'Best 164 Current Practice' (BCP). This document is not a BCP, but rather an 165 informational reference, intended to promote consistency in documents 166 containing YANG modules. 168 Many YANG constructs are defined as optional to use, such as the 169 description statement. However, in order to maximize 170 interoperability of NETCONF implementations utilizing YANG data 171 models, it is desirable to define a set of usage guidelines that may 172 require a higher level of compliance than the minimum level defined 173 in the YANG specification. 175 In addition, YANG allows constructs such as infinite length 176 identifiers and string values, or top-level mandatory nodes, that a 177 compliant server is not required to support. Only constructs that 178 all servers are required to support can be used in IETF YANG modules. 180 This document defines usage guidelines related to the NETCONF 181 operations layer and NETCONF content layer, as defined in [RFC6241]. 182 These guidelines are intended to be used by authors and reviewers to 183 improve the readability and interoperability of published YANG data 184 models. 186 Note that this document is not a YANG tutorial and the reader is 187 expected to know the YANG data modeling language before using this 188 document. 190 2. Terminology 192 2.1. Requirements Notation 194 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 195 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 196 document are to be interpreted as described in [RFC2119]. 198 RFC 2119 language is used here to express the views of the NETMOD 199 working group regarding content for YANG modules. YANG modules 200 complying with this document will treat the RFC 2119 terminology as 201 if it were describing best current practices. 203 2.2. NETCONF Terms 205 The following terms are defined in [RFC6241] and are not redefined 206 here: 208 o capabilities 210 o client 212 o operation 214 o server 216 2.3. YANG Terms 218 The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and 219 are not redefined here: 221 o data node 223 o module 225 o namespace 227 o submodule 229 o version 231 o YANG 233 o YIN 235 Note that the term 'module' may be used as a generic term for a YANG 236 module or submodule. When describing properties that are specific to 237 submodules, the term 'submodule' is used instead. 239 2.4. Terms 241 The following terms are used throughout this document: 243 o published: A stable release of a module or submodule. For example 244 the "Request for Comments" described in section 2.1 of [RFC2026] 245 is considered a stable publication. 247 o unpublished: An unstable release of a module or submodule. For 248 example the "Internet-Draft" described in section 2.2 of [RFC2026] 249 is considered an unstable publication that is a work-in-progess, 250 subject to change at any time. 252 o YANG fragment: A set of YANG statements that are not intended to 253 represent a complete YANG module or submodule. These statements 254 are not intended for actual use, except to provide an example of 255 YANG statement usage. The invalid syntax "..." is sometimes used 256 to indicate that additional YANG statements would be present in a 257 real YANG module. 259 3. YANG Tree Diagrams 261 YANG tree diagrams provide a concise representation of a YANG module 262 to help readers understand the module structure. 264 The meaning of the symbols in YANG tree diagrams is as follows: 266 o Brackets "[" and "]" enclose list keys. 268 o Abbreviations before data node names: "rw" means configuration 269 (read-write) and "ro" state data (read-only). 271 o Symbols after data node names: "?" means an optional node, "!" 272 means a presence container, and "*" denotes a list and leaf-list. 274 o Parentheses enclose choice and case nodes, and case nodes are also 275 marked with a colon (":"). 277 o Ellipsis ("...") stands for contents of subtrees that are not 278 shown. 280 4. General Documentation Guidelines 282 YANG data model modules under review are likely to be contained in 283 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 284 followed. The RFC Editor provides guidelines for authors of RFCs, 285 which are first published as Internet-Drafts. These guidelines 286 should be followed and are defined in [RFC2223] and updated in 287 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 289 The following sections MUST be present in an Internet-Draft 290 containing a module: 292 o Narrative sections 294 o Definitions section 296 o Security Considerations section 298 o IANA Considerations section 300 o References section 302 There are three usage scenarios for YANG that can appear in an 303 Internet-Draft or RFC: 305 o normative module or submodule 307 o example module or submodule 309 o example YANG fragment not part of any module or submodule 311 The guidelines in this document refer mainly to a normative complete 312 module or submodule, but may be applicable to example modules and 313 YANG fragments as well. 315 4.1. Module Copyright 317 The module description statement MUST contain a reference to the 318 latest approved IETF Trust Copyright statement, which is available 319 online at: 321 http://trustee.ietf.org/license-info/ 323 Each YANG module or submodule contained within an Internet-Draft or 324 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 326 component. 328 The "" tag SHOULD be followed by a string identifying 329 the file name specified in Section 5.2 of 330 [I-D.ietf-netmod-rfc6020bis]. The following example is for the 331 '2010-01-18' revision of the 'ietf-foo' module: 333 file "ietf-foo@2016-03-20.yang" 335 module ietf-foo { 336 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 337 prefix "foo"; 338 organization "..."; 339 contact "..."; 340 description "..."; 341 revision 2016-03-20 { 342 description "Latest revision"; 343 reference "RFC XXXX"; 344 } 345 // ... more statements 346 } 348 350 4.1.1. Example Modules 352 The convention SHOULD be used for complete example 353 modules, but not YANG fragments. This allows module extraction tools 354 to ignore partial YANG modules that are not intended to be compiled. 356 An example module SHOULD be named using the term "example", followed 357 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 359 4.2. Terminology Section 361 A terminology section MUST be present if any terms are defined in the 362 document or if any terms are imported from other documents. 364 If YANG tree diagrams are used, then a sub-section explaining the 365 YANG tree diagram syntax MUST be present, containing the following 366 text: 368 A simplified graphical representation of the data model is used in 369 this document. The meaning of the symbols in these diagrams is 370 defined in [RFCXXXX]. 372 -- RFC Editor: Replace XXXX with RFC number and remove note 374 4.3. Tree Diagrams 376 YANG tree diagrams provide a concise representation of a YANG module, 377 and SHOULD be included to help readers understand YANG module 378 structure. Tree diagrams MAY be split into sections to correspond to 379 document structure. 381 The following example shows a simple YANG tree diagram: 383 +--rw top-level-config-container 384 | +--rw config-list* [key-name] 385 | +--rw key-name string 386 | +--rw optional-parm? string 387 | +--rw mandatory-parm identityref 388 | +--ro read-only-leaf string 389 +--ro top-level-nonconfig-container 390 +--ro nonconfig-list* [name] 391 +--ro name string 392 +--ro type string 394 The 'pyang' compiler can be used to produce the tree diagram, using 395 the '-f tree' command line parameter. 397 If the YANG module is comprised of groupings only, then the tree 398 diagram SHOULD contain the groupings. The 'pyang' compiler can be 399 used to produce a tree diagram with groupings using the '-f tree 400 --tree-print-groupings" command line parameters. 402 If the YANG module contains notifications, then the tree diagram 403 SHOULD contain the notifications. If the YANG module contains RPC 404 statements, then the tree diagram SHOULD contain the RPC statements. 406 4.4. Narrative Sections 408 The narrative part MUST include an overview section that describes 409 the scope and field of application of the module(s) defined by the 410 specification and that specifies the relationship (if any) of these 411 modules to other standards, particularly to standards containing 412 other YANG modules. The narrative part SHOULD include one or more 413 sections to briefly describe the structure of the modules defined in 414 the specification. 416 If the module(s) defined by the specification imports definitions 417 from other modules (except for those defined in the 418 [I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always 419 implemented in conjunction with other modules, then those facts MUST 420 be noted in the overview section, as MUST be noted any special 421 interpretations of definitions in other modules. 423 4.5. Definitions Section 425 This section contains the module(s) defined by the specification. 426 These modules SHOULD be written using the YANG syntax defined in 427 [I-D.ietf-netmod-rfc6020bis]. YANG 1.0 [RFC6020] MAY be used if no 428 YANG 1.1 constructs or semantics are needed in the module. 430 A YIN syntax version of the module MAY also be present in the 431 document. There MAY also be other types of modules present in the 432 document, such as SMIv2, which are not affected by these guidelines. 434 Note that all YANG statements within a YANG module are considered 435 normative, if the module itself is considered normative, and not an 436 example module. The use of keywords defined in [RFC2119] apply to 437 YANG description statements in normative modules exactly as they 438 would in any other normative section. 440 Example YANG modules MUST NOT contain any normative text, including 441 any reserved words from [RFC2119]. 443 See Section 5 for guidelines on YANG usage. 445 4.6. Security Considerations Section 447 Each specification that defines one or more modules MUST contain a 448 section that discusses security considerations relevant to those 449 modules. 451 This section MUST be patterned after the latest approved template 452 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 453 yang-security-guidelines). Section 7.1 contains the security 454 considerations template dated 2013-05-08. Authors MUST check the WEB 455 page at the URL listed above in case there is a more recent version 456 available. 458 In particular: 460 o Writable data nodes that could be especially disruptive if abused 461 MUST be explicitly listed by name and the associated security 462 risks MUST be explained. 464 o Readable data nodes that contain especially sensitive information 465 or that raise significant privacy concerns MUST be explicitly 466 listed by name and the reasons for the sensitivity/privacy 467 concerns MUST be explained. 469 o Operations (i.e., YANG 'rpc' statements) that are potentially 470 harmful to system behavior or that raise significant privacy 471 concerns MUST be explicitly listed by name and the reasons for the 472 sensitivity/privacy concerns MUST be explained. 474 4.7. IANA Considerations Section 476 In order to comply with IESG policy as set forth in 477 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 478 is submitted to the IESG for publication MUST contain an IANA 479 Considerations section. The requirements for this section vary 480 depending on what actions are required of the IANA. If there are no 481 IANA considerations applicable to the document, then the IANA 482 Considerations section stating that there are no actions is removed 483 by the RFC Editor before publication. Refer to the guidelines in 484 [RFC5226] for more details. 486 4.7.1. Documents that Create a New Namespace 488 If an Internet-Draft defines a new namespace that is to be 489 administered by the IANA, then the document MUST include an IANA 490 Considerations section that specifies how the namespace is to be 491 administered. 493 Specifically, if any YANG module namespace statement value contained 494 in the document is not already registered with IANA, then a new YANG 495 Namespace registry entry MUST be requested from the IANA. The 496 [I-D.ietf-netmod-rfc6020bis] specification includes the procedure for 497 this purpose in its IANA Considerations section. 499 4.7.2. Documents that Extend an Existing Namespace 501 It is possible to extend an existing namespace using a YANG submodule 502 that belongs to an existing module already administered by IANA. In 503 this case, the document containing the main module MUST be updated to 504 use the latest revision of the submodule. 506 4.8. Reference Sections 508 For every import or include statement that appears in a module 509 contained in the specification, which identifies a module in a 510 separate document, a corresponding normative reference to that 511 document MUST appear in the Normative References section. The 512 reference MUST correspond to the specific module version actually 513 used within the specification. 515 For every normative reference statement that appears in a module 516 contained in the specification, which identifies a separate document, 517 a corresponding normative reference to that document SHOULD appear in 518 the Normative References section. The reference SHOULD correspond to 519 the specific document version actually used within the specification. 520 If the reference statement identifies an informative reference, which 521 identifies a separate document, a corresponding informative reference 522 to that document MAY appear in the Informative References section. 524 4.9. Validation Tools 526 All modules need to be validated before submission in an Internet 527 Draft. The 'pyang' YANG compiler is freely available from github: 529 https://github.com/mbj4668/pyang 531 If the 'pyang' compiler is used, then the "--ietf" command line 532 option SHOULD be used to identify any IETF guideline issues. 534 4.10. Module Extraction Tools 536 A version of 'rfcstrip' is available which will extract YANG modules 537 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 538 YANG module extraction is freely available: 540 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 542 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 544 can be extracted correctly. 546 5. YANG Usage Guidelines 548 In general, modules in IETF Standards Track specifications MUST 549 comply with all syntactic and semantic requirements of YANG 550 [I-D.ietf-netmod-rfc6020bis]. The guidelines in this section are 551 intended to supplement the YANG specification, which is intended to 552 define a minimum set of conformance requirements. 554 In order to promote interoperability and establish a set of practices 555 based on previous experience, the following sections establish usage 556 guidelines for specific YANG constructs. 558 Only guidelines that clarify or restrict the minimum conformance 559 requirements are included here. 561 5.1. Module Naming Conventions 563 Normative modules contained in Standards Track documents MUST be 564 named according to the guidelines in the IANA Considerations section 565 of [I-D.ietf-netmod-rfc6020bis]. 567 A distinctive word or acronym (e.g., protocol name or working group 568 acronym) SHOULD be used in the module name. If new definitions are 569 being defined to extend one or more existing modules, then the same 570 word or acronym should be reused, instead of creating a new one. 572 All published module names MUST be unique. For a YANG module 573 published in an RFC, this uniqueness is guaranteed by IANA. For 574 unpublished modules, the authors need to check that no other work in 575 progress is using the same module name. 577 Example modules are non-normative, and SHOULD be named with the 578 prefix "example-". 580 It is suggested that a stable prefix be selected representing the 581 entire organization. All normative YANG modules published by the 582 IETF MUST begin with the prefix "ietf-". Another standards 583 organization, such as the IEEE, might use the prefix "ieee-" for all 584 YANG modules. 586 Once a module name is published, it MUST NOT be reused, even if the 587 RFC containing the module is reclassified to 'Historic' status. A 588 module name cannot be changed in YANG, and this would be treated as a 589 a new module, not a name change. 591 5.2. Prefixes 593 All YANG definitions are scoped by the module containing the 594 definition being referenced. This allows definitions from multiple 595 modules to be used, even if the names are not unique. In the example 596 below, the identifier "foo" is used in all 3 modules: 598 module example-foo { 599 namespace "http://example.com/ns/foo"; 600 prefix f; 602 container foo; 603 } 605 module example-bar { 606 namespace "http://example.com/ns/bar"; 607 prefix b; 609 typedef foo { type uint32; } 610 } 612 module example-one { 613 namespace "http://example.com/ns/one"; 614 prefix one; 615 import example-foo { prefix f; } 616 import example-bar { prefix b; } 618 augment "/f:foo" { 619 leaf foo { type b:foo; } 620 } 621 } 623 YANG defines the following rules for prefix usage: 625 o Prefixes are never allowed for built in data types and YANG 626 keywords. 628 o A prefix MUST be used for any external statement (i.e., a 629 statement defined with the YANG "extension" statement) 631 o The proper module prefix MUST be used for all identifiers imported 632 from other modules 634 o The proper module prefix MUST be used for all identifiers included 635 from a submodule. 637 The following guidelines apply to prefix usage of the current (local) 638 module: 640 o The local module prefix SHOULD be used instead of no prefix in all 641 path expressions. 643 o The local module prefix MUST be used instead of no prefix in all 644 "default" statements for an "identityref" or "instance-identifier" 645 data type 647 o The local module prefix MAY be used for references to typedefs, 648 groupings, extensions, features, and identities defined in the 649 module. 651 Prefix values SHOULD be short, but also likely to be unique. Prefix 652 values SHOULD NOT conflict with known modules that have been 653 previously published. 655 5.3. Identifiers 657 Identifiers for all YANG identifiers in published modules MUST be 658 between 1 and 64 characters in length. These include any construct 659 specified as an 'identifier-arg-str' token in the ABNF in Section 13 660 of [I-D.ietf-netmod-rfc6020bis]. 662 5.3.1. Identifier Naming Conventions 664 Identifiers SHOULD follow a consistent naming pattern throughout the 665 module. Only lower-case letters, numbers, and dashes SHOULD be used 666 in identifier names. Upper-case characters and the underscore 667 character MAY be used if the identifier represents a well-known value 668 that uses these characters. 670 Identifiers SHOULD include complete words and/or well-known acronyms 671 or abbreviations. Child nodes within a container or list SHOULD NOT 672 replicate the parent identifier. YANG identifiers are hierarchical 673 and are only meant to be unique within the the set of sibling nodes 674 defined in the same module namespace. 676 It is permissible to use common identifiers such as "name" or "id" in 677 data definition statements, especially if these data nodes share a 678 common data type. 680 Identifiers SHOULD NOT carry any special semantics that identify data 681 modelling properties. Only YANG statements and YANG extension 682 statements are designed to convey machine readable data modelling 683 properties. For example, naming an object "config" or "state" does 684 not change whether it is configuration data or state data. Only 685 defined YANG statements or YANG extension statements can be used to 686 assign semantics in a machine readable format in YANG. 688 5.4. Defaults 690 In general, it is suggested that substatements containing very common 691 default values SHOULD NOT be present. The following substatements 692 are commonly used with the default value, which would make the module 693 difficult to read if used everywhere they are allowed. 695 +--------------+---------------+ 696 | Statement | Default Value | 697 +--------------+---------------+ 698 | config | true | 699 | mandatory | false | 700 | max-elements | unbounded | 701 | min-elements | 0 | 702 | ordered-by | system | 703 | status | current | 704 | yin-element | false | 705 +--------------+---------------+ 707 Statement Defaults 709 5.5. Conditional Statements 711 A module may be conceptually partitioned in several ways, using the 712 'if-feature' and/or 'when' statements. 714 Data model designers need to carefully consider all modularity 715 aspects, including the use of YANG conditional statements. 717 If a data definition is optional, depending on server support for a 718 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 719 be defined to indicate that the NETCONF capability is supported 720 within the data model. 722 If any notification data, or any data definition, for a non- 723 configuration data node is not mandatory, then the server may or may 724 not be required to return an instance of this data node. If any 725 conditional requirements exist for returning the data node in a 726 notification payload or retrieval request, they MUST be documented 727 somewhere. For example, a 'when' or 'if-feature' statement could 728 apply to the data node, or the conditional requirements could be 729 explained in a 'description' statement within the data node or one of 730 its ancestors (if any). 732 If any 'if-feature' statements apply to a list node, then the same 733 'if-feature' statements MUST apply to any key leaf nodes for the 734 list. There MUST NOT be any 'if-feature' statements applied to any 735 key leaf that do not also apply to the parent list node. 737 There SHOULD NOT be any 'when' statements applied to a key leaf node. 738 It is possible that a 'when' statement for an ancestor node of a key 739 leaf will have the exact node-set result as the key leaf. In such a 740 case, the 'when' statement for the key leaf is redundant and SHOULD 741 be avoided. 743 5.6. XPath Usage 745 This section describes guidelines for using the XML Path Language 746 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 748 5.6.1. XPath Evaluation Contexts 750 YANG defines 5 separate contexts for evaluation of XPath statements: 752 1) The "running" datastore: collection of all YANG configuration data 753 nodes. The document root is the conceptual container, (e.g., 754 "config" in the "edit-config" operation), which is the parent of all 755 top-level data definition statements with a "config" statement value 756 of "true". 758 2) State data + the "running" datastore: collection of all YANG data 759 nodes. The document root is the conceptual container, parent of all 760 top-level data definition statements. 762 3) Notification: an event notification document. The document root 763 is the notification element. 765 4) RPC Input: The document root is the conceptual "input" node, which 766 is the parent of all RPC input parameter definitions. 768 5) RPC Output: The document root is the conceptual "output" node, 769 which is the parent of all RPC output parameter definitions. 771 Note that these XPath contexts cannot be mixed. For example, a 772 "when" statement in a notification context cannot reference 773 configuration data. 775 notification foo { 776 leaf mtu { 777 // NOT OK because when-stmt context is this notification 778 when "/if:interfaces/if:interface[name='eth0']"; 779 type leafref { 780 // OK because path-stmt has a different context 781 path "/if:interfaces/if:interface/if:mtu"; 782 } 783 } 784 } 786 It is especially important to consider the XPath evaluation context 787 for XPath expressions defined in groupings. An XPath expression 788 defined in a grouping may not be portable, meaning it cannot be used 789 in multiple contexts and produce proper results. 791 If the XPath expressions defined in a grouping are intended for a 792 particular context, then this context SHOULD be identified in the 793 "description" statement for the grouping. 795 5.6.2. Function Library 797 The 'position' and 'last' functions SHOULD NOT be used. This applies 798 to implicit use of the 'position' function as well (e.g., 799 '//chapter[42]'). A server is only required to maintain the relative 800 XML document order of all instances of a particular user-ordered list 801 or leaf-list. The 'position' and 'last' functions MAY be used if 802 they are evaluated in a context where the context node is a user- 803 ordered 'list' or 'leaf-list'. 805 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 806 present in YANG documents so this function has no meaning. The YANG 807 compiler SHOULD return an empty string for this function. 809 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 810 Expanded names in XPath are different than YANG. A specific 811 canonical representation of a YANG expanded name does not exist. 813 The 'lang' function SHOULD NOT be used. This function does not apply 814 to YANG because there is no 'lang' attribute set with the document. 815 The YANG compiler SHOULD return 'false' for this function. 817 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 818 functions SHOULD NOT be used if the argument is a node-set. If so, 819 the function result will be determined by the document order of the 820 node-set. Since this order can be different on each server, the 821 function results can also be different. Any function call that 822 implicitly converts a node-set to a string will also have this issue. 824 The 'local-name' function SHOULD NOT be used to reference local names 825 outside of the YANG module defining the must or when expression 826 containing the 'local-name' function. Example of a local-name 827 function that should not be used: 829 /*[local-name()='foo'] 831 5.6.3. Axes 833 The 'attribute' and 'namespace' axes are not supported in YANG, and 834 MAY be empty in a NETCONF server implementation. 836 The 'preceding', and 'following' axes SHOULD NOT be used. These 837 constructs rely on XML document order within a NETCONF server 838 configuration database, which may not be supported consistently or 839 produce reliable results across implementations. Predicate 840 expressions based on static node properties (e.g., element name or 841 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 842 'preceding' and 'following' axes MAY be used if document order is not 843 relevant to the outcome of the expression (e.g., check for global 844 uniqueness of a parameter value). 846 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 847 however they MAY be used if document order is not relevant to the 848 outcome of the expression. 850 A server is only required to maintain the relative XML document order 851 of all instances of a particular user-ordered list or leaf-list. The 852 'preceding-sibling' and 'following-sibling' axes MAY be used if they 853 are evaluated in a context where the context node is a user-ordered 854 'list' or 'leaf-list'. 856 5.6.4. Types 858 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 859 be used within numeric or boolean expressions. There are boundary 860 conditions in which the translation from the YANG 64-bit type to an 861 XPath number can cause incorrect results. Specifically, an XPath 862 'double' precision floating point number cannot represent very large 863 positive or negative 64-bit numbers because it only provides a total 864 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 865 used in numeric expressions if the value can be represented with no 866 more than 53 bits of precision. 868 Data modelers need to be careful not to confuse the YANG value space 869 and the XPath value space. The data types are not the same in both, 870 and conversion between YANG and XPath data types SHOULD be considered 871 carefully. 873 Explicit XPath data type conversions MAY be used (e.g., 'string', 874 'boolean', or 'number' functions), instead of implicit XPath data 875 type conversions. 877 XPath expressions that contain a literal value representing a YANG 878 identity SHOULD always include the declared prefix of the module 879 where the identity is defined. 881 XPath expressions for 'when' statements SHOULD NOT reference the 882 context node or any descendant nodes of the context node. They MAY 883 reference descendant nodes if the 'when' statement is contained 884 within an 'augment' statement, and the referenced nodes are not 885 defined within the 'augment' statement. 887 Example: 889 augment "/rt:active-route/rt:input/rt:destination-address" { 890 when "rt:address-family='v4ur:ipv4-unicast'" { 891 description 892 "This augment is valid only for IPv4 unicast."; 893 } 894 // nodes defined here within the augment-stmt 895 // cannot be referenced in the when-stmt 896 } 898 5.6.5. Wildcards 900 It is possible to construct XPath expressions that will evaluate 901 differently when combined with several modules within a server 902 implementation, then when evaluated within the single module. This 903 is due to augmenting nodes from other modules. 905 Wildcard expansion is done within a server against all the nodes from 906 all namespaces, so it is possible for a 'must' or 'when' expression 907 that uses the '*' operator will always evaluate to false if processed 908 within a single YANG module. In such cases, the 'description' 909 statement SHOULD clarify that augmenting objects are expected to 910 match the wildcard expansion. 912 when /foo/services/*/active { 913 description 914 "No services directly defined in this module. 915 Matches objects that have augmented the services container."; 916 } 918 5.6.6. Boolean Expressions 920 The YANG "must" and "when" statements use an XPath boolean expression 921 to define the test condition for the statement. It is important to 922 specify these expressions in a way that will not cause inadvertent 923 changes in the result if the objects referenced in the expression are 924 updated in future revisions of the module. 926 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 927 to "one" or "three": 929 leaf foo1 { 930 type enumeration { 931 enum one; 932 enum two; 933 enum three; 934 } 935 } 937 leaf foo2 { 938 // INCORRECT 939 must "/f:foo1 != 'two'"; 940 type string; 941 } 943 leaf foo2 { 944 // CORRECT 945 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 946 type string; 947 } 949 In the next revision of the module, leaf "foo1" is extended with a 950 nem enum named "four": 952 leaf foo1 { 953 type enumeration { 954 enum one; 955 enum two; 956 enum three; 957 enum four; 958 } 959 } 961 Now the first XPath expression will allow the enum "four" to be 962 accepted in addition to the "one" and "three" enum values. 964 5.7. Lifecycle Management 966 The status statement MUST be present if its value is 'deprecated' or 967 'obsolete'. The status SHOULD NOT be changed from 'current' directly 968 to 'obsolete'. An object SHOULD be available for at least one year 969 with 'deprecated' status before it is changed to 'obsolete'. 971 The module or submodule name MUST NOT be changed, once the document 972 containing the module or submodule is published. 974 The module namespace URI value MUST NOT be changed, once the document 975 containing the module is published. 977 The revision-date substatement within the import statement SHOULD be 978 present if any groupings are used from the external module. 980 The revision-date substatement within the include statement SHOULD be 981 present if any groupings are used from the external submodule. 983 If submodules are used, then the document containing the main module 984 MUST be updated so that the main module revision date is equal or 985 more recent than the revision date of any submodule that is (directly 986 or indirectly) included by the main module. 988 Definitions for future use SHOULD NOT be specified in a module. Do 989 not specify placeholder objects like the "reserved" example below: 991 leaf reserved { 992 type string; 993 description 994 "This object has no purpose at this time, but a future 995 revision of this module might define a purpose 996 for this object."; 997 } 998 } 1000 5.8. Module Header, Meta, and Revision Statements 1002 For published modules, the namespace MUST be a globally unique URI, 1003 as defined in [RFC3986]. This value is usually assigned by the IANA. 1005 The organization statement MUST be present. If the module is 1006 contained in a document intended for IETF Standards Track status, 1007 then the organization SHOULD be the IETF working group chartered to 1008 write the document. For other standards organizations, a similar 1009 approach is also suggested. 1011 The contact statement MUST be present. If the module is contained in 1012 a document intended for Standards Track status, then the working 1013 group web and mailing information MUST be present, and the main 1014 document author or editor contact information SHOULD be present. If 1015 additional authors or editors exist, their contact information MAY be 1016 present. 1018 The description statement MUST be present. For modules published 1019 within IETF documents, the appropriate IETF Trust Copyright text MUST 1020 be present, as described in Section 4.1. 1022 If the module relies on information contained in other documents, 1023 which are not the same documents implied by the import statements 1024 present in the module, then these documents MUST be identified in the 1025 reference statement. 1027 A revision statement MUST be present for each published version of 1028 the module. The revision statement MUST have a reference 1029 substatement. It MUST identify the published document that contains 1030 the module. Modules are often extracted from their original 1031 documents, and it is useful for developers and operators to know how 1032 to find the original source document in a consistent manner. The 1033 revision statement MAY have a description substatement. 1035 It is not required to keep the full revision history of draft 1036 versions (e.g., modules contained within Internet-Drafts). That is, 1037 within a sequence of draft versions, only the most recent revision 1038 need be recorded in the module. However, whenever a new (i.e. 1039 changed) version is made available (e.g., via a new version of an 1040 Internet-Draft), the revision date of that new version MUST be 1041 updated to a date later than that of the previous version. 1043 5.9. Namespace Assignments 1045 It is RECOMMENDED that only valid YANG modules be included in 1046 documents, whether or not they are published yet. This allows: 1048 o the module to compile correctly instead of generating disruptive 1049 fatal errors. 1051 o early implementors to use the modules without picking a random 1052 value for the XML namespace. 1054 o early interoperability testing since independent implementations 1055 will use the same XML namespace value. 1057 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1058 provided for the namespace statement in a YANG module. A value 1059 SHOULD be selected that is not likely to collide with other YANG 1060 namespaces. Standard module names, prefixes, and URI strings already 1061 listed in the YANG Module Registry MUST NOT be used. 1063 A standard namespace statement value SHOULD have the following form: 1065 : 1067 The following URN prefix string SHOULD be used for published and 1068 unpublished YANG modules: 1070 urn:ietf:params:xml:ns:yang: 1072 The following example URNs would be valid namespace statement values 1073 for Standards Track modules: 1075 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1077 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1079 urn:ietf:params:xml:ns:yang:ietf-netconf 1081 Note that a different URN prefix string SHOULD be used for non- 1082 Standards-Track modules. The string SHOULD be selected according to 1083 the guidelines in [I-D.ietf-netmod-rfc6020bis]. 1085 The following examples are for non-Standards-Track modules. The 1086 domain "example.com" SHOULD be used in all namespace URIs for example 1087 modules. 1089 http://example.com/ns/example-interfaces 1091 http://example.com/ns/example-system 1093 5.10. Top-Level Data Definitions 1095 The top-level data organization SHOULD be considered carefully, in 1096 advance. Data model designers need to consider how the functionality 1097 for a given protocol or protocol family will grow over time. 1099 The separation of configuration data and operational data SHOULD be 1100 considered carefully. It is sometimes useful to define separate top- 1101 level containers for configuration and non-configuration data. For 1102 some existing top-level data nodes, configuration data was not in 1103 scope, so only one container representing operational data was 1104 created. 1106 The number of top-level data nodes within a module SHOULD be 1107 minimized. It is often useful to retrieve related information within 1108 a single subtree. If data is too distributed, is becomes difficult 1109 to retrieve all at once. 1111 The names and data organization SHOULD reflect persistent 1112 information, such as the name of a protocol. The name of the working 1113 group SHOULD NOT be used because this may change over time. 1115 A mandatory database data definition is defined as a node that a 1116 client must provide for the database to be valid. The server is not 1117 required to provide a value. 1119 Top-level database data definitions MUST NOT be mandatory. If a 1120 mandatory node appears at the top level, it will immediately cause 1121 the database to be invalid. This can occur when the server boots or 1122 when a module is loaded dynamically at runtime. 1124 5.11. Data Types 1126 Selection of an appropriate data type (i.e., built-in type, existing 1127 derived type, or new derived type) is very subjective, and therefore 1128 few requirements can be specified on that subject. 1130 Data model designers SHOULD use the most appropriate built-in data 1131 type for the particular application. 1133 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1134 'int64') SHOULD NOT be used unless negative values are allowed for 1135 the desired semantics. 1137 5.11.1. Fixed Value Extensibility 1139 If the set of values is fixed and the data type contents are 1140 controlled by a single naming authority, then an enumeration data 1141 type SHOULD be used. 1143 leaf foo { 1144 type enumeration { 1145 enum one; 1146 enum two; 1147 } 1148 } 1150 If extensibility of enumerated values is required, then the 1151 'identityref' data type SHOULD be used instead of an enumeration or 1152 other built-in type. 1154 identity foo-type { 1155 description "Base for the extensible type"; 1156 } 1158 identity one { 1159 base f:foo-type; 1160 } 1161 identity two { 1162 base f:foo-type; 1163 } 1165 leaf foo { 1166 type identityref { 1167 base f:foo-type; 1168 } 1169 } 1171 Note that any module can declare an identity with base "foo-type" 1172 that is valid for the "foo" leaf. Identityref values are considered 1173 to be qualified names. 1175 5.11.2. Patterns and Ranges 1177 For string data types, if a machine-readable pattern can be defined 1178 for the desired semantics, then one or more pattern statements SHOULD 1179 be present. A single quoted string SHOULD be used to specify the 1180 pattern, since a double-quoted string can modify the content. 1182 The following typedef from [RFC6991] demonstrates the proper use of 1183 the "pattern" statement: 1185 typedef ipv4-address-no-zone { 1186 type inet:ipv4-address { 1187 pattern '[0-9\.]*'; 1188 } 1189 ... 1190 } 1192 For string data types, if the length of the string is required to be 1193 bounded in all implementations, then a length statement MUST be 1194 present. 1196 The following typedef from [RFC6991] demonstrates the proper use of 1197 the "length" statement: 1199 typedef yang-identifier { 1200 type string { 1201 length "1..max"; 1202 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1203 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1204 } 1205 ... 1206 } 1208 For numeric data types, if the values allowed by the intended 1209 semantics are different than those allowed by the unbounded intrinsic 1210 data type (e.g., 'int32'), then a range statement SHOULD be present. 1212 The following typedef from [RFC6991] demonstrates the proper use of 1213 the "range" statement: 1215 typedef dscp { 1216 type uint8 { 1217 range "0..63"; 1218 } 1219 ... 1220 } 1222 5.11.3. Enumerations and Bits 1224 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1225 or 'bit' SHOULD be documented. A separate description statement 1226 (within each 'enum' or 'bit' statement) SHOULD be present. 1228 leaf foo { 1229 // INCORRECT 1230 type enumeration { 1231 enum one; 1232 enum two; 1233 } 1234 description 1235 "The foo enum... 1236 one: The first enum 1237 two: The second enum"; 1238 } 1240 leaf foo { 1241 // CORRECT 1242 type enumeration { 1243 enum one { 1244 description "The first enum"; 1245 } 1246 enum two { 1247 description "The second enum"; 1248 } 1249 } 1250 description 1251 "The foo enum... "; 1252 } 1254 5.11.4. Union Types 1256 The YANG "union" type is evaluated by testing a value against each 1257 member type in the union. The first type definition that accepts a 1258 value as valid is the member type used. In general, member types 1259 SHOULD be ordered from most restrictive to least restrictive types. 1261 In the following example, the "enumeration" type will never be 1262 matched because the preceding "string" type will match everything. 1264 Incorrect: 1266 type union { 1267 type string; 1268 type enumeration { 1269 enum up; 1270 enum down; 1271 } 1272 } 1274 Correct: 1276 type union { 1277 type enumeration { 1278 enum up; 1279 enum down; 1280 } 1281 type string; 1282 } 1284 It is possible for different member types to match, depending on the 1285 input encoding format. In XML, all values are passed as string 1286 nodes, but in JSON there are different value types for numbers, 1287 booleans, and strings. 1289 In the following example, a JSON numeric value will always be matched 1290 by the "int32" type but in XML the string value representing a number 1291 will be matched by the "string" type. The second version will match 1292 the "int32" member type no matter how the input is encoded. 1294 Incorrect: 1296 type union { 1297 type string; 1298 type int32; 1299 } 1301 Correct: 1303 type union { 1304 type int32; 1305 type string; 1306 } 1308 5.11.5. Empty and Boolean 1310 YANG provides an "empty" data type, which has one value (i.e., 1311 present). The default is "not present", which is not actually a 1312 value. When used within a list key, only one value can (and must) 1313 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1314 key leaf since it is pointless. 1316 There is really no difference between a leaf of type "empty" and a 1317 leaf-list of type "empty". Both are limited to one instance. The 1318 type "empty" SHOULD NOT be used for a leaf-list. 1320 The advantage of using type "empty" instead of type "boolean" is that 1321 the default (not present) does not take up any bytes in a 1322 representation. The disadvantage is that the client may not be sure 1323 if an empty leaf is missing because it was filtered somehow or not 1324 implemented. The client may not have a complete and accurate schema 1325 for the data returned by the server, and not be aware of the missing 1326 leaf. 1328 The YANG "boolean" data type provides two values ("true" and 1329 "false"). When used within a list key, two entries can exist for 1330 this key leaf. Default values are ignored for key leafs, but a 1331 default statement is often used for plain boolean leafs. The 1332 advantage of the "boolean" type is that the leaf or leaf-list has a 1333 clear representation for both values. The default value is usually 1334 not returned unless explicitly requested by the client, so no bytes 1335 are used in a typical representation. 1337 In general, the "boolean" data type SHOULD be used instead of the 1338 "empty" data type, as shown in the example below: 1340 Incorrect: 1342 leaf flag1 { 1343 type empty; 1344 } 1346 Correct: 1348 leaf flag2 { 1349 type boolean; 1350 default false; 1351 } 1353 5.12. Reusable Type Definitions 1355 If an appropriate derived type exists in any standard module, such as 1356 [RFC6991], then it SHOULD be used instead of defining a new derived 1357 type. 1359 If an appropriate units identifier can be associated with the desired 1360 semantics, then a units statement SHOULD be present. 1362 If an appropriate default value can be associated with the desired 1363 semantics, then a default statement SHOULD be present. 1365 If a significant number of derived types are defined, and it is 1366 anticipated that these data types will be reused by multiple modules, 1367 then these derived types SHOULD be contained in a separate module or 1368 submodule, to allow easier reuse without unnecessary coupling. 1370 The description statement MUST be present. 1372 If the type definition semantics are defined in an external document 1373 (other than another YANG module indicated by an import statement), 1374 then the reference statement MUST be present. 1376 5.13. Reusable Groupings 1378 A reusable grouping is a YANG grouping that can be imported by 1379 another module, and is intended for use by other modules. This is 1380 not the same as a grouping that is used within the module it is 1381 defined, but happens to be exportable to another module because it is 1382 defined at the top-level of the YANG module. 1384 The following guidelines apply to reusable groupings, in order to 1385 make them as robust as possible: 1387 o Clearly identify the purpose of the grouping in the "description" 1388 statement. 1390 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1391 output, notification, config=true data nodes, and all data nodes). 1392 Clearly identify which XPath contexts are applicable or excluded 1393 for the grouping. 1395 o Do not reference data outside the grouping in any "path", "must", 1396 or "when" statements. 1398 o Do not include a "default" sub-statement on a leaf or choice 1399 unless the value applies on all possible contexts. 1401 o Do not include a "config" sub-statement on a data node unless the 1402 value applies on all possible contexts. 1404 o Clearly identify any external dependencies in the grouping 1405 "description" statement, such as nodes referenced by absolute path 1406 from a "path", "must", or "when" statement. 1408 5.14. Data Definitions 1410 The description statement MUST be present in the following YANG 1411 statements: 1413 o anyxml 1415 o augment 1417 o choice 1418 o container 1420 o extension 1422 o feature 1424 o grouping 1426 o identity 1428 o leaf 1430 o leaf-list 1432 o list 1434 o notification 1436 o rpc 1438 o typedef 1440 If the data definition semantics are defined in an external document, 1441 (other than another YANG module indicated by an import statement), 1442 then a reference statement MUST be present. 1444 The 'anyxml' construct may be useful to represent an HTML banner 1445 containing markup elements, such as '<b>' and '</b>', and 1446 MAY be used in such cases. However, this construct SHOULD NOT be 1447 used if other YANG data node types can be used instead to represent 1448 the desired syntax and semantics. 1450 It has been found that the 'anyxml' statement is not implemented 1451 consistently across all servers. It is possible that mixed mode XML 1452 will not be supported, or configuration anyxml nodes will not 1453 supported. 1455 If there are referential integrity constraints associated with the 1456 desired semantics that can be represented with XPath, then one or 1457 more 'must' statements SHOULD be present. 1459 For list and leaf-list data definitions, if the number of possible 1460 instances is required to be bounded for all implementations, then the 1461 max-elements statements SHOULD be present. 1463 If any 'must' or 'when' statements are used within the data 1464 definition, then the data definition description statement SHOULD 1465 describe the purpose of each one. 1467 The "choice" statement is allowed to be directly present within a 1468 "case" statement in YANG 1.1. This needs to be considered carefully. 1469 Consider simply including the nested "choice" as additional "case" 1470 statements within the parent "choice" statement. Note that the 1471 "mandatory" and "default" statements within a nested "choice" 1472 statement only apply if the "case" containing the nested "choice" 1473 statement is first selected. 1475 5.14.1. Non-Presence Containers 1477 A non-presence container is used to organize data into specific 1478 subtrees. It is not intended to have semantics within the data model 1479 beyond this purpose, although YANG allows it (e.g., "must" statement 1480 within the non-presence container). 1482 Example using container wrappers: 1484 container top { 1485 container foos { 1486 list foo { ... } 1487 } 1488 container bars { 1489 list bar { ... } 1490 } 1491 } 1493 Example without container wrappers: 1495 container top { 1496 list foo { ... } 1497 list bar { ... } 1498 } 1500 Use of non-presence containers to organize data is a subjective 1501 matter similar to use of sub-directories in a file system. The 1502 NETCONF and RESTCONF protocols do not currently support the ability 1503 to delete all list (or leaf-list) entries at once. This deficiency 1504 is sometimes avoided by use of a parent container (i.e., deleting the 1505 container also removes all child entries). 1507 5.14.2. Top-Level Data Nodes 1509 Use of top-level objects needs to be considered carefully 1511 -top-level siblings are not ordered -top-level siblings not are not 1512 static, and depends on the modules that are loaded 1513 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1514 treated as a content-match node for all top-level-siblings 1516 o a top-level list with many instances may impact performance 1518 5.15. Operation Definitions 1520 If the operation semantics are defined in an external document (other 1521 than another YANG module indicated by an import statement), then a 1522 reference statement MUST be present. 1524 If the operation impacts system behavior in some way, it SHOULD be 1525 mentioned in the description statement. 1527 If the operation is potentially harmful to system behavior in some 1528 way, it MUST be mentioned in the Security Considerations section of 1529 the document. 1531 5.16. Notification Definitions 1533 The description statement MUST be present. 1535 If the notification semantics are defined in an external document 1536 (other than another YANG module indicated by an import statement), 1537 then a reference statement MUST be present. 1539 If the notification refers to a specific resource instance, then this 1540 instance SHOULD be identified in the notification data. This is 1541 usually done by including 'leafref' leaf nodes with the key leaf 1542 values for the resource instance. For example: 1544 notification interface-up { 1545 description "Sent when an interface is activated."; 1546 leaf name { 1547 type leafref { 1548 path "/if:interfaces/if:interface/if:name"; 1549 } 1550 } 1551 } 1553 Note that there are no formal YANG statements to identify any data 1554 node resources associated with a notification. The description 1555 statement for the notification SHOULD specify if and how the 1556 notification identifies any data node resources associated with the 1557 specific event. 1559 5.17. Feature Definitions 1561 The YANG "feature" statement is used to define a label for a set of 1562 optional functionality within a module. The "if-feature" statement 1563 is used in the YANG statements associated with a feature. 1565 The set of YANG features available in a module should be considered 1566 carefully. The description-stmt within a feature-stmt MUST specify 1567 any interactions with other features. 1569 If there is a large set of objects associated with a YANG feature, 1570 then consider moving those objects to a separate module, instead of 1571 using a YANG feature. Note that the set of features within a module 1572 is easily discovered by the reader, but the set of related modules 1573 within the entire YANG library is not as easy to identity. Module 1574 names with a common prefix can help readers identity the set of 1575 related modules, but this assumes the reader will have discovered and 1576 installed all the relevant modules. 1578 Another consideration for deciding whether to create a new module or 1579 add a YANG feature is the stability of the module in question. It 1580 may be desirable to have a stable base module that is not changed 1581 frequently. If new functionality is placed in a separate module, 1582 then the base module does not need to be republished. If it is 1583 designed as a YANG feature then the module will need to be 1584 republished. 1586 If one feature requires implementation of another feature, then an 1587 "if-feature" statement SHOULD be used in the dependent "feature" 1588 statement. 1590 For example, feature2 requires implementation of feature1: 1592 feature feature1 { 1593 description "Some protocol feature"; 1594 } 1596 feature feature2 { 1597 if-feature "feature1"; 1598 description "Another protocol feature"; 1599 } 1601 5.18. YANG Data Node Constraints 1603 5.18.1. Controlling Quantity 1605 The "min-elements" and "max-elements" statements can be use to 1606 control how many list or leaf-list instances are required for a 1607 particular data node. YANG constraint statements SHOULD be used to 1608 identify conditions that apply to all implementations of the data 1609 model. If platform-specific limitations (e.g., the "max-elements" 1610 supported for a particular list) are relevant to operations, then a 1611 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1612 used to identify the limit. 1614 5.18.2. must vs. when 1616 The "must" and "when" YANG statements are used to provide cross- 1617 object referential tests. They have very different behavior. The 1618 "when" statement causes data node instances to be silently deleted as 1619 soon as the condition becomes false. A false "when" expression is 1620 not considered to be an error. 1622 The "when" statement SHOULD be used together with the "augment" or 1623 "uses" statements to achieve conditional model composition. The 1624 condition SHOULD be based on static properties of the augmented entry 1625 (e.g., list key leafs). 1627 The "must" statement causes a datastore validation error if the 1628 condition is false. This statement SHOULD be used for enforcing 1629 parameter value restrictions that involve more than one data node 1630 (e.g., end-time parameter must be after the start-time parameter). 1632 5.19. Augment Statements 1634 The YANG "augment" statement is used to define a set of data 1635 definition statements that will be added as child nodes of a target 1636 data node. The module namespace for these data nodes will be the 1637 augmenting module, not the augmented module. 1639 A top-level "augment" statement SHOULD NOT be used if the target data 1640 node is in the same module or submodule as the evaluated "augment" 1641 statement. The data definition statements SHOULD be added inline 1642 instead. 1644 5.19.1. Conditional Augment Statements 1646 The "augment" statement is often used together with the "when" 1647 statement and/or "if-feature" statement to make the augmentation 1648 conditional on some portion of the data model. 1650 The following example from [RFC7223] shows how a conditional 1651 container called "ethernet" is added to the "interface" list only for 1652 entries of the type "ethernetCsmacd". 1654 augment "/if:interfaces/if:interface" { 1655 when "if:type = 'ianaift:ethernetCsmacd'"; 1657 container ethernet { 1658 leaf duplex { 1659 ... 1660 } 1661 } 1662 } 1664 5.19.2. Conditionally Mandatory Data Definition Statements 1666 YANG has very specific rules about how configuration data can be 1667 updated in new releases of a module. These rules allow an "old 1668 client" to continue interoperating with a "new server". 1670 If data nodes are added to an existing entry, the old client MUST NOT 1671 be required to provide any mandatory parameters that were not in the 1672 original module definition. 1674 It is possible to add conditional augment statements such that the 1675 old client would not know about the new condition, and would not 1676 specify the new condition. The conditional augment statement can 1677 contain mandatory objects only if the condition is false unless 1678 explicitly requested by the client. 1680 Only a conditional augment statement that uses the "when" statement 1681 form of condition can be used in this manner. The YANG features 1682 enabled on the server cannot be controlled by the client in any way, 1683 so it is not safe to add mandatory augmenting data nodes based on the 1684 "if-feature" statement. 1686 The XPath "when" statement condition MUST NOT reference data outside 1687 of target data node because the client does not have any control over 1688 this external data. 1690 In the following dummy example, it is OK to augment the "interface" 1691 entry with "mandatory-leaf" because the augmentation depends on 1692 support for "some-new-iftype". The old client does not know about 1693 this type so it would never select this type, and therefore not be 1694 adding a mandatory data node. 1696 module example-module { 1697 namespace "http://example.com/ns/example-module"; 1698 prefix mymod; 1700 import iana-if-type { prefix iana; } 1701 import ietf-interfaces { prefix if; } 1703 identity some-new-iftype { 1704 base iana:iana-interface-type; 1705 } 1707 augment "/if:interfaces/if:interface" { 1708 when "if:type = 'mymod:some-new-iftype'"; 1710 leaf mandatory-leaf { 1711 mandatory true; 1712 ... 1713 } 1714 } 1715 } 1717 Note that this practice is safe only for creating data resources. It 1718 is not safe for replacing or modifying resources if the client does 1719 not know about the new condition. The YANG data model MUST be 1720 packaged in a way that requires the client to be aware of the 1721 mandatory data nodes if it is aware of the condition for this data. 1722 In the example above, the "some-new-iftype" identity is defined in 1723 the same module as the "mandatory-leaf" data definition statement. 1725 This practice is not safe for identities defined in a common module 1726 such as "iana-if-type" because the client is not required to know 1727 about "my-module" just because it knows about the "iana-if-type" 1728 module. 1730 5.20. Deviation Statements 1732 The YANG "deviation" statement cannot appear in IETF YANG modules, 1733 but it can be useful for documenting server capabilities. Deviation 1734 statements are not reusable and typically not shared across all 1735 platforms. 1737 There are several reasons that deviations might be needed in an 1738 implementation, e.g., an object cannot be supported on all platforms, 1739 or feature delivery is done in multiple development phases. 1740 Deviation statements can also be used to add annotations to a module, 1741 which does not affect the conformance requirements for the module. 1743 It is suggested that deviation statements be defined in separate 1744 modules from regular YANG definitions. This allows the deviations to 1745 be platform-specific and/or temporary. 1747 The order that deviation statements are evaluated can affect the 1748 result. Therefore multiple deviation statements in the same module, 1749 for the same target object, SHOULD NOT be used. 1751 The "max-elements" statement is intended to describe an architectural 1752 limit to the number of list entries. It is not intended to describe 1753 platform limitations. It is better to use a "deviation" statement 1754 for the platforms that have a hard resource limit. 1756 Example documenting platform resource limits: 1758 Wrong: (max-elements in the list itself) 1760 container backups { 1761 list backup { 1762 ... 1763 max-elements 10; 1764 ... 1765 } 1766 } 1768 Correct: (max-elements in a deviation) 1770 deviation /bk:backups/bk:backup { 1771 deviate add { 1772 max-elements 10; 1773 } 1774 } 1776 5.21. Extension Statements 1778 The YANG "extension" statement is used to specify external 1779 definitions. This appears in the YANG syntax as an 1780 "unknown-statement". Usage of extension statements in a published 1781 module needs to be considered carefully. 1783 The following guidelines apply to the usage of YANG extensions: 1785 o The semantics of the extension MUST NOT contradict any YANG 1786 statements. Extensions can add semantics not covered by the 1787 normal YANG statements. 1789 o The module containing the extension statement MUST clearly 1790 identify the conformance requirements for the extension. It 1791 should be clear whether all implementations of the YANG module 1792 containing the extension need to also implement the extension. If 1793 not, identify what conditions apply that would require 1794 implementation of the extension. 1796 o The extension MUST clearly identify where it can be used within 1797 other YANG statements. 1799 o The extension MUST clearly identify if YANG statements or other 1800 extensions are allowed or required within the extension as sub- 1801 statements. 1803 5.22. Data Correlation 1805 Data can be correlated in various ways, using common data types, 1806 common data naming, and common data organization. There are several 1807 ways to extend the functionality of a module, based on the degree of 1808 coupling between the old and new functionality: 1810 o inline: update the module with new protocol-accessible objects. 1811 The naming and data organization of the original objects is used. 1812 The new objects are in the original module namespace. 1814 o augment: create a new module with new protocol-accessible objects 1815 that augment the original data structure. The naming and data 1816 organization of the original objects is used. The new objects are 1817 in the new module namespace. 1819 o mirror: create new objects in a new module or the original module, 1820 except use new a naming scheme and data location. The naming can 1821 be coupled in different ways. Tight coupling is achieved with a 1822 "leafref" data type, with the "require-instance" sub-statement set 1823 to "true". This method SHOULD be used. 1825 If the new data instances are not limited to the values in use in the 1826 original data structure, then the "require-instance" sub-statement 1827 MUST be set to "false". Loose coupling is achieved by using key 1828 leafs with the same data type as the original data structure. This 1829 has the same semantics as setting the "require-instance" sub- 1830 statement to "false". 1832 It is sometimes useful to separate configuration and operational 1833 data, so that they do not not even share the exact same naming 1834 characteristics. The correlation between configuration the 1835 operational data that is affected by changes in configuration is a 1836 complex problem. There may not be a simple 1:1 relationship between 1837 a configuration data node and an operational data node. Further work 1838 is needed in YANG to clarify this relationship. Protocol work may 1839 also be needed to allow a client to retrieve this type of information 1840 from a server. At this time the best practice is to clearly document 1841 any relationship to other data structures in the "description" 1842 statement. 1844 5.23. Operational Data 1846 In YANG, any data that has a "config" statement value of "false" 1847 could be considered operational data. The relationship between 1848 configuration (i.e., "config" statement has a value of "true") and 1849 operational data can be complex. 1851 One challenge for client developers is determining if the configured 1852 value is being used, which requires the developer to know which 1853 operational data parameters are associated with the particular 1854 configuration object(s). 1856 If possible, operational data SHOULD be combined with its associated 1857 configuration data. This prevents duplication of key leafs and 1858 ancestor nodes. It also prevents race conditions for retrieval of 1859 dynamic entries, and allows configuration and operational data to be 1860 retrieved together with minimal message overhead. 1862 Not preferred: 1864 list foo { 1865 ... 1866 } 1868 list foo-state { 1869 config false; 1870 ... 1871 } 1873 Preferred: 1875 list foo { 1876 container foo-state { 1877 config false; 1878 ... 1879 } 1880 } 1882 If it is not possible to combine configuration and operational data, 1883 then the keys used to represent list entries SHOULD be the same type. 1884 The "leafref" data type SHOULD be used in operational data for key 1885 leafs that have corresponding configuration instances. The 1886 "require-instance" statement MAY be set to "false" (in YANG 1.1 1887 modules only) to indicate instances are allowed in the operational 1888 state that do not exist in the associated configuration data. 1890 The following example shows the use of the "leafref" data type: 1892 Not preferred: 1894 list foo { 1895 key name; 1896 leaf name { 1897 type string; 1898 } 1899 ... 1900 } 1902 list foo-state { 1903 key name; 1904 config false; 1905 leaf name { 1906 type string; 1907 } 1908 ... 1909 } 1911 Preferred: 1913 list foo { 1914 key name; 1915 leaf name { 1916 type string; 1917 } 1918 ... 1919 } 1921 list foo-state { 1922 key name; 1923 config false; 1924 leaf name { 1925 type leafref { 1926 path "/foo/name"; 1927 require-instance false; 1928 } 1929 } 1930 ... 1931 } 1933 In the simplest use-cases, there is no interaction between 1934 configuration and operational data. For example, the arbitrary 1935 administrative name or sequence number assigned to an access control 1936 rule. The configured value is always the value that is being used by 1937 the system. 1939 However, some configuration parameters interact with routing and 1940 other signalling protocols, such that the operational value in use by 1941 the system may not be the same as the configured value. Other 1942 parameters specify the desired state, but environmental and other 1943 factors can cause the actual state to be different. 1945 For example a "temperature" configuration setting only represents the 1946 desired temperature. An operational data parameter is needed that 1947 reports the actual temperature in order to determine if the cooling 1948 system is operating correctly. YANG has no mechanism other than the 1949 "description" statement to associate the desired temperature and the 1950 actual temperature. 1952 Careful consideration needs to be given to the location of 1953 operational data. It can either be located within the configuration 1954 subtree for which it applies, or it can be located outside the 1955 particular configuration subtree. Placing operational data within 1956 the configuration subtree is appropriate if the operational values 1957 can only exist if the configuration exists. 1959 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1960 are an example of a complex relationship between configuration and 1961 operational data. The operational values can include interface 1962 entries that have been discovered or initialized by the system. An 1963 interface may be in use that has not been configured at all. 1964 Therefore, the operational data for an interface cannot be located 1965 within the configuration for that same interface. 1967 Sometimes the configured value represents some sort of procedure to 1968 be followed, in which the system will select an actual value, based 1969 on protocol negotiation. 1971 leaf duplex-admin-mode { 1972 type enumeration { 1973 enum auto; 1974 enum half; 1975 enum full; 1976 } 1977 } 1979 leaf duplex-oper-mode { 1980 config false; 1981 type enumeration { 1982 enum half; 1983 enum full; 1984 } 1985 } 1987 For example a "duplex" mode configuration may be "auto" to auto- 1988 negotiate the actual value to be used. The operational parameter 1989 will never contain the value "auto". It will always contain the 1990 result of the auto-negotiation, such as "half" or "full". This is 1991 just one way in which the configuration data model is not exactly the 1992 same as the operational data model. Another is if the detailed 1993 properties of the data are different for configured vs. learned 1994 entries. 1996 If all the data model properties are aligned between configuration 1997 and operational data, then it can be useful to define the 1998 configuration parameters within a grouping, and then replicate that 1999 grouping within the operational data portion of the data model. 2001 grouping parms { 2002 // do not use config-stmt in any of the nodes 2003 // placed in this grouping 2004 } 2006 container foo { 2007 uses parms; // these are all config=true by default 2008 state { 2009 config false; // only exists if foo config exists 2010 uses parms; 2011 } 2012 } 2014 Note that this mechanism can also be used if the configuration and 2015 operational data are in separate sub-trees: 2017 container bar { // bar config can exist without bar-state 2018 config true; 2019 uses parms; 2020 } 2022 container bar-state { // bar-state can exist without bar 2023 config false; 2024 uses parms; 2025 } 2027 The need to replicate objects or define different operational data 2028 objects depends on the data model. It is not possible to define one 2029 approach that will be optimal for all data models. Designers SHOULD 2030 describe the relationship in detail between configuration objects and 2031 any associated operational data objects. The "description" 2032 statements for both the configuration and the operational data SHOULD 2033 be used for this purpose. 2035 5.24. Performance Considerations 2037 It is generally likely that certain YANG statements require more 2038 runtime resources than other statements. Although there are no 2039 performance requirements for YANG validation, the following 2040 information MAY be considered when designing YANG data models: 2042 o Lists are generally more expensive than containers 2044 o "when-stmt" evaluation is generally more expensive than 2045 "if-feature" or "choice" statements 2047 o "must" statement is generally more expensive than "min-entries", 2048 "max-entries", "mandatory", or "unique" statements 2050 o "identityref" leafs are generally more expensive than 2051 "enumeration" leafs 2053 o "leafref" and "instance-identifier" types with "require-instance" 2054 set to true are generally more expensive than if 2055 "require-instance" is set to false 2057 5.25. Open Systems Considerations 2059 A YANG module MUST NOT be designed such that the set of modules found 2060 on a server implementation can be predetermined in advance. Only the 2061 modules imported by a particular module can be assumed to be present 2062 in an implementation. An open system MAY include any combination of 2063 YANG modules. 2065 5.26. YANG 1.1 Guidelines 2067 The set of YANG 1.1 guidelines will grow as operational experience is 2068 gained with the new language features. This section contains an 2069 initial set of guidelines. 2071 5.26.1. Importing Multiple Revisions 2073 Standard modules SHOULD NOT import multiple revisions of the same 2074 module into a module. This MAY be done if the authors can 2075 demonstrate that the "avoided" definitions from the most recent of 2076 the multiple revisions are somehow broken or harmful to 2077 interoperability. 2079 5.26.2. Using Feature Logic 2081 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2082 "description" statement SHOULD describe the "if-feature" logic in 2083 text, to help readers understand the module. 2085 YANG features SHOULD be used instead of the "when" statement, if 2086 possible. Features are advertised by the server and objects 2087 conditional by if-feature are conceptually grouped together. There 2088 is no such commonality supported for "when" statements. 2090 Features generally require less server implementation complexity and 2091 runtime resources than objects that use "when" statements. Features 2092 are generally static (i.e., set when module is loaded and not changed 2093 at runtime). However every client edit might cause a "when" 2094 statement result to change. 2096 5.26.3. anyxml vs. anydata 2098 The "anyxml" statement MUST NOT be used to represent a conceptual 2099 subtree of YANG data nodes. The "anydata" statement MUST be used for 2100 this purpose. 2102 5.26.4. action vs. rpc 2104 The use of "action" statements or "rpc" statements is a subjective 2105 design decision. RPC operations are not associated with any 2106 particular data node. Actions are associated with a specific data 2107 node definition. An "action" statement SHOULD be used if the 2108 protocol operation is specific to a subset of all data nodes instead 2109 of all possible data nodes. 2111 The same action name MAY be used in different definitions within 2112 different data node. For example, a "reset" action defined with a 2113 data node definition for an interface might have different parameters 2114 than for a power supply or a VLAN. The same action name SHOULD be 2115 used to represent similar semantics. 2117 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2118 parameter access control for RPC operations. The user is given 2119 permission (or not) to invoke the RPC operation with any parameters. 2120 For example, if each client is only allowed to reset their own 2121 interface, then NACM cannot be used. 2123 For example, NACM cannot enforce access access control based on the 2124 value of the "interface" parameter, only the "reset" operation 2125 itself: 2127 rpc reset { 2128 input { 2129 leaf interface { 2130 type if:interface-ref; 2131 mandatory true; 2132 description "The interface to reset."; 2133 } 2134 } 2135 } 2137 However, NACM can enforce access access control for individual 2138 interface instances, using a "reset" action, If the user does not 2139 have read access to the specific "interface" instance, then it cannot 2140 invoke the "reset" action for that interface instance: 2142 container interfaces { 2143 list interface { 2144 ... 2145 action reset { } 2146 } 2147 } 2149 5.27. Updating YANG Modules (Published vs. Unpublished) 2151 YANG modules can change over time. Typically, new data model 2152 definitions are needed to support new features. YANG update rules 2153 defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be 2154 followed for published modules. They MAY be followed for unpublished 2155 modules. 2157 The YANG update rules only apply to published module revisions. Each 2158 organization will have their own way to identity published work which 2159 is considered to be stable, and unpublished work which is considered 2160 to be unstable. For example, in the IETF, the RFC document is used 2161 for published work, and the Internet-Draft is used for unpublished 2162 work. 2164 6. IANA Considerations 2166 This document registers one URI in the IETF XML registry [RFC3688]. 2168 The following registration has been made: 2170 URI: urn:ietf:params:xml:ns:yang:ietf-template 2172 Registrant Contact: The NETMOD WG of the IETF. 2174 XML: N/A, the requested URI is an XML namespace. 2176 Per this document, the following assignment has been made in the YANG 2177 Module Names Registry for the YANG module template in Appendix C. 2179 +-----------+-------------------------------------------+ 2180 | Field | Value | 2181 +-----------+-------------------------------------------+ 2182 | Name | ietf-template | 2183 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2184 | Prefix | temp | 2185 | Reference | RFC XXXX | 2186 +-----------+-------------------------------------------+ 2188 YANG Registry Assignment 2190 7. Security Considerations 2192 This document defines documentation guidelines for NETCONF content 2193 defined with the YANG data modeling language. The guidelines for how 2194 to write a Security Considerations section for a YANG module are 2195 defined in the online document 2197 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2198 yang-security-guidelines 2200 This document does not introduce any new or increased security risks 2201 into the management system. 2203 The following section contains the security considerations template 2204 dated 2010-06-16. Be sure to check the webpage at the URL listed 2205 above in case there is a more recent version available. 2207 Each specification that defines one or more YANG modules MUST contain 2208 a section that discusses security considerations relevant to those 2209 modules. This section MUST be patterned after the latest approved 2210 template (available at 2212 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2214 In particular, writable data nodes that could be especially 2215 disruptive if abused MUST be explicitly listed by name and the 2216 associated security risks MUST be spelled out. 2218 Similarly, readable data nodes that contain especially sensitive 2219 information or that raise significant privacy concerns MUST be 2220 explicitly listed by name and the reasons for the sensitivity/privacy 2221 concerns MUST be explained. 2223 Further, if new RPC operations have been defined, then the security 2224 considerations of each new RPC operation MUST be explained. 2226 7.1. Security Considerations Section Template 2228 X. Security Considerations 2230 The YANG module defined in this memo is designed to be accessed via 2231 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2232 secure transport layer and the mandatory-to-implement secure 2233 transport is SSH [RFC6242]. 2235 -- if you have any writable data nodes (those are all the 2236 -- "config true" nodes, and remember, that is the default) 2237 -- describe their specific sensitivity or vulnerability. 2239 There are a number of data nodes defined in this YANG module which 2240 are writable/creatable/deletable (i.e., config true, which is the 2241 default). These data nodes may be considered sensitive or vulnerable 2242 in some network environments. Write operations (e.g., edit-config) 2243 to these data nodes without proper protection can have a negative 2244 effect on network operations. These are the subtrees and data nodes 2245 and their sensitivity/vulnerability: 2247 2249 -- for all YANG modules you must evaluate whether any readable data 2250 -- nodes (those are all the "config false" nodes, but also all other 2251 -- nodes, because they can also be read via operations like get or 2252 -- get-config) are sensitive or vulnerable (for instance, if they 2253 -- might reveal customer information or violate personal privacy 2254 -- laws such as those of the European Union if exposed to 2255 -- unauthorized parties) 2257 Some of the readable data nodes in this YANG module may be considered 2258 sensitive or vulnerable in some network environments. It is thus 2259 important to control read access (e.g., via get, get-config, or 2260 notification) to these data nodes. These are the subtrees and data 2261 nodes and their sensitivity/vulnerability: 2263 2265 -- if your YANG module has defined any rpc operations 2266 -- describe their specific sensitivity or vulnerability. 2268 Some of the RPC operations in this YANG module may be considered 2269 sensitive or vulnerable in some network environments. It is thus 2270 important to control access to these operations. These are the 2271 operations and their sensitivity/vulnerability: 2273 2275 8. Acknowledgments 2277 The structure and contents of this document are adapted from 2278 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2280 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2281 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 2282 contributions to this document. 2284 9. Changes Since RFC 6087 2286 The following changes have been made to the guidelines published in 2287 [RFC6087]: 2289 o Updated NETCONF reference from RFC 4741 to RFC 6241 2291 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2293 o Updated YANG Types reference from RFC 6021 to RFC 6991 2295 o Updated obsolete URLs for IETF resources 2297 o Changed top-level data node guideline 2299 o Clarified XPath usage for a literal value representing a YANG 2300 identity 2302 o Clarified XPath usage for a when-stmt 2304 o Clarified XPath usage for 'proceeding-sibling' and 2305 'following-sibling' axes 2307 o Added terminology guidelines 2309 o Added YANG tree diagram definition and guideline 2311 o Updated XPath guidelines for type conversions and function library 2312 usage. 2314 o Updated data types section 2316 o Updated notifications section 2318 o Clarified conditional key leaf nodes 2320 o Clarify usage of 'uint64' and 'int64' data types 2322 o Added text on YANG feature usage 2324 o Added Identifier Naming Conventions 2326 o Clarified use of mandatory nodes with conditional augmentations 2328 o Clarified namespace and domain conventions for example modules 2330 o Added and convention 2331 o Added YANG 1.1 guidelines 2333 o Added Data Model Constraints section 2335 10. References 2337 10.1. Normative References 2339 [I-D.ietf-netmod-rfc6020bis] 2340 Bjorklund, M., "YANG - A Data Modeling Language for the 2341 Network Configuration Protocol (NETCONF)", 2342 draft-ietf-netmod-rfc6020bis-07 (work in progress), 2343 September 2015. 2345 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2346 Requirement Levels", BCP 14, RFC 2119, March 1997. 2348 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 2349 RFC 2223, October 1997. 2351 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2352 January 2004. 2354 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2355 Resource Identifier (URI): Generic Syntax", STD 66, 2356 RFC 3986, January 2005. 2358 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2359 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2361 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 2362 and Boilerplates", RFC 5741, December 2009. 2364 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2365 Network Configuration Protocol (NETCONF)", RFC 6020, 2366 October 2010. 2368 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2369 and A. Bierman, Ed., "Network Configuration Protocol 2370 (NETCONF)", RFC 6241, June 2011. 2372 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2373 July 2013. 2375 [W3C.REC-xpath-19991116] 2376 Clark, J. and S. DeRose, "XML Path Language (XPath) 2377 Version 1.0", World Wide Web Consortium 2378 Recommendation REC-xpath-19991116, November 1999, 2379 . 2381 10.2. Informative References 2383 [RFC-STYLE] 2384 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2385 Style", September 2009, 2386 . 2388 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2389 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2390 . 2392 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2393 Documents", BCP 111, RFC 4181, September 2005. 2395 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2396 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2397 May 2008. 2399 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2400 Data Model Documents", RFC 6087, January 2011. 2402 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2403 Protocol (NETCONF) Access Control Model", RFC 6536, 2404 March 2012. 2406 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2407 Management", RFC 7223, May 2014. 2409 Appendix A. Change Log 2411 -- RFC Ed.: remove this section before publication. 2413 A.1. v07 to v08 2415 o changed CODE BEGINS guideline for example modules 2417 o updated tree diagram guidelines 2419 o clarified published and unpublished terms 2421 o added section on Empty and Boolean data types 2423 o clarified how to update the revision statement 2425 o updated operational state guidelines 2427 o added 'YANG fragment' to terminology section 2429 A.2. v06 to v07 2431 o update contact statement guideline 2433 o update example modules guidelines 2435 o add guidelines on top-level data nodes 2437 o add guideline on use of NP containers 2439 o added guidelines on union types 2441 o add guideline on deviations 2443 o added section on open systems considerations 2445 o added guideline about definitions reserved for future use 2447 A.3. v05 to v06 2449 o Changed example 'my-module' to 'example-module' 2451 o Added section Updating YANG Modules (Published vs. Unpublished) 2453 o Added Example Modules section 2455 o Added "" convention for full example modules 2456 o Added section on using action vs. rpc 2458 o Changed term "operational state" to "operational data" 2460 o Added section on YANG Data Node Constraints 2462 o Added guidelines on using must vs. when statements 2464 o Made ietf-foo module validate for I-D submission 2466 A.4. v04 to v05 2468 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2469 no YANG 1.1 features needed 2471 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2472 standards track documents only) 2474 o Clarified module naming conventions for normative modules, example 2475 modules, and modules from other SDOs. 2477 o Added prefix value selection guidelines 2479 o Added new section on guidelines for reusable groupings 2481 o Made header guidelines less IETF-specific 2483 o Added new section on guidelines for extension statements 2485 o Added guidelines for nested "choice" statement within a "case" 2486 statement 2488 A.5. v03 ot v04 2490 o Added sections for deviation statements and performance 2491 considerations 2493 o Added YANG 1.1 section 2495 o Updated YANG reference from 1.0 to 1.1 2497 A.6. v02 to v03 2499 o Updated draft based on github data tracker issues added by Benoit 2500 Clause (Issues 12 - 18) 2502 A.7. v01 to v02 2504 o Updated draft based on mailing list comments. 2506 A.8. v00 to v01 2508 All issues from the issue tracker have been addressed. 2510 https://github.com/netmod-wg/rfc6087bis/issues 2512 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 2513 can use an Informative reference to this RFC for tree diagrams. 2514 Updated guidelines to reference this RFC when tree diagrams are 2515 used 2517 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2518 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2519 functions 2521 o Issue 3: XPath function document order issues: Added paragraph in 2522 XPath usage section about node-set ordering for 'local-name', 2523 'namespace-uri', 'name', 'string' and 'number' functions. Also 2524 any function that implicitly converts a node-set to a string. 2526 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2527 and text in XPath usage section already has proposed text from 2528 Lada. 2530 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2531 exception and example in XPath Usage section for augmented nodes. 2533 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2534 to 'numeric and boolean expressions' 2536 o Issue 7: XPath module containment: Added sub-section on XPath 2537 wildcards 2539 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2540 section about transitioning from active to deprecated and then to 2541 obsolete. 2543 o Issue 9: resource identification in notifications: Add text to 2544 Notifications section about identifying resources and using the 2545 leafref data type. 2547 o Issue 10: single quoted strings: Added text to Data Types section 2548 about using a single-quoted string for patterns. 2550 Appendix B. Module Review Checklist 2552 This section is adapted from RFC 4181. 2554 The purpose of a YANG module review is to review the YANG module both 2555 for technical correctness and for adherence to IETF documentation 2556 requirements. The following checklist may be helpful when reviewing 2557 an Internet-Draft: 2559 o I-D Boilerplate -- verify that the draft contains the required 2560 Internet-Draft boilerplate (see 2561 http://www.ietf.org/id-info/guidelines.html), including the 2562 appropriate statement to permit publication as an RFC, and that 2563 I-D boilerplate does not contain references or section numbers. 2565 o Abstract -- verify that the abstract does not contain references, 2566 that it does not have a section number, and that its content 2567 follows the guidelines in 2568 http://www.ietf.org/id-info/guidelines.html. 2570 o Copyright Notice -- verify that the draft has the appropriate text 2571 regarding the rights that document contributers provide to the 2572 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2573 copyright notice at the beginning of the document. The IETF Trust 2574 Legal Provisions (TLP) can be found at: 2576 http://trustee.ietf.org/license-info/ 2578 o Security Considerations section -- verify that the draft uses the 2579 latest approved template from the OPS area website (http:// 2580 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2581 and that the guidelines therein have been followed. 2583 o IANA Considerations section -- this section must always be 2584 present. For each module within the document, ensure that the 2585 IANA Considerations section contains entries for the following 2586 IANA registries: 2588 XML Namespace Registry: Register the YANG module namespace. 2590 YANG Module Registry: Register the YANG module name, prefix, 2591 namespace, and RFC number, according to the rules specified 2592 in [I-D.ietf-netmod-rfc6020bis]. 2594 o References -- verify that the references are properly divided 2595 between normative and informative references, that RFC 2119 is 2596 included as a normative reference if the terminology defined 2597 therein is used in the document, that all references required by 2598 the boilerplate are present, that all YANG modules containing 2599 imported items are cited as normative references, and that all 2600 citations point to the most current RFCs unless there is a valid 2601 reason to do otherwise (for example, it is OK to include an 2602 informative reference to a previous version of a specification to 2603 help explain a feature included for backward compatibility). Be 2604 sure citations for all imported modules are present somewhere in 2605 the document text (outside the YANG module). 2607 o License -- verify that the draft contains the Simplified BSD 2608 License in each YANG module or submodule. Some guidelines related 2609 to this requirement are described in Section 4.1. Make sure that 2610 the correct year is used in all copyright dates. Use the approved 2611 text from the latest Trust Legal Provisions (TLP) document, which 2612 can be found at: 2614 http://trustee.ietf.org/license-info/ 2616 o Other Issues -- check for any issues mentioned in 2617 http://www.ietf.org/id-info/checklist.html that are not covered 2618 elsewhere. 2620 o Technical Content -- review the actual technical content for 2621 compliance with the guidelines in this document. The use of a 2622 YANG module compiler is recommended when checking for syntax 2623 errors. A list of freely available tools and other information 2624 can be found at: 2626 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2628 Checking for correct syntax, however, is only part of the job. 2629 It is just as important to actually read the YANG module document 2630 from the point of view of a potential implementor. It is 2631 particularly important to check that description statements are 2632 sufficiently clear and unambiguous to allow interoperable 2633 implementations to be created. 2635 Appendix C. YANG Module Template 2637 file "ietf-template@2016-03-20.yang" 2639 module ietf-template { 2641 // replace this string with a unique namespace URN value 2642 namespace 2643 "urn:ietf:params:xml:ns:yang:ietf-template"; 2645 // replace this string, and try to pick a unique prefix 2646 prefix "temp"; 2648 // import statements here: e.g., 2649 // import ietf-yang-types { prefix yang; } 2650 // import ietf-inet-types { prefix inet; } 2652 // identify the IETF working group if applicable 2653 organization 2654 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2656 // update this contact statement with your info 2657 contact 2658 "WG Web: 2659 WG List: 2661 Editor: your-name 2662 "; 2664 // replace the first sentence in this description statement. 2665 // replace the copyright notice with the most recent 2666 // version, if it has been updated since the publication 2667 // of this document 2668 description 2669 "This module defines a template for other YANG modules. 2671 Copyright (c) IETF Trust and the persons 2672 identified as authors of the code. All rights reserved. 2674 Redistribution and use in source and binary forms, with or 2675 without modification, is permitted pursuant to, and subject 2676 to the license terms contained in, the Simplified BSD License 2677 set forth in Section 4.c of the IETF Trust's Legal Provisions 2678 Relating to IETF Documents 2679 (http://trustee.ietf.org/license-info). 2681 This version of this YANG module is part of RFC XXXX; see 2682 the RFC itself for full legal notices."; 2684 // RFC Ed.: replace XXXX with actual RFC number and remove 2685 // this note 2687 reference "RFC XXXX"; 2689 // RFC Ed.: remove this note 2690 // Note: extracted from RFC XXXX 2692 // replace '2016-03-20' with the module publication date 2693 // The format is (year-month-day) 2694 revision "2016-03-20" { 2695 description "what changed in this revision"; 2696 reference "document containing this module"; 2697 } 2699 // extension statements 2701 // feature statements 2703 // identity statements 2705 // typedef statements 2707 // grouping statements 2709 // data definition statements 2711 // augment statements 2713 // rpc statements 2715 // notification statements 2717 // DO NOT put deviation statements in a published module 2719 } 2721 2723 Author's Address 2725 Andy Bierman 2726 YumaWorks 2728 Email: andy@yumaworks.com