idnits 2.17.1 draft-ietf-netmod-rfc6087bis-13.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 (June 18, 2017) is 2497 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC5378' is defined on line 2262, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-02 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-00 -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 0 errors (**), 0 flaws (~~), 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 Obsoletes: 6087 (if approved) June 18, 2017 5 Intended status: Informational 6 Expires: December 20, 2017 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-13 11 Abstract 13 This memo provides guidelines for authors and reviewers of Standards 14 Track specifications containing YANG data model modules. Applicable 15 portions may be used as a basis for reviews of other YANG data model 16 documents. Recommendations and procedures are defined, which are 17 intended to increase interoperability and usability of Network 18 Configuration Protocol (NETCONF) and RESTCONF protocol 19 implementations that utilize YANG data model modules. This document 20 obsoletes RFC 6087. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 20, 2017. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 59 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 60 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 2.4.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7 63 3. General Documentation Guidelines . . . . . . . . . . . . . . . 8 64 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 65 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8 66 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 67 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9 68 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 69 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 70 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11 71 3.7. Security Considerations Section . . . . . . . . . . . . . 11 72 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 12 73 3.8.1. Documents that Create a New Namespace . . . . . . . . 12 74 3.8.2. Documents that Extend an Existing Namespace . . . . . 12 75 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 76 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13 77 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 78 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 13 79 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 80 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 81 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 83 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 84 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 85 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 86 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 87 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 88 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 89 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 90 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 91 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 92 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 93 4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 94 4.8. Module Header, Meta, and Revision Statements . . . . . . . 23 95 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 96 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 97 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26 98 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 99 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27 100 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28 101 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 29 102 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 30 103 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 31 104 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 32 105 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 32 106 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 34 107 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 34 108 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 35 109 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 35 110 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 36 111 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 36 112 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 36 113 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 37 114 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 37 115 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 37 116 4.19.2. Conditionally Mandatory Data Definition Statements . . 38 117 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 39 118 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 40 119 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 41 120 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 42 121 4.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43 122 4.24. Performance Considerations . . . . . . . . . . . . . . . . 43 123 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 44 124 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 44 125 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 44 126 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 44 127 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 45 128 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 45 129 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 46 130 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 131 6. Security Considerations . . . . . . . . . . . . . . . . . . . 48 132 6.1. Security Considerations Section Template . . . . . . . . . 48 133 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50 134 8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 51 135 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 136 9.1. Normative References . . . . . . . . . . . . . . . . . . . 53 137 9.2. Informative References . . . . . . . . . . . . . . . . . . 53 138 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 56 139 A.1. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 56 140 A.2. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 56 141 A.3. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 56 142 A.4. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 56 143 A.5. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 56 144 A.6. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 57 145 A.7. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 57 146 A.8. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 57 147 A.9. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 58 148 A.10. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 58 149 A.11. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 58 150 A.12. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 59 151 A.13. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 59 152 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 60 153 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 62 154 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64 156 1. Introduction 158 The standardization of network configuration interfaces for use with 159 the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040] 160 requires a modular set of data models, which can be reused and 161 extended over time. 163 This document defines a set of usage guidelines for Standards Track 164 documents containing [RFC7950] data models. YANG is used to define 165 the data structures, protocol operations, and notification content 166 used within a NETCONF and/or RESTCONF server. A server that supports 167 a particular YANG module will support client NETCONF and/or RESTCONF 168 operation requests, as indicated by the specific content defined in 169 the YANG module. 171 This document is similar to the Structure of Management Information 172 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 173 and structure. However, since that document was written a decade 174 after SMIv2 modules had been in use, it was published as a 'Best 175 Current Practice' (BCP). This document is not a BCP, but rather an 176 informational reference, intended to promote consistency in documents 177 containing YANG modules. 179 Many YANG constructs are defined as optional to use, such as the 180 description statement. However, in order to maximize 181 interoperability of NETCONF and RESTCONF implementations utilizing 182 YANG data models, it is desirable to define a set of usage guidelines 183 that may require a higher level of compliance than the minimum level 184 defined in the YANG specification. 186 In addition, YANG allows constructs such as infinite length 187 identifiers and string values, or top-level mandatory nodes, that a 188 compliant server is not required to support. Only constructs that 189 all servers are required to support can be used in IETF YANG modules. 191 This document defines usage guidelines related to the NETCONF 192 operations layer and NETCONF content layer, as defined in [RFC6241], 193 and the RESTCONF methods and RESTCONF resources, as defined in 194 [RFC8040], 196 These guidelines are intended to be used by authors and reviewers to 197 improve the readability and interoperability of published YANG data 198 models. 200 Note that this document is not a YANG tutorial and the reader is 201 expected to know the YANG data modeling language before using this 202 document. 204 2. Terminology 206 2.1. Requirements Notation 208 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 209 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 210 document are to be interpreted as described in [RFC2119]. 212 RFC 2119 language is used here to express the views of the NETMOD 213 working group regarding content for YANG modules. YANG modules 214 complying with this document will treat the RFC 2119 terminology as 215 if it were describing best current practices. 217 2.2. NETCONF Terms 219 The following terms are defined in [RFC6241] and are not redefined 220 here: 222 o capabilities 224 o client 226 o operation 228 o server 230 2.3. YANG Terms 232 The following terms are defined in [RFC7950] and are not redefined 233 here: 235 o data node 237 o module 239 o namespace 241 o submodule 243 o version 245 o YANG 247 o YIN 249 Note that the term 'module' may be used as a generic term for a YANG 250 module or submodule. When describing properties that are specific to 251 submodules, the term 'submodule' is used instead. 253 2.4. Terms 255 The following terms are used throughout this document: 257 o published: A stable release of a module or submodule. For example 258 the "Request for Comments" described in section 2.1 of [RFC2026] 259 is considered a stable publication. 261 o unpublished: An unstable release of a module or submodule. For 262 example the "Internet-Draft" described in section 2.2 of [RFC2026] 263 is considered an unstable publication that is a work-in-progress, 264 subject to change at any time. 266 o YANG fragment: A set of YANG statements that are not intended to 267 represent a complete YANG module or submodule. These statements 268 are not intended for actual use, except to provide an example of 269 YANG statement usage. The invalid syntax "..." is sometimes used 270 to indicate that additional YANG statements would be present in a 271 real YANG module. 273 2.4.1. YANG Tree Diagrams 275 A simplified graphical representation of the data model is used in 276 this document. The meaning of the symbols in these diagrams is 277 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 279 3. General Documentation Guidelines 281 YANG data model modules under review are likely to be contained in 282 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 283 followed. The RFC Editor provides guidelines for authors of RFCs, 284 which are first published as Internet-Drafts. These guidelines 285 should be followed and are defined in [RFC7322] and updated in 286 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 288 The following sections MUST be present in an Internet-Draft 289 containing a module: 291 o Narrative sections 293 o Definitions section 295 o Security Considerations section 297 o IANA Considerations section 299 o References section 301 There are three usage scenarios for YANG that can appear in an 302 Internet-Draft or RFC: 304 o normative module or submodule 306 o example module or submodule 308 o example YANG fragment not part of any module or submodule 310 The guidelines in this document refer mainly to a normative complete 311 module or submodule, but may be applicable to example modules and 312 YANG fragments as well. 314 3.1. Module Copyright 316 The module description statement MUST contain a reference to the 317 latest approved IETF Trust Copyright statement, which is available 318 online at: 320 http://trustee.ietf.org/license-info/ 322 3.2. Code Components 324 Each normative YANG module or submodule contained within an Internet- 325 Draft or RFC is considered to be a code component. The strings 326 "" and "" MUST be used to identify each code 327 component. 329 The "" tag SHOULD be followed by a string identifying 330 the file name specified in Section 5.2 of [RFC7950]. The name string 331 form that includes the revision-date SHOULD be used. The following 332 example is for the '2010-01-18' revision of the 'ietf-foo' module: 334 file "ietf-foo@2016-03-20.yang" 336 module ietf-foo { 337 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 338 prefix "foo"; 339 organization "..."; 340 contact "..."; 341 description "..."; 342 revision 2016-03-20 { 343 description "Latest revision"; 344 reference "RFC XXXX"; 345 } 346 // ... more statements 347 } 349 351 3.2.1. Example Modules 353 Example modules are not code components. The 354 convention MUST NOT be used for example modules. 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 3.3. 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 [I-D.ietf-netmod-yang-tree-diagrams]. 372 3.4. Tree Diagrams 374 YANG tree diagrams provide a concise representation of a YANG module, 375 and SHOULD be included to help readers understand YANG module 376 structure. Tree diagrams MAY be split into sections to correspond to 377 document structure. 379 The following example shows a simple YANG tree diagram: 381 +--rw top-level-config-container 382 | +--rw config-list* [key-name] 383 | +--rw key-name string 384 | +--rw optional-parm? string 385 | +--rw mandatory-parm identityref 386 | +--ro read-only-leaf string 387 +--ro top-level-nonconfig-container 388 +--ro nonconfig-list* [name] 389 +--ro name string 390 +--ro type string 392 The 'pyang' compiler can be used to produce the tree diagram, using 393 the '-f tree' command line parameter. 395 If the YANG module is comprised of groupings only, then the tree 396 diagram SHOULD contain the groupings. The 'pyang' compiler can be 397 used to produce a tree diagram with groupings using the '-f tree 398 --tree-print-groupings" command line parameters. 400 If the YANG module contains notifications, then the tree diagram 401 SHOULD contain the notifications. If the YANG module contains RPC 402 statements, then the tree diagram SHOULD contain the RPC statements. 404 3.5. Narrative Sections 406 The narrative part MUST include an overview section that describes 407 the scope and field of application of the module(s) defined by the 408 specification and that specifies the relationship (if any) of these 409 modules to other standards, particularly to standards containing 410 other YANG modules. The narrative part SHOULD include one or more 411 sections to briefly describe the structure of the modules defined in 412 the specification. 414 If the module(s) defined by the specification imports definitions 415 from other modules (except for those defined in the [RFC7950] or 416 [RFC6991] documents), or are always implemented in conjunction with 417 other modules, then those facts MUST be noted in the overview 418 section, as MUST be noted any special interpretations of definitions 419 in other modules. 421 3.6. Definitions Section 423 This section contains the module(s) defined by the specification. 424 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 425 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 426 semantics are needed in the module. 428 A YIN syntax version of the module MAY also be present in the 429 document. There MAY also be other types of modules present in the 430 document, such as SMIv2, which are not affected by these guidelines. 432 Note that all YANG statements within a YANG module are considered 433 normative, if the module itself is considered normative, and not an 434 example module. The use of keywords defined in [RFC2119] apply to 435 YANG description statements in normative modules exactly as they 436 would in any other normative section. 438 Example YANG modules MUST NOT contain any normative text, including 439 any reserved words from [RFC2119]. 441 See Section 4 for guidelines on YANG usage. 443 3.7. Security Considerations Section 445 Each specification that defines one or more modules MUST contain a 446 section that discusses security considerations relevant to those 447 modules. 449 This section MUST be patterned after the latest approved template 450 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 451 yang-security-guidelines). Section 6.1 contains the security 452 considerations template dated 2013-05-08. Authors MUST check the WEB 453 page at the URL listed above in case there is a more recent version 454 available. 456 In particular: 458 o Writable data nodes that could be especially disruptive if abused 459 MUST be explicitly listed by name and the associated security 460 risks MUST be explained. 462 o Readable data nodes that contain especially sensitive information 463 or that raise significant privacy concerns MUST be explicitly 464 listed by name and the reasons for the sensitivity/privacy 465 concerns MUST be explained. 467 o Operations (i.e., YANG 'rpc' statements) that are potentially 468 harmful to system behavior or that raise significant privacy 469 concerns MUST be explicitly listed by name and the reasons for the 470 sensitivity/privacy concerns MUST be explained. 472 3.8. IANA Considerations Section 474 In order to comply with IESG policy as set forth in 475 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 476 is submitted to the IESG for publication MUST contain an IANA 477 Considerations section. The requirements for this section vary 478 depending on what actions are required of the IANA. If there are no 479 IANA considerations applicable to the document, then the IANA 480 Considerations section stating that there are no actions is removed 481 by the RFC Editor before publication. Refer to the guidelines in 482 [RFC5226] for more details. 484 Each normative YANG module MUST be registered in the XML namespace 485 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 486 This applies to new modules and updated modules. Examples of these 487 registrations for the "ietf-template" module can be found in 488 Section 5. 490 3.8.1. Documents that Create a New Namespace 492 If an Internet-Draft defines a new namespace that is to be 493 administered by the IANA, then the document MUST include an IANA 494 Considerations section that specifies how the namespace is to be 495 administered. 497 Specifically, if any YANG module namespace statement value contained 498 in the document is not already registered with IANA, then a new YANG 499 Namespace registry entry MUST be requested from the IANA. The 500 [RFC7950] specification includes the procedure for this purpose in 501 its IANA Considerations section. 503 3.8.2. Documents that Extend an Existing Namespace 505 It is possible to extend an existing namespace using a YANG submodule 506 that belongs to an existing module already administered by IANA. In 507 this case, the document containing the main module MUST be updated to 508 use the latest revision of the submodule. 510 3.9. Reference Sections 512 For every import or include statement that appears in a module 513 contained in the specification, which identifies a module in a 514 separate document, a corresponding normative reference to that 515 document MUST appear in the Normative References section. The 516 reference MUST correspond to the specific module version actually 517 used within the specification. 519 For every normative reference statement that appears in a module 520 contained in the specification, which identifies a separate document, 521 a corresponding normative reference to that document SHOULD appear in 522 the Normative References section. The reference SHOULD correspond to 523 the specific document version actually used within the specification. 524 If the reference statement identifies an informative reference, which 525 identifies a separate document, a corresponding informative reference 526 to that document MAY appear in the Informative References section. 528 3.10. Validation Tools 530 All modules need to be validated before submission in an Internet 531 Draft. The 'pyang' YANG compiler is freely available from github: 533 https://github.com/mbj4668/pyang 535 If the 'pyang' compiler is used to validate a normative module, then 536 the "--ietf" command line option MUST be used to identify any IETF 537 guideline issues. 539 If the 'pyang' compiler is used to validate an example module, then 540 the "--ietf" command line option MAY be used to identify any IETF 541 guideline issues. 543 3.11. Module Extraction Tools 545 A version of 'rfcstrip' is available which will extract YANG modules 546 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 547 YANG module extraction is freely available: 549 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 551 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 553 can be extracted correctly. 555 3.12. Module Usage Examples 557 Each specification that defines one or more modules SHOULD contain 558 usage examples, either throughout the document or in an appendix. 559 This includes example instance document snippets in an appropriate 560 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 561 the YANG module(s). 563 4. YANG Usage Guidelines 565 Modules in IETF Standards Track specifications MUST comply with all 566 syntactic and semantic requirements of YANG [RFC7950]. The 567 guidelines in this section are intended to supplement the YANG 568 specification, which is intended to define a minimum set of 569 conformance requirements. 571 In order to promote interoperability and establish a set of practices 572 based on previous experience, the following sections establish usage 573 guidelines for specific YANG constructs. 575 Only guidelines that clarify or restrict the minimum conformance 576 requirements are included here. 578 4.1. Module Naming Conventions 580 Normative modules contained in Standards Track documents MUST be 581 named according to the guidelines in the IANA Considerations section 582 of [RFC7950]. 584 A distinctive word or acronym (e.g., protocol name or working group 585 acronym) SHOULD be used in the module name. If new definitions are 586 being defined to extend one or more existing modules, then the same 587 word or acronym should be reused, instead of creating a new one. 589 All published module names MUST be unique. For a YANG module 590 published in an RFC, this uniqueness is guaranteed by IANA. For 591 unpublished modules, the authors need to check that no other work in 592 progress is using the same module name. 594 Example modules are non-normative, and SHOULD be named with the 595 prefix "example-". 597 It is suggested that a stable prefix be selected representing the 598 entire organization. All normative YANG modules published by the 599 IETF MUST begin with the prefix "ietf-". Another standards 600 organization, such as the IEEE, might use the prefix "ieee-" for all 601 YANG modules. 603 Once a module name is published, it MUST NOT be reused, even if the 604 RFC containing the module is reclassified to 'Historic' status. A 605 module name cannot be changed in YANG, and this would be treated as a 606 a new module, not a name change. 608 4.2. Prefixes 610 All YANG definitions are scoped by the module containing the 611 definition being referenced. This allows definitions from multiple 612 modules to be used, even if the names are not unique. In the example 613 below, the identifier "foo" is used in all 3 modules: 615 module example-foo { 616 namespace "http://example.com/ns/foo"; 617 prefix f; 619 container foo; 620 } 622 module example-bar { 623 namespace "http://example.com/ns/bar"; 624 prefix b; 626 typedef foo { type uint32; } 627 } 629 module example-one { 630 namespace "http://example.com/ns/one"; 631 prefix one; 632 import example-foo { prefix f; } 633 import example-bar { prefix b; } 635 augment "/f:foo" { 636 leaf foo { type b:foo; } 637 } 638 } 640 YANG defines the following rules for prefix usage: 642 o Prefixes are never allowed for built in data types and YANG 643 keywords. 645 o A prefix MUST be used for any external statement (i.e., a 646 statement defined with the YANG "extension" statement) 648 o The proper module prefix MUST be used for all identifiers imported 649 from other modules 651 o The proper module prefix MUST be used for all identifiers included 652 from a submodule. 654 The following guidelines apply to prefix usage of the current (local) 655 module: 657 o The local module prefix SHOULD be used instead of no prefix in all 658 path expressions. 660 o The local module prefix MUST be used instead of no prefix in all 661 "default" statements for an "identityref" or "instance-identifier" 662 data type 664 o The local module prefix MAY be used for references to typedefs, 665 groupings, extensions, features, and identities defined in the 666 module. 668 Prefix values SHOULD be short, but also likely to be unique. Prefix 669 values SHOULD NOT conflict with known modules that have been 670 previously published. 672 4.3. Identifiers 674 Identifiers for all YANG identifiers in published modules MUST be 675 between 1 and 64 characters in length. These include any construct 676 specified as an 'identifier-arg-str' token in the ABNF in Section 13 677 of [RFC7950]. 679 4.3.1. Identifier Naming Conventions 681 Identifiers SHOULD follow a consistent naming pattern throughout the 682 module. Only lower-case letters, numbers, and dashes SHOULD be used 683 in identifier names. Upper-case characters and the underscore 684 character MAY be used if the identifier represents a well-known value 685 that uses these characters. 687 Identifiers SHOULD include complete words and/or well-known acronyms 688 or abbreviations. Child nodes within a container or list SHOULD NOT 689 replicate the parent identifier. YANG identifiers are hierarchical 690 and are only meant to be unique within the the set of sibling nodes 691 defined in the same module namespace. 693 It is permissible to use common identifiers such as "name" or "id" in 694 data definition statements, especially if these data nodes share a 695 common data type. 697 Identifiers SHOULD NOT carry any special semantics that identify data 698 modelling properties. Only YANG statements and YANG extension 699 statements are designed to convey machine readable data modelling 700 properties. For example, naming an object "config" or "state" does 701 not change whether it is configuration data or state data. Only 702 defined YANG statements or YANG extension statements can be used to 703 assign semantics in a machine readable format in YANG. 705 4.4. Defaults 707 In general, it is suggested that substatements containing very common 708 default values SHOULD NOT be present. The following substatements 709 are commonly used with the default value, which would make the module 710 difficult to read if used everywhere they are allowed. 712 +--------------+---------------+ 713 | Statement | Default Value | 714 +--------------+---------------+ 715 | config | true | 716 | mandatory | false | 717 | max-elements | unbounded | 718 | min-elements | 0 | 719 | ordered-by | system | 720 | status | current | 721 | yin-element | false | 722 +--------------+---------------+ 724 Statement Defaults 726 4.5. Conditional Statements 728 A module may be conceptually partitioned in several ways, using the 729 'if-feature' and/or 'when' statements. 731 Data model designers need to carefully consider all modularity 732 aspects, including the use of YANG conditional statements. 734 If a data definition is optional, depending on server support for a 735 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 736 statement SHOULD be defined to indicate that the NETCONF or RESTCONF 737 capability is supported within the data model. 739 If any notification data, or any data definition, for a non- 740 configuration data node is not mandatory, then the server may or may 741 not be required to return an instance of this data node. If any 742 conditional requirements exist for returning the data node in a 743 notification payload or retrieval request, they MUST be documented 744 somewhere. For example, a 'when' or 'if-feature' statement could 745 apply to the data node, or the conditional requirements could be 746 explained in a 'description' statement within the data node or one of 747 its ancestors (if any). 749 If any 'if-feature' statements apply to a list node, then the same 750 'if-feature' statements MUST apply to any key leaf nodes for the 751 list. There MUST NOT be any 'if-feature' statements applied to any 752 key leaf that do not also apply to the parent list node. 754 There SHOULD NOT be any 'when' statements applied to a key leaf node. 755 It is possible that a 'when' statement for an ancestor node of a key 756 leaf will have the exact node-set result as the key leaf. In such a 757 case, the 'when' statement for the key leaf is redundant and SHOULD 758 be avoided. 760 4.6. XPath Usage 762 This section describes guidelines for using the XML Path Language 763 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 765 4.6.1. XPath Evaluation Contexts 767 YANG defines 5 separate contexts for evaluation of XPath statements: 769 1) The "running" datastore: collection of all YANG configuration data 770 nodes. The document root is the conceptual container, (e.g., 771 "config" in the "edit-config" operation), which is the parent of all 772 top-level data definition statements with a "config" statement value 773 of "true". 775 2) State data + the "running" datastore: collection of all YANG data 776 nodes. The document root is the conceptual container, parent of all 777 top-level data definition statements. 779 3) Notification: an event notification document. The document root 780 is the notification element. 782 4) RPC Input: The document root is the conceptual "input" node, which 783 is the parent of all RPC input parameter definitions. 785 5) RPC Output: The document root is the conceptual "output" node, 786 which is the parent of all RPC output parameter definitions. 788 Note that these XPath contexts cannot be mixed. For example, a 789 "when" statement in a notification context cannot reference 790 configuration data. 792 notification foo { 793 leaf mtu { 794 // NOT OK because when-stmt context is this notification 795 when "/if:interfaces/if:interface[name='eth0']"; 796 type leafref { 797 // OK because path-stmt has a different context 798 path "/if:interfaces/if:interface/if:mtu"; 799 } 800 } 801 } 803 It is especially important to consider the XPath evaluation context 804 for XPath expressions defined in groupings. An XPath expression 805 defined in a grouping may not be portable, meaning it cannot be used 806 in multiple contexts and produce proper results. 808 If the XPath expressions defined in a grouping are intended for a 809 particular context, then this context SHOULD be identified in the 810 "description" statement for the grouping. 812 4.6.2. Function Library 814 The 'position' and 'last' functions SHOULD NOT be used. This applies 815 to implicit use of the 'position' function as well (e.g., 816 '//chapter[42]'). A server is only required to maintain the relative 817 XML document order of all instances of a particular user-ordered list 818 or leaf-list. The 'position' and 'last' functions MAY be used if 819 they are evaluated in a context where the context node is a user- 820 ordered 'list' or 'leaf-list'. 822 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 823 present in YANG documents so this function has no meaning. The YANG 824 compiler SHOULD return an empty string for this function. 826 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 827 Expanded names in XPath are different than YANG. A specific 828 canonical representation of a YANG expanded name does not exist. 830 The 'lang' function SHOULD NOT be used. This function does not apply 831 to YANG because there is no 'lang' attribute set with the document. 832 The YANG compiler SHOULD return 'false' for this function. 834 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 835 functions SHOULD NOT be used if the argument is a node-set. If so, 836 the function result will be determined by the document order of the 837 node-set. Since this order can be different on each server, the 838 function results can also be different. Any function call that 839 implicitly converts a node-set to a string will also have this issue. 841 The 'local-name' function SHOULD NOT be used to reference local names 842 outside of the YANG module defining the must or when expression 843 containing the 'local-name' function. Example of a local-name 844 function that should not be used: 846 /*[local-name()='foo'] 848 4.6.3. Axes 850 The 'attribute' and 'namespace' axes are not supported in YANG, and 851 MAY be empty in a NETCONF or RESTCONF server implementation. 853 The 'preceding', and 'following' axes SHOULD NOT be used. These 854 constructs rely on XML document order within a NETCONF or RESTCONF 855 server configuration database, which may not be supported 856 consistently or produce reliable results across implementations. 857 Predicate expressions based on static node properties (e.g., element 858 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 859 instead. The 'preceding' and 'following' axes MAY be used if 860 document order is not relevant to the outcome of the expression 861 (e.g., check for global uniqueness of a parameter value). 863 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 864 however they MAY be used if document order is not relevant to the 865 outcome of the expression. 867 A server is only required to maintain the relative XML document order 868 of all instances of a particular user-ordered list or leaf-list. The 869 'preceding-sibling' and 'following-sibling' axes MAY be used if they 870 are evaluated in a context where the context node is a user-ordered 871 'list' or 'leaf-list'. 873 4.6.4. Types 875 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 876 be used within numeric or boolean expressions. There are boundary 877 conditions in which the translation from the YANG 64-bit type to an 878 XPath number can cause incorrect results. Specifically, an XPath 879 'double' precision floating point number cannot represent very large 880 positive or negative 64-bit numbers because it only provides a total 881 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 882 used in numeric expressions if the value can be represented with no 883 more than 53 bits of precision. 885 Data modelers need to be careful not to confuse the YANG value space 886 and the XPath value space. The data types are not the same in both, 887 and conversion between YANG and XPath data types SHOULD be considered 888 carefully. 890 Explicit XPath data type conversions MAY be used (e.g., 'string', 891 'boolean', or 'number' functions), instead of implicit XPath data 892 type conversions. 894 XPath expressions that contain a literal value representing a YANG 895 identity SHOULD always include the declared prefix of the module 896 where the identity is defined. 898 XPath expressions for 'when' statements SHOULD NOT reference the 899 context node or any descendant nodes of the context node. They MAY 900 reference descendant nodes if the 'when' statement is contained 901 within an 'augment' statement, and the referenced nodes are not 902 defined within the 'augment' statement. 904 Example: 906 augment "/rt:active-route/rt:input/rt:destination-address" { 907 when "rt:address-family='v4ur:ipv4-unicast'" { 908 description 909 "This augment is valid only for IPv4 unicast."; 910 } 911 // nodes defined here within the augment-stmt 912 // cannot be referenced in the when-stmt 913 } 915 4.6.5. Wildcards 917 It is possible to construct XPath expressions that will evaluate 918 differently when combined with several modules within a server 919 implementation, then when evaluated within the single module. This 920 is due to augmenting nodes from other modules. 922 Wildcard expansion is done within a server against all the nodes from 923 all namespaces, so it is possible for a 'must' or 'when' expression 924 that uses the '*' operator will always evaluate to false if processed 925 within a single YANG module. In such cases, the 'description' 926 statement SHOULD clarify that augmenting objects are expected to 927 match the wildcard expansion. 929 when /foo/services/*/active { 930 description 931 "No services directly defined in this module. 932 Matches objects that have augmented the services container."; 933 } 935 4.6.6. Boolean Expressions 937 The YANG "must" and "when" statements use an XPath boolean expression 938 to define the test condition for the statement. It is important to 939 specify these expressions in a way that will not cause inadvertent 940 changes in the result if the objects referenced in the expression are 941 updated in future revisions of the module. 943 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 944 to "one" or "three": 946 leaf foo1 { 947 type enumeration { 948 enum one; 949 enum two; 950 enum three; 951 } 952 } 954 leaf foo2 { 955 // INCORRECT 956 must "/f:foo1 != 'two'"; 957 type string; 958 } 960 leaf foo2 { 961 // CORRECT 962 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 963 type string; 964 } 966 In the next revision of the module, leaf "foo1" is extended with a 967 new enum named "four": 969 leaf foo1 { 970 type enumeration { 971 enum one; 972 enum two; 973 enum three; 974 enum four; 975 } 976 } 978 Now the first XPath expression will allow the enum "four" to be 979 accepted in addition to the "one" and "three" enum values. 981 4.7. Lifecycle Management 983 The status statement MUST be present if its value is 'deprecated' or 984 'obsolete'. The status SHOULD NOT be changed from 'current' directly 985 to 'obsolete'. An object SHOULD be available for at least one year 986 with 'deprecated' status before it is changed to 'obsolete'. 988 The module or submodule name MUST NOT be changed, once the document 989 containing the module or submodule is published. 991 The module namespace URI value MUST NOT be changed, once the document 992 containing the module is published. 994 The revision-date substatement within the import statement SHOULD be 995 present if any groupings are used from the external module. 997 The revision-date substatement within the include statement SHOULD be 998 present if any groupings are used from the external submodule. 1000 If submodules are used, then the document containing the main module 1001 MUST be updated so that the main module revision date is equal or 1002 more recent than the revision date of any submodule that is (directly 1003 or indirectly) included by the main module. 1005 Definitions for future use SHOULD NOT be specified in a module. Do 1006 not specify placeholder objects like the "reserved" example below: 1008 leaf reserved { 1009 type string; 1010 description 1011 "This object has no purpose at this time, but a future 1012 revision of this module might define a purpose 1013 for this object."; 1014 } 1015 } 1017 4.8. Module Header, Meta, and Revision Statements 1019 For published modules, the namespace MUST be a globally unique URI, 1020 as defined in [RFC3986]. This value is usually assigned by the IANA. 1022 The organization statement MUST be present. If the module is 1023 contained in a document intended for IETF Standards Track status, 1024 then the organization SHOULD be the IETF working group chartered to 1025 write the document. For other standards organizations, a similar 1026 approach is also suggested. 1028 The contact statement MUST be present. If the module is contained in 1029 a document intended for Standards Track status, then the working 1030 group web and mailing information MUST be present, and the main 1031 document author or editor contact information SHOULD be present. If 1032 additional authors or editors exist, their contact information MAY be 1033 present. 1035 The description statement MUST be present. For modules published 1036 within IETF documents, the appropriate IETF Trust Copyright text MUST 1037 be present, as described in Section 3.1. 1039 If the module relies on information contained in other documents, 1040 which are not the same documents implied by the import statements 1041 present in the module, then these documents MUST be identified in the 1042 reference statement. 1044 A revision statement MUST be present for each published version of 1045 the module. The revision statement MUST have a reference 1046 substatement. It MUST identify the published document that contains 1047 the module. Modules are often extracted from their original 1048 documents, and it is useful for developers and operators to know how 1049 to find the original source document in a consistent manner. The 1050 revision statement MAY have a description substatement. 1052 It is not required to keep the full revision history of draft 1053 versions (e.g., modules contained within Internet-Drafts). That is, 1054 within a sequence of draft versions, only the most recent revision 1055 need be recorded in the module. However, whenever a new (i.e. 1056 changed) version is made available (e.g., via a new version of an 1057 Internet-Draft), the revision date of that new version MUST be 1058 updated to a date later than that of the previous version. 1060 4.9. Namespace Assignments 1062 It is RECOMMENDED that only valid YANG modules be included in 1063 documents, whether or not they are published yet. This allows: 1065 o the module to compile correctly instead of generating disruptive 1066 fatal errors. 1068 o early implementors to use the modules without picking a random 1069 value for the XML namespace. 1071 o early interoperability testing since independent implementations 1072 will use the same XML namespace value. 1074 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1075 provided for the namespace statement in a YANG module. A value 1076 SHOULD be selected that is not likely to collide with other YANG 1077 namespaces. Standard module names, prefixes, and URI strings already 1078 listed in the YANG Module Registry MUST NOT be used. 1080 A standard namespace statement value SHOULD have the following form: 1082 : 1084 The following URN prefix string SHOULD be used for published and 1085 unpublished YANG modules: 1087 urn:ietf:params:xml:ns:yang: 1089 The following example URNs would be valid namespace statement values 1090 for Standards Track modules: 1092 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1094 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1096 urn:ietf:params:xml:ns:yang:ietf-netconf 1098 Note that a different URN prefix string SHOULD be used for non- 1099 Standards-Track modules. The string SHOULD be selected according to 1100 the guidelines in [RFC7950]. 1102 The following URIs exemplify what might be used by non Standards 1103 Track modules. Note that the domain "example.com" SHOULD be used by 1104 example modules in IETF drafts. 1106 Example URIs using URLs per RFC 3986 [RFC3986]: 1108 http://example.com/ns/example-interfaces 1110 http://example.com/ns/example-system 1112 Example URIs using tags per RFC 4151 [RFC4151]: 1114 tag:example.com,2017:example-interfaces 1116 tag:example.com,2017:example-system 1118 4.10. Top-Level Data Definitions 1120 The top-level data organization SHOULD be considered carefully, in 1121 advance. Data model designers need to consider how the functionality 1122 for a given protocol or protocol family will grow over time. 1124 The separation of configuration data and operational data SHOULD be 1125 considered carefully. It is sometimes useful to define separate top- 1126 level containers for configuration and non-configuration data. For 1127 some existing top-level data nodes, configuration data was not in 1128 scope, so only one container representing operational data was 1129 created. 1131 The number of top-level data nodes within a module SHOULD be 1132 minimized. It is often useful to retrieve related information within 1133 a single subtree. If data is too distributed, is becomes difficult 1134 to retrieve all at once. 1136 The names and data organization SHOULD reflect persistent 1137 information, such as the name of a protocol. The name of the working 1138 group SHOULD NOT be used because this may change over time. 1140 A mandatory database data definition is defined as a node that a 1141 client must provide for the database to be valid. The server is not 1142 required to provide a value. 1144 Top-level database data definitions MUST NOT be mandatory. If a 1145 mandatory node appears at the top level, it will immediately cause 1146 the database to be invalid. This can occur when the server boots or 1147 when a module is loaded dynamically at runtime. 1149 4.11. Data Types 1151 Selection of an appropriate data type (i.e., built-in type, existing 1152 derived type, or new derived type) is very subjective, and therefore 1153 few requirements can be specified on that subject. 1155 Data model designers SHOULD use the most appropriate built-in data 1156 type for the particular application. 1158 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1159 'int64') SHOULD NOT be used unless negative values are allowed for 1160 the desired semantics. 1162 4.11.1. Fixed Value Extensibility 1164 If the set of values is fixed and the data type contents are 1165 controlled by a single naming authority, then an enumeration data 1166 type SHOULD be used. 1168 leaf foo { 1169 type enumeration { 1170 enum one; 1171 enum two; 1172 } 1173 } 1175 If extensibility of enumerated values is required, then the 1176 'identityref' data type SHOULD be used instead of an enumeration or 1177 other built-in type. 1179 identity foo-type { 1180 description "Base for the extensible type"; 1181 } 1183 identity one { 1184 base f:foo-type; 1185 } 1186 identity two { 1187 base f:foo-type; 1188 } 1190 leaf foo { 1191 type identityref { 1192 base f:foo-type; 1193 } 1194 } 1196 Note that any module can declare an identity with base "foo-type" 1197 that is valid for the "foo" leaf. Identityref values are considered 1198 to be qualified names. 1200 4.11.2. Patterns and Ranges 1202 For string data types, if a machine-readable pattern can be defined 1203 for the desired semantics, then one or more pattern statements SHOULD 1204 be present. A single quoted string SHOULD be used to specify the 1205 pattern, since a double-quoted string can modify the content. 1207 The following typedef from [RFC6991] demonstrates the proper use of 1208 the "pattern" statement: 1210 typedef ipv4-address-no-zone { 1211 type inet:ipv4-address { 1212 pattern '[0-9\.]*'; 1213 } 1214 ... 1215 } 1217 For string data types, if the length of the string is required to be 1218 bounded in all implementations, then a length statement MUST be 1219 present. 1221 The following typedef from [RFC6991] demonstrates the proper use of 1222 the "length" statement: 1224 typedef yang-identifier { 1225 type string { 1226 length "1..max"; 1227 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1228 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1229 } 1230 ... 1231 } 1233 For numeric data types, if the values allowed by the intended 1234 semantics are different than those allowed by the unbounded intrinsic 1235 data type (e.g., 'int32'), then a range statement SHOULD be present. 1237 The following typedef from [RFC6991] demonstrates the proper use of 1238 the "range" statement: 1240 typedef dscp { 1241 type uint8 { 1242 range "0..63"; 1243 } 1244 ... 1245 } 1247 4.11.3. Enumerations and Bits 1249 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1250 or 'bit' SHOULD be documented. A separate description statement 1251 (within each 'enum' or 'bit' statement) SHOULD be present. 1253 leaf foo { 1254 // INCORRECT 1255 type enumeration { 1256 enum one; 1257 enum two; 1258 } 1259 description 1260 "The foo enum... 1261 one: The first enum 1262 two: The second enum"; 1263 } 1265 leaf foo { 1266 // CORRECT 1267 type enumeration { 1268 enum one { 1269 description "The first enum"; 1270 } 1271 enum two { 1272 description "The second enum"; 1273 } 1274 } 1275 description 1276 "The foo enum... "; 1277 } 1279 4.11.4. Union Types 1281 The YANG "union" type is evaluated by testing a value against each 1282 member type in the union. The first type definition that accepts a 1283 value as valid is the member type used. In general, member types 1284 SHOULD be ordered from most restrictive to least restrictive types. 1286 In the following example, the "enumeration" type will never be 1287 matched because the preceding "string" type will match everything. 1289 Incorrect: 1291 type union { 1292 type string; 1293 type enumeration { 1294 enum up; 1295 enum down; 1296 } 1297 } 1299 Correct: 1301 type union { 1302 type enumeration { 1303 enum up; 1304 enum down; 1305 } 1306 type string; 1307 } 1309 It is possible for different member types to match, depending on the 1310 input encoding format. In XML, all values are passed as string 1311 nodes, but in JSON there are different value types for numbers, 1312 booleans, and strings. 1314 In the following example, a JSON numeric value will always be matched 1315 by the "int32" type but in XML the string value representing a number 1316 will be matched by the "string" type. The second version will match 1317 the "int32" member type no matter how the input is encoded. 1319 Incorrect: 1321 type union { 1322 type string; 1323 type int32; 1324 } 1326 Correct: 1328 type union { 1329 type int32; 1330 type string; 1331 } 1333 4.11.5. Empty and Boolean 1335 YANG provides an "empty" data type, which has one value (i.e., 1336 present). The default is "not present", which is not actually a 1337 value. When used within a list key, only one value can (and must) 1338 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1339 key leaf since it is pointless. 1341 There is really no difference between a leaf of type "empty" and a 1342 leaf-list of type "empty". Both are limited to one instance. The 1343 type "empty" SHOULD NOT be used for a leaf-list. 1345 The advantage of using type "empty" instead of type "boolean" is that 1346 the default (not present) does not take up any bytes in a 1347 representation. The disadvantage is that the client may not be sure 1348 if an empty leaf is missing because it was filtered somehow or not 1349 implemented. The client may not have a complete and accurate schema 1350 for the data returned by the server, and not be aware of the missing 1351 leaf. 1353 The YANG "boolean" data type provides two values ("true" and 1354 "false"). When used within a list key, two entries can exist for 1355 this key leaf. Default values are ignored for key leafs, but a 1356 default statement is often used for plain boolean leafs. The 1357 advantage of the "boolean" type is that the leaf or leaf-list has a 1358 clear representation for both values. The default value is usually 1359 not returned unless explicitly requested by the client, so no bytes 1360 are used in a typical representation. 1362 In general, the "boolean" data type SHOULD be used instead of the 1363 "empty" data type, as shown in the example below: 1365 Incorrect: 1367 leaf flag1 { 1368 type empty; 1369 } 1371 Correct: 1373 leaf flag2 { 1374 type boolean; 1375 default false; 1376 } 1378 4.12. Reusable Type Definitions 1380 If an appropriate derived type exists in any standard module, such as 1381 [RFC6991], then it SHOULD be used instead of defining a new derived 1382 type. 1384 If an appropriate units identifier can be associated with the desired 1385 semantics, then a units statement SHOULD be present. 1387 If an appropriate default value can be associated with the desired 1388 semantics, then a default statement SHOULD be present. 1390 If a significant number of derived types are defined, and it is 1391 anticipated that these data types will be reused by multiple modules, 1392 then these derived types SHOULD be contained in a separate module or 1393 submodule, to allow easier reuse without unnecessary coupling. 1395 The description statement MUST be present. 1397 If the type definition semantics are defined in an external document 1398 (other than another YANG module indicated by an import statement), 1399 then the reference statement MUST be present. 1401 4.13. Reusable Groupings 1403 A reusable grouping is a YANG grouping that can be imported by 1404 another module, and is intended for use by other modules. This is 1405 not the same as a grouping that is used within the module it is 1406 defined, but happens to be exportable to another module because it is 1407 defined at the top-level of the YANG module. 1409 The following guidelines apply to reusable groupings, in order to 1410 make them as robust as possible: 1412 o Clearly identify the purpose of the grouping in the "description" 1413 statement. 1415 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1416 output, notification, config=true data nodes, and all data nodes). 1417 Clearly identify which XPath contexts are applicable or excluded 1418 for the grouping. 1420 o Do not reference data outside the grouping in any "path", "must", 1421 or "when" statements. 1423 o Do not include a "default" sub-statement on a leaf or choice 1424 unless the value applies on all possible contexts. 1426 o Do not include a "config" sub-statement on a data node unless the 1427 value applies on all possible contexts. 1429 o Clearly identify any external dependencies in the grouping 1430 "description" statement, such as nodes referenced by absolute path 1431 from a "path", "must", or "when" statement. 1433 4.14. Data Definitions 1435 The description statement MUST be present in the following YANG 1436 statements: 1438 o anyxml 1440 o augment 1442 o choice 1443 o container 1445 o extension 1447 o feature 1449 o grouping 1451 o identity 1453 o leaf 1455 o leaf-list 1457 o list 1459 o notification 1461 o rpc 1463 o typedef 1465 If the data definition semantics are defined in an external document, 1466 (other than another YANG module indicated by an import statement), 1467 then a reference statement MUST be present. 1469 The 'anyxml' construct may be useful to represent an HTML banner 1470 containing markup elements, such as '<b>' and '</b>', and 1471 MAY be used in such cases. However, this construct SHOULD NOT be 1472 used if other YANG data node types can be used instead to represent 1473 the desired syntax and semantics. 1475 It has been found that the 'anyxml' statement is not implemented 1476 consistently across all servers. It is possible that mixed mode XML 1477 will not be supported, or configuration anyxml nodes will not 1478 supported. 1480 If there are referential integrity constraints associated with the 1481 desired semantics that can be represented with XPath, then one or 1482 more 'must' statements SHOULD be present. 1484 For list and leaf-list data definitions, if the number of possible 1485 instances is required to be bounded for all implementations, then the 1486 max-elements statements SHOULD be present. 1488 If any 'must' or 'when' statements are used within the data 1489 definition, then the data definition description statement SHOULD 1490 describe the purpose of each one. 1492 The "choice" statement is allowed to be directly present within a 1493 "case" statement in YANG 1.1. This needs to be considered carefully. 1494 Consider simply including the nested "choice" as additional "case" 1495 statements within the parent "choice" statement. Note that the 1496 "mandatory" and "default" statements within a nested "choice" 1497 statement only apply if the "case" containing the nested "choice" 1498 statement is first selected. 1500 4.14.1. Non-Presence Containers 1502 A non-presence container is used to organize data into specific 1503 subtrees. It is not intended to have semantics within the data model 1504 beyond this purpose, although YANG allows it (e.g., "must" statement 1505 within the non-presence container). 1507 Example using container wrappers: 1509 container top { 1510 container foos { 1511 list foo { ... } 1512 } 1513 container bars { 1514 list bar { ... } 1515 } 1516 } 1518 Example without container wrappers: 1520 container top { 1521 list foo { ... } 1522 list bar { ... } 1523 } 1525 Use of non-presence containers to organize data is a subjective 1526 matter similar to use of sub-directories in a file system. The 1527 NETCONF and RESTCONF protocols do not currently support the ability 1528 to delete all list (or leaf-list) entries at once. This deficiency 1529 is sometimes avoided by use of a parent container (i.e., deleting the 1530 container also removes all child entries). 1532 4.14.2. Top-Level Data Nodes 1534 Use of top-level objects needs to be considered carefully 1536 -top-level siblings are not ordered -top-level siblings not are not 1537 static, and depends on the modules that are loaded 1538 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1539 treated as a content-match node for all top-level-siblings 1541 o a top-level list with many instances may impact performance 1543 4.15. Operation Definitions 1545 If the operation semantics are defined in an external document (other 1546 than another YANG module indicated by an import statement), then a 1547 reference statement MUST be present. 1549 If the operation impacts system behavior in some way, it SHOULD be 1550 mentioned in the description statement. 1552 If the operation is potentially harmful to system behavior in some 1553 way, it MUST be mentioned in the Security Considerations section of 1554 the document. 1556 4.16. Notification Definitions 1558 The description statement MUST be present. 1560 If the notification semantics are defined in an external document 1561 (other than another YANG module indicated by an import statement), 1562 then a reference statement MUST be present. 1564 If the notification refers to a specific resource instance, then this 1565 instance SHOULD be identified in the notification data. This is 1566 usually done by including 'leafref' leaf nodes with the key leaf 1567 values for the resource instance. For example: 1569 notification interface-up { 1570 description "Sent when an interface is activated."; 1571 leaf name { 1572 type leafref { 1573 path "/if:interfaces/if:interface/if:name"; 1574 } 1575 } 1576 } 1578 Note that there are no formal YANG statements to identify any data 1579 node resources associated with a notification. The description 1580 statement for the notification SHOULD specify if and how the 1581 notification identifies any data node resources associated with the 1582 specific event. 1584 4.17. Feature Definitions 1586 The YANG "feature" statement is used to define a label for a set of 1587 optional functionality within a module. The "if-feature" statement 1588 is used in the YANG statements associated with a feature. 1590 The set of YANG features available in a module should be considered 1591 carefully. The description-stmt within a feature-stmt MUST specify 1592 any interactions with other features. 1594 If there is a large set of objects associated with a YANG feature, 1595 then consider moving those objects to a separate module, instead of 1596 using a YANG feature. Note that the set of features within a module 1597 is easily discovered by the reader, but the set of related modules 1598 within the entire YANG library is not as easy to identity. Module 1599 names with a common prefix can help readers identity the set of 1600 related modules, but this assumes the reader will have discovered and 1601 installed all the relevant modules. 1603 Another consideration for deciding whether to create a new module or 1604 add a YANG feature is the stability of the module in question. It 1605 may be desirable to have a stable base module that is not changed 1606 frequently. If new functionality is placed in a separate module, 1607 then the base module does not need to be republished. If it is 1608 designed as a YANG feature then the module will need to be 1609 republished. 1611 If one feature requires implementation of another feature, then an 1612 "if-feature" statement SHOULD be used in the dependent "feature" 1613 statement. 1615 For example, feature2 requires implementation of feature1: 1617 feature feature1 { 1618 description "Some protocol feature"; 1619 } 1621 feature feature2 { 1622 if-feature "feature1"; 1623 description "Another protocol feature"; 1624 } 1626 4.18. YANG Data Node Constraints 1628 4.18.1. Controlling Quantity 1630 The "min-elements" and "max-elements" statements can be use to 1631 control how many list or leaf-list instances are required for a 1632 particular data node. YANG constraint statements SHOULD be used to 1633 identify conditions that apply to all implementations of the data 1634 model. If platform-specific limitations (e.g., the "max-elements" 1635 supported for a particular list) are relevant to operations, then a 1636 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1637 used to identify the limit. 1639 4.18.2. must vs. when 1641 The "must" and "when" YANG statements are used to provide cross- 1642 object referential tests. They have very different behavior. The 1643 "when" statement causes data node instances to be silently deleted as 1644 soon as the condition becomes false. A false "when" expression is 1645 not considered to be an error. 1647 The "when" statement SHOULD be used together with the "augment" or 1648 "uses" statements to achieve conditional model composition. The 1649 condition SHOULD be based on static properties of the augmented entry 1650 (e.g., list key leafs). 1652 The "must" statement causes a datastore validation error if the 1653 condition is false. This statement SHOULD be used for enforcing 1654 parameter value restrictions that involve more than one data node 1655 (e.g., end-time parameter must be after the start-time parameter). 1657 4.19. Augment Statements 1659 The YANG "augment" statement is used to define a set of data 1660 definition statements that will be added as child nodes of a target 1661 data node. The module namespace for these data nodes will be the 1662 augmenting module, not the augmented module. 1664 A top-level "augment" statement SHOULD NOT be used if the target data 1665 node is in the same module or submodule as the evaluated "augment" 1666 statement. The data definition statements SHOULD be added inline 1667 instead. 1669 4.19.1. Conditional Augment Statements 1671 The "augment" statement is often used together with the "when" 1672 statement and/or "if-feature" statement to make the augmentation 1673 conditional on some portion of the data model. 1675 The following example from [RFC7223] shows how a conditional 1676 container called "ethernet" is added to the "interface" list only for 1677 entries of the type "ethernetCsmacd". 1679 augment "/if:interfaces/if:interface" { 1680 when "if:type = 'ianaift:ethernetCsmacd'"; 1682 container ethernet { 1683 leaf duplex { 1684 ... 1685 } 1686 } 1687 } 1689 4.19.2. Conditionally Mandatory Data Definition Statements 1691 YANG has very specific rules about how configuration data can be 1692 updated in new releases of a module. These rules allow an "old 1693 client" to continue interoperating with a "new server". 1695 If data nodes are added to an existing entry, the old client MUST NOT 1696 be required to provide any mandatory parameters that were not in the 1697 original module definition. 1699 It is possible to add conditional augment statements such that the 1700 old client would not know about the new condition, and would not 1701 specify the new condition. The conditional augment statement can 1702 contain mandatory objects only if the condition is false unless 1703 explicitly requested by the client. 1705 Only a conditional augment statement that uses the "when" statement 1706 form of condition can be used in this manner. The YANG features 1707 enabled on the server cannot be controlled by the client in any way, 1708 so it is not safe to add mandatory augmenting data nodes based on the 1709 "if-feature" statement. 1711 The XPath "when" statement condition MUST NOT reference data outside 1712 of target data node because the client does not have any control over 1713 this external data. 1715 In the following dummy example, it is OK to augment the "interface" 1716 entry with "mandatory-leaf" because the augmentation depends on 1717 support for "some-new-iftype". The old client does not know about 1718 this type so it would never select this type, and therefore not be 1719 adding a mandatory data node. 1721 module example-module { 1722 namespace "http://example.com/ns/example-module"; 1723 prefix mymod; 1725 import iana-if-type { prefix iana; } 1726 import ietf-interfaces { prefix if; } 1728 identity some-new-iftype { 1729 base iana:iana-interface-type; 1730 } 1732 augment "/if:interfaces/if:interface" { 1733 when "if:type = 'mymod:some-new-iftype'"; 1735 leaf mandatory-leaf { 1736 mandatory true; 1737 ... 1738 } 1739 } 1740 } 1742 Note that this practice is safe only for creating data resources. It 1743 is not safe for replacing or modifying resources if the client does 1744 not know about the new condition. The YANG data model MUST be 1745 packaged in a way that requires the client to be aware of the 1746 mandatory data nodes if it is aware of the condition for this data. 1747 In the example above, the "some-new-iftype" identity is defined in 1748 the same module as the "mandatory-leaf" data definition statement. 1750 This practice is not safe for identities defined in a common module 1751 such as "iana-if-type" because the client is not required to know 1752 about "my-module" just because it knows about the "iana-if-type" 1753 module. 1755 4.20. Deviation Statements 1757 The YANG "deviation" statement cannot appear in IETF YANG modules, 1758 but it can be useful for documenting server capabilities. Deviation 1759 statements are not reusable and typically not shared across all 1760 platforms. 1762 There are several reasons that deviations might be needed in an 1763 implementation, e.g., an object cannot be supported on all platforms, 1764 or feature delivery is done in multiple development phases. 1765 Deviation statements can also be used to add annotations to a module, 1766 which does not affect the conformance requirements for the module. 1768 It is suggested that deviation statements be defined in separate 1769 modules from regular YANG definitions. This allows the deviations to 1770 be platform-specific and/or temporary. 1772 The order that deviation statements are evaluated can affect the 1773 result. Therefore multiple deviation statements in the same module, 1774 for the same target object, SHOULD NOT be used. 1776 The "max-elements" statement is intended to describe an architectural 1777 limit to the number of list entries. It is not intended to describe 1778 platform limitations. It is better to use a "deviation" statement 1779 for the platforms that have a hard resource limit. 1781 Example documenting platform resource limits: 1783 Wrong: (max-elements in the list itself) 1785 container backups { 1786 list backup { 1787 ... 1788 max-elements 10; 1789 ... 1790 } 1791 } 1793 Correct: (max-elements in a deviation) 1795 deviation /bk:backups/bk:backup { 1796 deviate add { 1797 max-elements 10; 1798 } 1799 } 1801 4.21. Extension Statements 1803 The YANG "extension" statement is used to specify external 1804 definitions. This appears in the YANG syntax as an 1805 "unknown-statement". Usage of extension statements in a published 1806 module needs to be considered carefully. 1808 The following guidelines apply to the usage of YANG extensions: 1810 o The semantics of the extension MUST NOT contradict any YANG 1811 statements. Extensions can add semantics not covered by the 1812 normal YANG statements. 1814 o The module containing the extension statement MUST clearly 1815 identify the conformance requirements for the extension. It 1816 should be clear whether all implementations of the YANG module 1817 containing the extension need to also implement the extension. If 1818 not, identify what conditions apply that would require 1819 implementation of the extension. 1821 o The extension MUST clearly identify where it can be used within 1822 other YANG statements. 1824 o The extension MUST clearly identify if YANG statements or other 1825 extensions are allowed or required within the extension as sub- 1826 statements. 1828 4.22. Data Correlation 1830 Data can be correlated in various ways, using common data types, 1831 common data naming, and common data organization. There are several 1832 ways to extend the functionality of a module, based on the degree of 1833 coupling between the old and new functionality: 1835 o inline: update the module with new protocol-accessible objects. 1836 The naming and data organization of the original objects is used. 1837 The new objects are in the original module namespace. 1839 o augment: create a new module with new protocol-accessible objects 1840 that augment the original data structure. The naming and data 1841 organization of the original objects is used. The new objects are 1842 in the new module namespace. 1844 o mirror: create new objects in a new module or the original module, 1845 except use new a naming scheme and data location. The naming can 1846 be coupled in different ways. Tight coupling is achieved with a 1847 "leafref" data type, with the "require-instance" sub-statement set 1848 to "true". This method SHOULD be used. 1850 If the new data instances are not limited to the values in use in the 1851 original data structure, then the "require-instance" sub-statement 1852 MUST be set to "false". Loose coupling is achieved by using key 1853 leafs with the same data type as the original data structure. This 1854 has the same semantics as setting the "require-instance" sub- 1855 statement to "false". 1857 It is sometimes useful to separate configuration and operational 1858 data, so that they do not not even share the exact same naming 1859 characteristics. The correlation between configuration the 1860 operational data that is affected by changes in configuration is a 1861 complex problem. There may not be a simple 1:1 relationship between 1862 a configuration data node and an operational data node. Further work 1863 is needed in YANG to clarify this relationship. Protocol work may 1864 also be needed to allow a client to retrieve this type of information 1865 from a server. At this time the best practice is to clearly document 1866 any relationship to other data structures in the "description" 1867 statement. 1869 4.22.1. Use of Leafref for Key Correlation 1871 Sometimes it is not practical to augment a data structure. For 1872 example, the correlated data could have different keys or contain 1873 mandatory nodes. 1875 The following example shows the use of the "leafref" data type for 1876 data correlation purposes: 1878 Not preferred: 1880 list foo { 1881 key name; 1882 leaf name { 1883 type string; 1884 } 1885 ... 1886 } 1888 list foo-addon { 1889 key name; 1890 config false; 1891 leaf name { 1892 type string; 1893 } 1894 ... 1895 } 1897 Preferred: 1899 list foo { 1900 key name; 1901 leaf name { 1902 type string; 1903 } 1904 ... 1905 } 1907 list foo-addon { 1908 key name; 1909 config false; 1910 leaf name { 1911 type leafref { 1912 path "/foo/name"; 1913 require-instance false; 1914 } 1915 } 1916 leaf addon { 1917 type string; 1918 mandatory true; 1919 } 1920 } 1922 4.23. Operational Data 1924 In YANG, any data that has a "config" statement value of "false" 1925 could be considered operational data. The relationship between 1926 configuration (i.e., "config" statement has a value of "true") and 1927 operational data can be complex. 1929 The original set of datastores defined in NETCONF (i.e., candidate, 1930 running, and startup) are not sufficient to fully manage a device 1931 with multiple sources of configuration data. In additional, a 1932 separate datastore is needed to store operational state and other 1933 data such as statistics. Refer to 1934 [I-D.ietf-netmod-revised-datastores] for details on this new "revised 1935 datastore" architecture. Guidelines for usage of the new datastores 1936 (including the operational datastore) is defined in 1937 [I-D.dsdt-nmda-guidelines]. 1939 4.24. Performance Considerations 1941 It is generally likely that certain YANG statements require more 1942 runtime resources than other statements. Although there are no 1943 performance requirements for YANG validation, the following 1944 information MAY be considered when designing YANG data models: 1946 o Lists are generally more expensive than containers 1948 o "when-stmt" evaluation is generally more expensive than 1949 "if-feature" or "choice" statements 1951 o "must" statement is generally more expensive than "min-entries", 1952 "max-entries", "mandatory", or "unique" statements 1954 o "identityref" leafs are generally more expensive than 1955 "enumeration" leafs 1957 o "leafref" and "instance-identifier" types with "require-instance" 1958 set to true are generally more expensive than if 1959 "require-instance" is set to false 1961 4.25. Open Systems Considerations 1963 A YANG module MUST NOT be designed such that the set of modules found 1964 on a server implementation can be predetermined in advance. Only the 1965 modules imported by a particular module can be assumed to be present 1966 in an implementation. An open system MAY include any combination of 1967 YANG modules. 1969 4.26. YANG 1.1 Guidelines 1971 The set of YANG 1.1 guidelines will grow as operational experience is 1972 gained with the new language features. This section contains an 1973 initial set of guidelines. 1975 4.26.1. Importing Multiple Revisions 1977 Standard modules SHOULD NOT import multiple revisions of the same 1978 module into a module. This MAY be done if the authors can 1979 demonstrate that the "avoided" definitions from the most recent of 1980 the multiple revisions are somehow broken or harmful to 1981 interoperability. 1983 4.26.2. Using Feature Logic 1985 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 1986 "description" statement SHOULD describe the "if-feature" logic in 1987 text, to help readers understand the module. 1989 YANG features SHOULD be used instead of the "when" statement, if 1990 possible. Features are advertised by the server and objects 1991 conditional by if-feature are conceptually grouped together. There 1992 is no such commonality supported for "when" statements. 1994 Features generally require less server implementation complexity and 1995 runtime resources than objects that use "when" statements. Features 1996 are generally static (i.e., set when module is loaded and not changed 1997 at runtime). However every client edit might cause a "when" 1998 statement result to change. 2000 4.26.3. anyxml vs. anydata 2002 The "anyxml" statement MUST NOT be used to represent a conceptual 2003 subtree of YANG data nodes. The "anydata" statement MUST be used for 2004 this purpose. 2006 4.26.4. action vs. rpc 2008 The use of "action" statements or "rpc" statements is a subjective 2009 design decision. RPC operations are not associated with any 2010 particular data node. Actions are associated with a specific data 2011 node definition. An "action" statement SHOULD be used if the 2012 protocol operation is specific to a subset of all data nodes instead 2013 of all possible data nodes. 2015 The same action name MAY be used in different definitions within 2016 different data node. For example, a "reset" action defined with a 2017 data node definition for an interface might have different parameters 2018 than for a power supply or a VLAN. The same action name SHOULD be 2019 used to represent similar semantics. 2021 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2022 parameter access control for RPC operations. The user is given 2023 permission (or not) to invoke the RPC operation with any parameters. 2024 For example, if each client is only allowed to reset their own 2025 interface, then NACM cannot be used. 2027 For example, NACM cannot enforce access access control based on the 2028 value of the "interface" parameter, only the "reset" operation 2029 itself: 2031 rpc reset { 2032 input { 2033 leaf interface { 2034 type if:interface-ref; 2035 mandatory true; 2036 description "The interface to reset."; 2037 } 2038 } 2039 } 2041 However, NACM can enforce access access control for individual 2042 interface instances, using a "reset" action, If the user does not 2043 have read access to the specific "interface" instance, then it cannot 2044 invoke the "reset" action for that interface instance: 2046 container interfaces { 2047 list interface { 2048 ... 2049 action reset { } 2050 } 2051 } 2053 4.27. Updating YANG Modules (Published vs. Unpublished) 2055 YANG modules can change over time. Typically, new data model 2056 definitions are needed to support new features. YANG update rules 2057 defined in section 11 of [RFC7950] MUST be followed for published 2058 modules. They MAY be followed for unpublished modules. 2060 The YANG update rules only apply to published module revisions. Each 2061 organization will have their own way to identify published work which 2062 is considered to be stable, and unpublished work which is considered 2063 to be unstable. For example, in the IETF, the RFC document is used 2064 for published work, and the Internet-Draft is used for unpublished 2065 work. 2067 5. IANA Considerations 2069 -- RFC Ed: These registries need to be updated to reference this 2070 RFC instead of RFC 6087 for the ietf-template module, and 2071 remove this note. 2073 This document registers one URI in the IETF XML registry [RFC3688]. 2075 The following registration has been made in [RFC6087] and updated by 2076 this document. 2078 URI: urn:ietf:params:xml:ns:yang:ietf-template 2080 Registrant Contact: The NETMOD WG of the IETF. 2082 XML: N/A, the requested URI is an XML namespace. 2084 The following assignment has been made in [RFC6087] and updated by 2085 this document in the YANG Module Names Registry, or the YANG module 2086 template in Appendix C. 2088 +-----------+-------------------------------------------+ 2089 | Field | Value | 2090 +-----------+-------------------------------------------+ 2091 | Name | ietf-template | 2092 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2093 | Prefix | temp | 2094 | Reference | RFC XXXX | 2095 +-----------+-------------------------------------------+ 2097 YANG Registry Assignment 2099 6. Security Considerations 2101 This document defines documentation guidelines for NETCONF or 2102 RESTCONF content defined with the YANG data modeling language. The 2103 guidelines for how to write a Security Considerations section for a 2104 YANG module are defined in the online document 2106 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2107 yang-security-guidelines 2109 This document does not introduce any new or increased security risks 2110 into the management system. 2112 The following section contains the security considerations template 2113 dated 2010-06-16. Be sure to check the webpage at the URL listed 2114 above in case there is a more recent version available. 2116 Each specification that defines one or more YANG modules MUST contain 2117 a section that discusses security considerations relevant to those 2118 modules. This section MUST be patterned after the latest approved 2119 template (available at 2121 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2123 In particular, writable data nodes that could be especially 2124 disruptive if abused MUST be explicitly listed by name and the 2125 associated security risks MUST be spelled out. 2127 Similarly, readable data nodes that contain especially sensitive 2128 information or that raise significant privacy concerns MUST be 2129 explicitly listed by name and the reasons for the sensitivity/privacy 2130 concerns MUST be explained. 2132 Further, if new RPC operations have been defined, then the security 2133 considerations of each new RPC operation MUST be explained. 2135 6.1. Security Considerations Section Template 2137 X. Security Considerations 2139 The YANG module defined in this memo is designed to be accessed via 2140 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2141 secure transport layer and the mandatory-to-implement secure 2142 transport is SSH [RFC6242]. 2144 -- if you have any writable data nodes (those are all the 2145 -- "config true" nodes, and remember, that is the default) 2146 -- describe their specific sensitivity or vulnerability. 2148 There are a number of data nodes defined in this YANG module which 2149 are writable/creatable/deletable (i.e., config true, which is the 2150 default). These data nodes may be considered sensitive or vulnerable 2151 in some network environments. Write operations (e.g., edit-config) 2152 to these data nodes without proper protection can have a negative 2153 effect on network operations. These are the subtrees and data nodes 2154 and their sensitivity/vulnerability: 2156 2158 -- for all YANG modules you must evaluate whether any readable data 2159 -- nodes (those are all the "config false" nodes, but also all other 2160 -- nodes, because they can also be read via operations like get or 2161 -- get-config) are sensitive or vulnerable (for instance, if they 2162 -- might reveal customer information or violate personal privacy 2163 -- laws such as those of the European Union if exposed to 2164 -- unauthorized parties) 2166 Some of the readable data nodes in this YANG module may be considered 2167 sensitive or vulnerable in some network environments. It is thus 2168 important to control read access (e.g., via get, get-config, or 2169 notification) to these data nodes. These are the subtrees and data 2170 nodes and their sensitivity/vulnerability: 2172 2174 -- if your YANG module has defined any rpc operations 2175 -- describe their specific sensitivity or vulnerability. 2177 Some of the RPC operations in this YANG module may be considered 2178 sensitive or vulnerable in some network environments. It is thus 2179 important to control access to these operations. These are the 2180 operations and their sensitivity/vulnerability: 2182 2184 7. Acknowledgments 2186 The structure and contents of this document are adapted from 2187 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2189 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2190 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 2191 contributions to this document. 2193 8. Changes Since RFC 6087 2195 The following changes have been made to the guidelines published in 2196 [RFC6087]: 2198 o Updated NETCONF reference from RFC 4741 to RFC 6241 2200 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2202 o Updated YANG Types reference from RFC 6021 to RFC 6991 2204 o Updated obsolete URLs for IETF resources 2206 o Changed top-level data node guideline 2208 o Clarified XPath usage for a literal value representing a YANG 2209 identity 2211 o Clarified XPath usage for a when-stmt 2213 o Clarified XPath usage for 'proceeding-sibling' and 2214 'following-sibling' axes 2216 o Added terminology guidelines 2218 o Added YANG tree diagram definition and guideline 2220 o Updated XPath guidelines for type conversions and function library 2221 usage. 2223 o Updated data types section 2225 o Updated notifications section 2227 o Clarified conditional key leaf nodes 2229 o Clarify usage of 'uint64' and 'int64' data types 2231 o Added text on YANG feature usage 2233 o Added Identifier Naming Conventions 2235 o Clarified use of mandatory nodes with conditional augmentations 2237 o Clarified namespace and domain conventions for example modules 2239 o Clarified conventions for identifying code components 2240 o Added YANG 1.1 guidelines 2242 o Added Data Model Constraints section 2244 o Added mention of RESTCONF protocol 2246 o Added mention of Revised Datastores and associated guidelines 2248 9. References 2250 9.1. Normative References 2252 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2253 Requirement Levels", BCP 14, RFC 2119, March 1997. 2255 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2256 January 2004. 2258 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2259 Resource Identifier (URI): Generic Syntax", STD 66, 2260 RFC 3986, January 2005. 2262 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2263 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2265 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2266 Network Configuration Protocol (NETCONF)", RFC 6020, 2267 October 2010. 2269 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2270 July 2013. 2272 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2273 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2274 . 2276 [W3C.REC-xpath-19991116] 2277 Clark, J. and S. DeRose, "XML Path Language (XPath) 2278 Version 1.0", World Wide Web Consortium 2279 Recommendation REC-xpath-19991116, November 1999, 2280 . 2282 9.2. Informative References 2284 [I-D.dsdt-nmda-guidelines] 2285 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2286 and R. Wilton, "Guidelines for YANG Module Authors 2287 (NMDA)", draft-dsdt-nmda-guidelines-01 (work in progress), 2288 May 2017. 2290 [I-D.ietf-netmod-revised-datastores] 2291 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2292 and R. Wilton, "Network Management Datastore 2293 Architecture", draft-ietf-netmod-revised-datastores-02 2294 (work in progress), May 2017. 2296 [I-D.ietf-netmod-yang-tree-diagrams] 2297 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2298 draft-ietf-netmod-yang-tree-diagrams-00 (work in 2299 progress), June 2017. 2301 [RFC-STYLE] 2302 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2303 Style", September 2009, 2304 . 2306 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2307 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2308 . 2310 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2311 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2312 . 2314 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2315 Documents", BCP 111, RFC 4181, September 2005. 2317 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2318 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2319 May 2008. 2321 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2322 Data Model Documents", RFC 6087, January 2011. 2324 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2325 and A. Bierman, Ed., "Network Configuration Protocol 2326 (NETCONF)", RFC 6241, June 2011. 2328 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2329 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2330 . 2332 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2333 Protocol (NETCONF) Access Control Model", RFC 6536, 2334 March 2012. 2336 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2337 Management", RFC 7223, May 2014. 2339 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2340 DOI 10.17487/RFC7322, September 2014, 2341 . 2343 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2344 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2345 DOI 10.17487/RFC7841, May 2016, 2346 . 2348 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2349 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2350 . 2352 Appendix A. Change Log 2354 -- RFC Ed.: remove this section before publication. 2356 A.1. v12 to v13 2358 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2359 YANG file extraction macro. 2361 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2362 module name registries. 2364 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2366 o Update Operation Data section to consider revised datastores. 2368 o Add reference to YANG Tree Diagrams and update 2 sections that use 2369 this reference. 2371 o Add reference to Revised Datastores and guidelines drafts 2373 A.2. v11 to v12 2375 o fix incorrect location of new Module Usage Examples section 2377 A.3. v10 to v11 2379 o updated YANG tree diagram syntax to align with pyang 1.7.1 2381 o added general guideline to include module usage examples 2383 A.4. v09 to v10 2385 o clarified is only for normative modules 2387 o clarified example module namespace URI conventions 2389 o clarified pyang usage for normative and example modules 2391 o updated YANG tree diagrams section with text from RFC 8022 2393 A.5. v08 to v09 2395 o fixed references 2397 o added mention of RESTCONF to abstract and intro 2398 o created separate section for code components 2400 o fixed document status 2402 A.6. v07 to v08 2404 o changed CODE BEGINS guideline for example modules 2406 o updated tree diagram guidelines 2408 o clarified published and unpublished terms 2410 o added section on Empty and Boolean data types 2412 o clarified how to update the revision statement 2414 o updated operational state guidelines 2416 o added 'YANG fragment' to terminology section 2418 A.7. v06 to v07 2420 o update contact statement guideline 2422 o update example modules guidelines 2424 o add guidelines on top-level data nodes 2426 o add guideline on use of NP containers 2428 o added guidelines on union types 2430 o add guideline on deviations 2432 o added section on open systems considerations 2434 o added guideline about definitions reserved for future use 2436 A.8. v05 to v06 2438 o Changed example 'my-module' to 'example-module' 2440 o Added section Updating YANG Modules (Published vs. Unpublished) 2442 o Added Example Modules section 2444 o Added "" convention for full example modules 2445 o Added section on using action vs. rpc 2447 o Changed term "operational state" to "operational data" 2449 o Added section on YANG Data Node Constraints 2451 o Added guidelines on using must vs. when statements 2453 o Made ietf-foo module validate for I-D submission 2455 A.9. v04 to v05 2457 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2458 no YANG 1.1 features needed 2460 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2461 standards track documents only) 2463 o Clarified module naming conventions for normative modules, example 2464 modules, and modules from other SDOs. 2466 o Added prefix value selection guidelines 2468 o Added new section on guidelines for reusable groupings 2470 o Made header guidelines less IETF-specific 2472 o Added new section on guidelines for extension statements 2474 o Added guidelines for nested "choice" statement within a "case" 2475 statement 2477 A.10. v03 ot v04 2479 o Added sections for deviation statements and performance 2480 considerations 2482 o Added YANG 1.1 section 2484 o Updated YANG reference from 1.0 to 1.1 2486 A.11. v02 to v03 2488 o Updated draft based on github data tracker issues added by Benoit 2489 Clause (Issues 12 - 18) 2491 A.12. v01 to v02 2493 o Updated draft based on mailing list comments. 2495 A.13. v00 to v01 2497 All issues from the issue tracker have been addressed. 2499 https://github.com/netmod-wg/rfc6087bis/issues 2501 o Issue 1: Tree Diagrams: Added Section 2.4.1 so RFCs with YANG 2502 modules can use an Informative reference to this RFC for tree 2503 diagrams. Updated guidelines to reference this RFC when tree 2504 diagrams are used 2506 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2507 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2508 functions 2510 o Issue 3: XPath function document order issues: Added paragraph in 2511 XPath usage section about node-set ordering for 'local-name', 2512 'namespace-uri', 'name', 'string' and 'number' functions. Also 2513 any function that implicitly converts a node-set to a string. 2515 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2516 and text in XPath usage section already has proposed text from 2517 Lada. 2519 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2520 exception and example in XPath Usage section for augmented nodes. 2522 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2523 to 'numeric and boolean expressions' 2525 o Issue 7: XPath module containment: Added sub-section on XPath 2526 wildcards 2528 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2529 section about transitioning from active to deprecated and then to 2530 obsolete. 2532 o Issue 9: resource identification in notifications: Add text to 2533 Notifications section about identifying resources and using the 2534 leafref data type. 2536 o Issue 10: single quoted strings: Added text to Data Types section 2537 about using a single-quoted string for patterns. 2539 Appendix B. Module Review Checklist 2541 This section is adapted from RFC 4181. 2543 The purpose of a YANG module review is to review the YANG module both 2544 for technical correctness and for adherence to IETF documentation 2545 requirements. The following checklist may be helpful when reviewing 2546 an Internet-Draft: 2548 o I-D Boilerplate -- verify that the draft contains the required 2549 Internet-Draft boilerplate (see 2550 http://www.ietf.org/id-info/guidelines.html), including the 2551 appropriate statement to permit publication as an RFC, and that 2552 I-D boilerplate does not contain references or section numbers. 2554 o Abstract -- verify that the abstract does not contain references, 2555 that it does not have a section number, and that its content 2556 follows the guidelines in 2557 http://www.ietf.org/id-info/guidelines.html. 2559 o Copyright Notice -- verify that the draft has the appropriate text 2560 regarding the rights that document contributers provide to the 2561 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2562 copyright notice at the beginning of the document. The IETF Trust 2563 Legal Provisions (TLP) can be found at: 2565 http://trustee.ietf.org/license-info/ 2567 o Security Considerations section -- verify that the draft uses the 2568 latest approved template from the OPS area website (http:// 2569 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2570 and that the guidelines therein have been followed. 2572 o IANA Considerations section -- this section must always be 2573 present. For each module within the document, ensure that the 2574 IANA Considerations section contains entries for the following 2575 IANA registries: 2577 XML Namespace Registry: Register the YANG module namespace. 2579 YANG Module Registry: Register the YANG module name, prefix, 2580 namespace, and RFC number, according to the rules specified 2581 in [RFC7950]. 2583 o References -- verify that the references are properly divided 2584 between normative and informative references, that RFC 2119 is 2585 included as a normative reference if the terminology defined 2586 therein is used in the document, that all references required by 2587 the boilerplate are present, that all YANG modules containing 2588 imported items are cited as normative references, and that all 2589 citations point to the most current RFCs unless there is a valid 2590 reason to do otherwise (for example, it is OK to include an 2591 informative reference to a previous version of a specification to 2592 help explain a feature included for backward compatibility). Be 2593 sure citations for all imported modules are present somewhere in 2594 the document text (outside the YANG module). 2596 o License -- verify that the draft contains the Simplified BSD 2597 License in each YANG module or submodule. Some guidelines related 2598 to this requirement are described in Section 3.1. Make sure that 2599 the correct year is used in all copyright dates. Use the approved 2600 text from the latest Trust Legal Provisions (TLP) document, which 2601 can be found at: 2603 http://trustee.ietf.org/license-info/ 2605 o Other Issues -- check for any issues mentioned in 2606 http://www.ietf.org/id-info/checklist.html that are not covered 2607 elsewhere. 2609 o Technical Content -- review the actual technical content for 2610 compliance with the guidelines in this document. The use of a 2611 YANG module compiler is recommended when checking for syntax 2612 errors. A list of freely available tools and other information 2613 can be found at: 2615 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2617 Checking for correct syntax, however, is only part of the job. 2618 It is just as important to actually read the YANG module document 2619 from the point of view of a potential implementor. It is 2620 particularly important to check that description statements are 2621 sufficiently clear and unambiguous to allow interoperable 2622 implementations to be created. 2624 Appendix C. YANG Module Template 2626 file "ietf-template@2016-03-20.yang" 2628 module ietf-template { 2630 // replace this string with a unique namespace URN value 2631 namespace 2632 "urn:ietf:params:xml:ns:yang:ietf-template"; 2634 // replace this string, and try to pick a unique prefix 2635 prefix "temp"; 2637 // import statements here: e.g., 2638 // import ietf-yang-types { prefix yang; } 2639 // import ietf-inet-types { prefix inet; } 2641 // identify the IETF working group if applicable 2642 organization 2643 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2645 // update this contact statement with your info 2646 contact 2647 "WG Web: 2648 WG List: 2650 Editor: your-name 2651 "; 2653 // replace the first sentence in this description statement. 2654 // replace the copyright notice with the most recent 2655 // version, if it has been updated since the publication 2656 // of this document 2657 description 2658 "This module defines a template for other YANG modules. 2660 Copyright (c) IETF Trust and the persons 2661 identified as authors of the code. All rights reserved. 2663 Redistribution and use in source and binary forms, with or 2664 without modification, is permitted pursuant to, and subject 2665 to the license terms contained in, the Simplified BSD License 2666 set forth in Section 4.c of the IETF Trust's Legal Provisions 2667 Relating to IETF Documents 2668 (http://trustee.ietf.org/license-info). 2670 This version of this YANG module is part of RFC XXXX; see 2671 the RFC itself for full legal notices."; 2673 // RFC Ed.: replace XXXX with actual RFC number and remove 2674 // this note 2676 reference "RFC XXXX"; 2678 // RFC Ed.: remove this note 2679 // Note: extracted from RFC XXXX 2681 // replace '2016-03-20' with the module publication date 2682 // The format is (year-month-day) 2683 revision "2016-03-20" { 2684 description "what changed in this revision"; 2685 reference "document containing this module"; 2686 } 2688 // extension statements 2690 // feature statements 2692 // identity statements 2694 // typedef statements 2696 // grouping statements 2698 // data definition statements 2700 // augment statements 2702 // rpc statements 2704 // notification statements 2706 // DO NOT put deviation statements in a published module 2708 } 2710 2712 Author's Address 2714 Andy Bierman 2715 YumaWorks 2717 Email: andy@yumaworks.com