idnits 2.17.1 draft-ietf-netmod-rfc6087bis-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 8, 2017) is 2422 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 2513, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-04 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-01 -- 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) September 8, 2017 5 Intended status: Informational 6 Expires: March 12, 2018 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-14 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 March 12, 2018. 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. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 62 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 2.5.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7 64 3. General Documentation Guidelines . . . . . . . . . . . . . . . 8 65 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 66 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8 67 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 68 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9 69 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 70 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 71 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11 72 3.7. Security Considerations Section . . . . . . . . . . . . . 11 73 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 12 74 3.8.1. Documents that Create a New Namespace . . . . . . . . 12 75 3.8.2. Documents that Extend an Existing Namespace . . . . . 12 76 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 77 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13 78 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 79 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 13 80 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 81 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 82 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 83 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 84 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 85 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 86 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 87 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 88 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 89 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 90 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 91 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 92 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 93 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 94 4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 95 4.8. Module Header, Meta, and Revision Statements . . . . . . . 23 96 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 97 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 98 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26 99 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 100 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27 101 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28 102 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 29 103 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 30 104 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 31 105 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 32 106 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 32 107 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 34 108 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 34 109 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 35 110 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 35 111 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 36 112 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 36 113 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 36 114 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 37 115 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 37 116 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 37 117 4.19.2. Conditionally Mandatory Data Definition Statements . . 38 118 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 39 119 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 40 120 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 41 121 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 42 122 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 43 123 4.23.1. Combining Operational State and Configuration Data . . 43 124 4.23.2. Representing Operational Values of Configuration 125 Data . . . . . . . . . . . . . . . . . . . . . . . . . 44 126 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 44 127 4.24. Performance Considerations . . . . . . . . . . . . . . . . 48 128 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 48 129 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 49 130 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 49 131 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 49 132 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 49 133 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 49 134 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 50 135 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 136 6. Security Considerations . . . . . . . . . . . . . . . . . . . 53 137 6.1. Security Considerations Section Template . . . . . . . . . 53 138 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 139 8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 56 140 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 141 9.1. Normative References . . . . . . . . . . . . . . . . . . . 58 142 9.2. Informative References . . . . . . . . . . . . . . . . . . 58 143 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61 144 A.1. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 145 A.2. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 146 A.3. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 61 147 A.4. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 61 148 A.5. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 61 149 A.6. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 150 A.7. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 151 A.8. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 62 152 A.9. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 153 A.10. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 154 A.11. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 63 155 A.12. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 156 A.13. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 157 A.14. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 158 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66 159 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68 160 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 162 1. Introduction 164 The standardization of network configuration interfaces for use with 165 the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040] 166 requires a modular set of data models, which can be reused and 167 extended over time. 169 This document defines a set of usage guidelines for Standards Track 170 documents containing [RFC7950] data models. YANG is used to define 171 the data structures, protocol operations, and notification content 172 used within a NETCONF and/or RESTCONF server. A server that supports 173 a particular YANG module will support client NETCONF and/or RESTCONF 174 operation requests, as indicated by the specific content defined in 175 the YANG module. 177 This document is similar to the Structure of Management Information 178 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 179 and structure. However, since that document was written a decade 180 after SMIv2 modules had been in use, it was published as a 'Best 181 Current Practice' (BCP). This document is not a BCP, but rather an 182 informational reference, intended to promote consistency in documents 183 containing YANG modules. 185 Many YANG constructs are defined as optional to use, such as the 186 description statement. However, in order to maximize 187 interoperability of NETCONF and RESTCONF implementations utilizing 188 YANG data models, it is desirable to define a set of usage guidelines 189 that may require a higher level of compliance than the minimum level 190 defined in the YANG specification. 192 In addition, YANG allows constructs such as infinite length 193 identifiers and string values, or top-level mandatory nodes, that a 194 compliant server is not required to support. Only constructs that 195 all servers are required to support can be used in IETF YANG modules. 197 This document defines usage guidelines related to the NETCONF 198 operations layer and NETCONF content layer, as defined in [RFC6241], 199 and the RESTCONF methods and RESTCONF resources, as defined in 200 [RFC8040], 202 These guidelines are intended to be used by authors and reviewers to 203 improve the readability and interoperability of published YANG data 204 models. 206 Note that this document is not a YANG tutorial and the reader is 207 expected to know the YANG data modeling language before using this 208 document. 210 2. Terminology 212 2.1. Requirements Notation 214 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 215 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 216 document are to be interpreted as described in [RFC2119]. 218 RFC 2119 language is used here to express the views of the NETMOD 219 working group regarding content for YANG modules. YANG modules 220 complying with this document will treat the RFC 2119 terminology as 221 if it were describing best current practices. 223 2.2. NETCONF Terms 225 The following terms are defined in [RFC6241] and are not redefined 226 here: 228 o capabilities 230 o client 232 o operation 234 o server 236 2.3. YANG Terms 238 The following terms are defined in [RFC7950] and are not redefined 239 here: 241 o data node 243 o module 245 o namespace 247 o submodule 249 o version 251 o YANG 253 o YIN 255 Note that the term 'module' may be used as a generic term for a YANG 256 module or submodule. When describing properties that are specific to 257 submodules, the term 'submodule' is used instead. 259 2.4. NMDA Terms 261 The following terms are defined in the Network Management Datastore 262 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not 263 redefined here: 265 o configuration 267 o conventional configuration datastore 269 o datastore 271 o operational state 273 o operational state datastore 275 2.5. Terms 277 The following terms are used throughout this document: 279 o published: A stable release of a module or submodule. For example 280 the "Request for Comments" described in section 2.1 of [RFC2026] 281 is considered a stable publication. 283 o unpublished: An unstable release of a module or submodule. For 284 example the "Internet-Draft" described in section 2.2 of [RFC2026] 285 is considered an unstable publication that is a work-in-progress, 286 subject to change at any time. 288 o YANG fragment: A set of YANG statements that are not intended to 289 represent a complete YANG module or submodule. These statements 290 are not intended for actual use, except to provide an example of 291 YANG statement usage. The invalid syntax "..." is sometimes used 292 to indicate that additional YANG statements would be present in a 293 real YANG module. 295 2.5.1. YANG Tree Diagrams 297 A simplified graphical representation of the data model is used in 298 this document. The meaning of the symbols in these diagrams is 299 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 301 3. General Documentation Guidelines 303 YANG data model modules under review are likely to be contained in 304 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 305 followed. The RFC Editor provides guidelines for authors of RFCs, 306 which are first published as Internet-Drafts. These guidelines 307 should be followed and are defined in [RFC7322] and updated in 308 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 310 The following sections MUST be present in an Internet-Draft 311 containing a module: 313 o Narrative sections 315 o Definitions section 317 o Security Considerations section 319 o IANA Considerations section 321 o References section 323 There are three usage scenarios for YANG that can appear in an 324 Internet-Draft or RFC: 326 o normative module or submodule 328 o example module or submodule 330 o example YANG fragment not part of any module or submodule 332 The guidelines in this document refer mainly to a normative complete 333 module or submodule, but may be applicable to example modules and 334 YANG fragments as well. 336 3.1. Module Copyright 338 The module description statement MUST contain a reference to the 339 latest approved IETF Trust Copyright statement, which is available 340 online at: 342 http://trustee.ietf.org/license-info/ 344 3.2. Code Components 346 Each normative YANG module or submodule contained within an Internet- 347 Draft or RFC is considered to be a code component. The strings 348 "" and "" MUST be used to identify each code 349 component. 351 The "" tag SHOULD be followed by a string identifying 352 the file name specified in Section 5.2 of [RFC7950]. The name string 353 form that includes the revision-date SHOULD be used. The following 354 example is for the '2010-01-18' revision of the 'ietf-foo' module: 356 file "ietf-foo@2016-03-20.yang" 358 module ietf-foo { 359 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 360 prefix "foo"; 361 organization "..."; 362 contact "..."; 363 description "..."; 364 revision 2016-03-20 { 365 description "Latest revision"; 366 reference "RFC XXXX"; 367 } 368 // ... more statements 369 } 371 373 3.2.1. Example Modules 375 Example modules are not code components. The 376 convention MUST NOT be used for example modules. 378 An example module SHOULD be named using the term "example", followed 379 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 381 3.3. Terminology Section 383 A terminology section MUST be present if any terms are defined in the 384 document or if any terms are imported from other documents. 386 If YANG tree diagrams are used, then a sub-section explaining the 387 YANG tree diagram syntax MUST be present, containing the following 388 text: 390 A simplified graphical representation of the data model is used in 391 this document. The meaning of the symbols in these diagrams is 392 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 394 3.4. Tree Diagrams 396 YANG tree diagrams provide a concise representation of a YANG module, 397 and SHOULD be included to help readers understand YANG module 398 structure. Tree diagrams MAY be split into sections to correspond to 399 document structure. 401 The following example shows a simple YANG tree diagram: 403 +--rw top-level-config-container 404 | +--rw config-list* [key-name] 405 | +--rw key-name string 406 | +--rw optional-parm? string 407 | +--rw mandatory-parm identityref 408 | +--ro read-only-leaf string 409 +--ro top-level-nonconfig-container 410 +--ro nonconfig-list* [name] 411 +--ro name string 412 +--ro type string 414 The 'pyang' compiler can be used to produce the tree diagram, using 415 the '-f tree' command line parameter. 417 If the YANG module is comprised of groupings only, then the tree 418 diagram SHOULD contain the groupings. The 'pyang' compiler can be 419 used to produce a tree diagram with groupings using the '-f tree 420 --tree-print-groupings" command line parameters. 422 If the YANG module contains notifications, then the tree diagram 423 SHOULD contain the notifications. If the YANG module contains RPC 424 statements, then the tree diagram SHOULD contain the RPC statements. 426 3.5. Narrative Sections 428 The narrative part MUST include an overview section that describes 429 the scope and field of application of the module(s) defined by the 430 specification and that specifies the relationship (if any) of these 431 modules to other standards, particularly to standards containing 432 other YANG modules. The narrative part SHOULD include one or more 433 sections to briefly describe the structure of the modules defined in 434 the specification. 436 If the module(s) defined by the specification imports definitions 437 from other modules (except for those defined in the [RFC7950] or 438 [RFC6991] documents), or are always implemented in conjunction with 439 other modules, then those facts MUST be noted in the overview 440 section, as MUST be noted any special interpretations of definitions 441 in other modules. 443 3.6. Definitions Section 445 This section contains the module(s) defined by the specification. 446 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 447 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 448 semantics are needed in the module. 450 A YIN syntax version of the module MAY also be present in the 451 document. There MAY also be other types of modules present in the 452 document, such as SMIv2, which are not affected by these guidelines. 454 Note that all YANG statements within a YANG module are considered 455 normative, if the module itself is considered normative, and not an 456 example module. The use of keywords defined in [RFC2119] apply to 457 YANG description statements in normative modules exactly as they 458 would in any other normative section. 460 Example YANG modules MUST NOT contain any normative text, including 461 any reserved words from [RFC2119]. 463 See Section 4 for guidelines on YANG usage. 465 3.7. Security Considerations Section 467 Each specification that defines one or more modules MUST contain a 468 section that discusses security considerations relevant to those 469 modules. 471 This section MUST be patterned after the latest approved template 472 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 473 yang-security-guidelines). Section 6.1 contains the security 474 considerations template dated 2013-05-08. Authors MUST check the WEB 475 page at the URL listed above in case there is a more recent version 476 available. 478 In particular: 480 o Writable data nodes that could be especially disruptive if abused 481 MUST be explicitly listed by name and the associated security 482 risks MUST be explained. 484 o Readable data nodes that contain especially sensitive information 485 or that raise significant privacy concerns MUST be explicitly 486 listed by name and the reasons for the sensitivity/privacy 487 concerns MUST be explained. 489 o Operations (i.e., YANG 'rpc' statements) that are potentially 490 harmful to system behavior or that raise significant privacy 491 concerns MUST be explicitly listed by name and the reasons for the 492 sensitivity/privacy concerns MUST be explained. 494 3.8. IANA Considerations Section 496 In order to comply with IESG policy as set forth in 497 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 498 is submitted to the IESG for publication MUST contain an IANA 499 Considerations section. The requirements for this section vary 500 depending on what actions are required of the IANA. If there are no 501 IANA considerations applicable to the document, then the IANA 502 Considerations section stating that there are no actions is removed 503 by the RFC Editor before publication. Refer to the guidelines in 504 [RFC5226] for more details. 506 Each normative YANG module MUST be registered in the XML namespace 507 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 508 This applies to new modules and updated modules. Examples of these 509 registrations for the "ietf-template" module can be found in 510 Section 5. 512 3.8.1. Documents that Create a New Namespace 514 If an Internet-Draft defines a new namespace that is to be 515 administered by the IANA, then the document MUST include an IANA 516 Considerations section that specifies how the namespace is to be 517 administered. 519 Specifically, if any YANG module namespace statement value contained 520 in the document is not already registered with IANA, then a new YANG 521 Namespace registry entry MUST be requested from the IANA. The 522 [RFC7950] specification includes the procedure for this purpose in 523 its IANA Considerations section. 525 3.8.2. Documents that Extend an Existing Namespace 527 It is possible to extend an existing namespace using a YANG submodule 528 that belongs to an existing module already administered by IANA. In 529 this case, the document containing the main module MUST be updated to 530 use the latest revision of the submodule. 532 3.9. Reference Sections 534 For every import or include statement that appears in a module 535 contained in the specification, which identifies a module in a 536 separate document, a corresponding normative reference to that 537 document MUST appear in the Normative References section. The 538 reference MUST correspond to the specific module version actually 539 used within the specification. 541 For every normative reference statement that appears in a module 542 contained in the specification, which identifies a separate document, 543 a corresponding normative reference to that document SHOULD appear in 544 the Normative References section. The reference SHOULD correspond to 545 the specific document version actually used within the specification. 546 If the reference statement identifies an informative reference, which 547 identifies a separate document, a corresponding informative reference 548 to that document MAY appear in the Informative References section. 550 3.10. Validation Tools 552 All modules need to be validated before submission in an Internet 553 Draft. The 'pyang' YANG compiler is freely available from github: 555 https://github.com/mbj4668/pyang 557 If the 'pyang' compiler is used to validate a normative module, then 558 the "--ietf" command line option MUST be used to identify any IETF 559 guideline issues. 561 If the 'pyang' compiler is used to validate an example module, then 562 the "--ietf" command line option MAY be used to identify any IETF 563 guideline issues. 565 3.11. Module Extraction Tools 567 A version of 'rfcstrip' is available which will extract YANG modules 568 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 569 YANG module extraction is freely available: 571 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 573 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 575 can be extracted correctly. 577 3.12. Module Usage Examples 579 Each specification that defines one or more modules SHOULD contain 580 usage examples, either throughout the document or in an appendix. 581 This includes example instance document snippets in an appropriate 582 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 583 the YANG module(s). 585 4. YANG Usage Guidelines 587 Modules in IETF Standards Track specifications MUST comply with all 588 syntactic and semantic requirements of YANG [RFC7950]. The 589 guidelines in this section are intended to supplement the YANG 590 specification, which is intended to define a minimum set of 591 conformance requirements. 593 In order to promote interoperability and establish a set of practices 594 based on previous experience, the following sections establish usage 595 guidelines for specific YANG constructs. 597 Only guidelines that clarify or restrict the minimum conformance 598 requirements are included here. 600 4.1. Module Naming Conventions 602 Normative modules contained in Standards Track documents MUST be 603 named according to the guidelines in the IANA Considerations section 604 of [RFC7950]. 606 A distinctive word or acronym (e.g., protocol name or working group 607 acronym) SHOULD be used in the module name. If new definitions are 608 being defined to extend one or more existing modules, then the same 609 word or acronym should be reused, instead of creating a new one. 611 All published module names MUST be unique. For a YANG module 612 published in an RFC, this uniqueness is guaranteed by IANA. For 613 unpublished modules, the authors need to check that no other work in 614 progress is using the same module name. 616 Example modules are non-normative, and SHOULD be named with the 617 prefix "example-". 619 It is suggested that a stable prefix be selected representing the 620 entire organization. All normative YANG modules published by the 621 IETF MUST begin with the prefix "ietf-". Another standards 622 organization, such as the IEEE, might use the prefix "ieee-" for all 623 YANG modules. 625 Once a module name is published, it MUST NOT be reused, even if the 626 RFC containing the module is reclassified to 'Historic' status. A 627 module name cannot be changed in YANG, and this would be treated as a 628 a new module, not a name change. 630 4.2. Prefixes 632 All YANG definitions are scoped by the module containing the 633 definition being referenced. This allows definitions from multiple 634 modules to be used, even if the names are not unique. In the example 635 below, the identifier "foo" is used in all 3 modules: 637 module example-foo { 638 namespace "http://example.com/ns/foo"; 639 prefix f; 641 container foo; 642 } 644 module example-bar { 645 namespace "http://example.com/ns/bar"; 646 prefix b; 648 typedef foo { type uint32; } 649 } 651 module example-one { 652 namespace "http://example.com/ns/one"; 653 prefix one; 654 import example-foo { prefix f; } 655 import example-bar { prefix b; } 657 augment "/f:foo" { 658 leaf foo { type b:foo; } 659 } 660 } 662 YANG defines the following rules for prefix usage: 664 o Prefixes are never allowed for built in data types and YANG 665 keywords. 667 o A prefix MUST be used for any external statement (i.e., a 668 statement defined with the YANG "extension" statement) 670 o The proper module prefix MUST be used for all identifiers imported 671 from other modules 673 o The proper module prefix MUST be used for all identifiers included 674 from a submodule. 676 The following guidelines apply to prefix usage of the current (local) 677 module: 679 o The local module prefix SHOULD be used instead of no prefix in all 680 path expressions. 682 o The local module prefix MUST be used instead of no prefix in all 683 "default" statements for an "identityref" or "instance-identifier" 684 data type 686 o The local module prefix MAY be used for references to typedefs, 687 groupings, extensions, features, and identities defined in the 688 module. 690 Prefix values SHOULD be short, but also likely to be unique. Prefix 691 values SHOULD NOT conflict with known modules that have been 692 previously published. 694 4.3. Identifiers 696 Identifiers for all YANG identifiers in published modules MUST be 697 between 1 and 64 characters in length. These include any construct 698 specified as an 'identifier-arg-str' token in the ABNF in Section 13 699 of [RFC7950]. 701 4.3.1. Identifier Naming Conventions 703 Identifiers SHOULD follow a consistent naming pattern throughout the 704 module. Only lower-case letters, numbers, and dashes SHOULD be used 705 in identifier names. Upper-case characters and the underscore 706 character MAY be used if the identifier represents a well-known value 707 that uses these characters. 709 Identifiers SHOULD include complete words and/or well-known acronyms 710 or abbreviations. Child nodes within a container or list SHOULD NOT 711 replicate the parent identifier. YANG identifiers are hierarchical 712 and are only meant to be unique within the the set of sibling nodes 713 defined in the same module namespace. 715 It is permissible to use common identifiers such as "name" or "id" in 716 data definition statements, especially if these data nodes share a 717 common data type. 719 Identifiers SHOULD NOT carry any special semantics that identify data 720 modelling properties. Only YANG statements and YANG extension 721 statements are designed to convey machine readable data modelling 722 properties. For example, naming an object "config" or "state" does 723 not change whether it is configuration data or state data. Only 724 defined YANG statements or YANG extension statements can be used to 725 assign semantics in a machine readable format in YANG. 727 4.4. Defaults 729 In general, it is suggested that substatements containing very common 730 default values SHOULD NOT be present. The following substatements 731 are commonly used with the default value, which would make the module 732 difficult to read if used everywhere they are allowed. 734 +--------------+---------------+ 735 | Statement | Default Value | 736 +--------------+---------------+ 737 | config | true | 738 | mandatory | false | 739 | max-elements | unbounded | 740 | min-elements | 0 | 741 | ordered-by | system | 742 | status | current | 743 | yin-element | false | 744 +--------------+---------------+ 746 Statement Defaults 748 4.5. Conditional Statements 750 A module may be conceptually partitioned in several ways, using the 751 'if-feature' and/or 'when' statements. 753 Data model designers need to carefully consider all modularity 754 aspects, including the use of YANG conditional statements. 756 If a data definition is optional, depending on server support for a 757 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 758 statement SHOULD be defined to indicate that the NETCONF or RESTCONF 759 capability is supported within the data model. 761 If any notification data, or any data definition, for a non- 762 configuration data node is not mandatory, then the server may or may 763 not be required to return an instance of this data node. If any 764 conditional requirements exist for returning the data node in a 765 notification payload or retrieval request, they MUST be documented 766 somewhere. For example, a 'when' or 'if-feature' statement could 767 apply to the data node, or the conditional requirements could be 768 explained in a 'description' statement within the data node or one of 769 its ancestors (if any). 771 If any 'if-feature' statements apply to a list node, then the same 772 'if-feature' statements MUST apply to any key leaf nodes for the 773 list. There MUST NOT be any 'if-feature' statements applied to any 774 key leaf that do not also apply to the parent list node. 776 There SHOULD NOT be any 'when' statements applied to a key leaf node. 777 It is possible that a 'when' statement for an ancestor node of a key 778 leaf will have the exact node-set result as the key leaf. In such a 779 case, the 'when' statement for the key leaf is redundant and SHOULD 780 be avoided. 782 4.6. XPath Usage 784 This section describes guidelines for using the XML Path Language 785 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 787 4.6.1. XPath Evaluation Contexts 789 YANG defines 5 separate contexts for evaluation of XPath statements: 791 1) The "running" datastore: collection of all YANG configuration data 792 nodes. The document root is the conceptual container, (e.g., 793 "config" in the "edit-config" operation), which is the parent of all 794 top-level data definition statements with a "config" statement value 795 of "true". 797 2) State data + the "running" datastore: collection of all YANG data 798 nodes. The document root is the conceptual container, parent of all 799 top-level data definition statements. 801 3) Notification: an event notification document. The document root 802 is the notification element. 804 4) RPC Input: The document root is the conceptual "input" node, which 805 is the parent of all RPC input parameter definitions. 807 5) RPC Output: The document root is the conceptual "output" node, 808 which is the parent of all RPC output parameter definitions. 810 Note that these XPath contexts cannot be mixed. For example, a 811 "when" statement in a notification context cannot reference 812 configuration data. 814 notification foo { 815 leaf mtu { 816 // NOT OK because when-stmt context is this notification 817 when "/if:interfaces/if:interface[name='eth0']"; 818 type leafref { 819 // OK because path-stmt has a different context 820 path "/if:interfaces/if:interface/if:mtu"; 821 } 822 } 823 } 825 It is especially important to consider the XPath evaluation context 826 for XPath expressions defined in groupings. An XPath expression 827 defined in a grouping may not be portable, meaning it cannot be used 828 in multiple contexts and produce proper results. 830 If the XPath expressions defined in a grouping are intended for a 831 particular context, then this context SHOULD be identified in the 832 "description" statement for the grouping. 834 4.6.2. Function Library 836 The 'position' and 'last' functions SHOULD NOT be used. This applies 837 to implicit use of the 'position' function as well (e.g., 838 '//chapter[42]'). A server is only required to maintain the relative 839 XML document order of all instances of a particular user-ordered list 840 or leaf-list. The 'position' and 'last' functions MAY be used if 841 they are evaluated in a context where the context node is a user- 842 ordered 'list' or 'leaf-list'. 844 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 845 present in YANG documents so this function has no meaning. The YANG 846 compiler SHOULD return an empty string for this function. 848 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 849 Expanded names in XPath are different than YANG. A specific 850 canonical representation of a YANG expanded name does not exist. 852 The 'lang' function SHOULD NOT be used. This function does not apply 853 to YANG because there is no 'lang' attribute set with the document. 854 The YANG compiler SHOULD return 'false' for this function. 856 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 857 functions SHOULD NOT be used if the argument is a node-set. If so, 858 the function result will be determined by the document order of the 859 node-set. Since this order can be different on each server, the 860 function results can also be different. Any function call that 861 implicitly converts a node-set to a string will also have this issue. 863 The 'local-name' function SHOULD NOT be used to reference local names 864 outside of the YANG module defining the must or when expression 865 containing the 'local-name' function. Example of a local-name 866 function that should not be used: 868 /*[local-name()='foo'] 870 4.6.3. Axes 872 The 'attribute' and 'namespace' axes are not supported in YANG, and 873 MAY be empty in a NETCONF or RESTCONF server implementation. 875 The 'preceding', and 'following' axes SHOULD NOT be used. These 876 constructs rely on XML document order within a NETCONF or RESTCONF 877 server configuration database, which may not be supported 878 consistently or produce reliable results across implementations. 879 Predicate expressions based on static node properties (e.g., element 880 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 881 instead. The 'preceding' and 'following' axes MAY be used if 882 document order is not relevant to the outcome of the expression 883 (e.g., check for global uniqueness of a parameter value). 885 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 886 however they MAY be used if document order is not relevant to the 887 outcome of the expression. 889 A server is only required to maintain the relative XML document order 890 of all instances of a particular user-ordered list or leaf-list. The 891 'preceding-sibling' and 'following-sibling' axes MAY be used if they 892 are evaluated in a context where the context node is a user-ordered 893 'list' or 'leaf-list'. 895 4.6.4. Types 897 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 898 be used within numeric or boolean expressions. There are boundary 899 conditions in which the translation from the YANG 64-bit type to an 900 XPath number can cause incorrect results. Specifically, an XPath 901 'double' precision floating point number cannot represent very large 902 positive or negative 64-bit numbers because it only provides a total 903 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 904 used in numeric expressions if the value can be represented with no 905 more than 53 bits of precision. 907 Data modelers need to be careful not to confuse the YANG value space 908 and the XPath value space. The data types are not the same in both, 909 and conversion between YANG and XPath data types SHOULD be considered 910 carefully. 912 Explicit XPath data type conversions MAY be used (e.g., 'string', 913 'boolean', or 'number' functions), instead of implicit XPath data 914 type conversions. 916 XPath expressions that contain a literal value representing a YANG 917 identity SHOULD always include the declared prefix of the module 918 where the identity is defined. 920 XPath expressions for 'when' statements SHOULD NOT reference the 921 context node or any descendant nodes of the context node. They MAY 922 reference descendant nodes if the 'when' statement is contained 923 within an 'augment' statement, and the referenced nodes are not 924 defined within the 'augment' statement. 926 Example: 928 augment "/rt:active-route/rt:input/rt:destination-address" { 929 when "rt:address-family='v4ur:ipv4-unicast'" { 930 description 931 "This augment is valid only for IPv4 unicast."; 932 } 933 // nodes defined here within the augment-stmt 934 // cannot be referenced in the when-stmt 935 } 937 4.6.5. Wildcards 939 It is possible to construct XPath expressions that will evaluate 940 differently when combined with several modules within a server 941 implementation, then when evaluated within the single module. This 942 is due to augmenting nodes from other modules. 944 Wildcard expansion is done within a server against all the nodes from 945 all namespaces, so it is possible for a 'must' or 'when' expression 946 that uses the '*' operator will always evaluate to false if processed 947 within a single YANG module. In such cases, the 'description' 948 statement SHOULD clarify that augmenting objects are expected to 949 match the wildcard expansion. 951 when /foo/services/*/active { 952 description 953 "No services directly defined in this module. 954 Matches objects that have augmented the services container."; 955 } 957 4.6.6. Boolean Expressions 959 The YANG "must" and "when" statements use an XPath boolean expression 960 to define the test condition for the statement. It is important to 961 specify these expressions in a way that will not cause inadvertent 962 changes in the result if the objects referenced in the expression are 963 updated in future revisions of the module. 965 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 966 to "one" or "three": 968 leaf foo1 { 969 type enumeration { 970 enum one; 971 enum two; 972 enum three; 973 } 974 } 976 leaf foo2 { 977 // INCORRECT 978 must "/f:foo1 != 'two'"; 979 type string; 980 } 982 leaf foo2 { 983 // CORRECT 984 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 985 type string; 986 } 988 In the next revision of the module, leaf "foo1" is extended with a 989 new enum named "four": 991 leaf foo1 { 992 type enumeration { 993 enum one; 994 enum two; 995 enum three; 996 enum four; 997 } 998 } 1000 Now the first XPath expression will allow the enum "four" to be 1001 accepted in addition to the "one" and "three" enum values. 1003 4.7. Lifecycle Management 1005 The status statement MUST be present if its value is 'deprecated' or 1006 'obsolete'. The status SHOULD NOT be changed from 'current' directly 1007 to 'obsolete'. An object SHOULD be available for at least one year 1008 with 'deprecated' status before it is changed to 'obsolete'. 1010 The module or submodule name MUST NOT be changed, once the document 1011 containing the module or submodule is published. 1013 The module namespace URI value MUST NOT be changed, once the document 1014 containing the module is published. 1016 The revision-date substatement within the import statement SHOULD be 1017 present if any groupings are used from the external module. 1019 The revision-date substatement within the include statement SHOULD be 1020 present if any groupings are used from the external submodule. 1022 If an import statement is for a module from a stable source (e.g., an 1023 RFC for an IETF module), then a reference-stmt SHOULD be present 1024 within an import statement. 1026 import ietf-yang-types { 1027 prefix yang; 1028 reference "RFC 6991"; 1029 } 1031 If submodules are used, then the document containing the main module 1032 MUST be updated so that the main module revision date is equal or 1033 more recent than the revision date of any submodule that is (directly 1034 or indirectly) included by the main module. 1036 Definitions for future use SHOULD NOT be specified in a module. Do 1037 not specify placeholder objects like the "reserved" example below: 1039 leaf reserved { 1040 type string; 1041 description 1042 "This object has no purpose at this time, but a future 1043 revision of this module might define a purpose 1044 for this object."; 1045 } 1046 } 1048 4.8. Module Header, Meta, and Revision Statements 1050 For published modules, the namespace MUST be a globally unique URI, 1051 as defined in [RFC3986]. This value is usually assigned by the IANA. 1053 The organization statement MUST be present. If the module is 1054 contained in a document intended for IETF Standards Track status, 1055 then the organization SHOULD be the IETF working group chartered to 1056 write the document. For other standards organizations, a similar 1057 approach is also suggested. 1059 The contact statement MUST be present. If the module is contained in 1060 a document intended for Standards Track status, then the working 1061 group web and mailing information MUST be present, and the main 1062 document author or editor contact information SHOULD be present. If 1063 additional authors or editors exist, their contact information MAY be 1064 present. 1066 The description statement MUST be present. For modules published 1067 within IETF documents, the appropriate IETF Trust Copyright text MUST 1068 be present, as described in Section 3.1. 1070 If the module relies on information contained in other documents, 1071 which are not the same documents implied by the import statements 1072 present in the module, then these documents MUST be identified in the 1073 reference statement. 1075 A revision statement MUST be present for each published version of 1076 the module. The revision statement MUST have a reference 1077 substatement. It MUST identify the published document that contains 1078 the module. Modules are often extracted from their original 1079 documents, and it is useful for developers and operators to know how 1080 to find the original source document in a consistent manner. The 1081 revision statement MAY have a description substatement. 1083 It is not required to keep the full revision history of draft 1084 versions (e.g., modules contained within Internet-Drafts). That is, 1085 within a sequence of draft versions, only the most recent revision 1086 need be recorded in the module. However, whenever a new (i.e. 1087 changed) version is made available (e.g., via a new version of an 1088 Internet-Draft), the revision date of that new version MUST be 1089 updated to a date later than that of the previous version. 1091 4.9. Namespace Assignments 1093 It is RECOMMENDED that only valid YANG modules be included in 1094 documents, whether or not they are published yet. This allows: 1096 o the module to compile correctly instead of generating disruptive 1097 fatal errors. 1099 o early implementors to use the modules without picking a random 1100 value for the XML namespace. 1102 o early interoperability testing since independent implementations 1103 will use the same XML namespace value. 1105 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1106 provided for the namespace statement in a YANG module. A value 1107 SHOULD be selected that is not likely to collide with other YANG 1108 namespaces. Standard module names, prefixes, and URI strings already 1109 listed in the YANG Module Registry MUST NOT be used. 1111 A standard namespace statement value SHOULD have the following form: 1113 : 1115 The following URN prefix string SHOULD be used for published and 1116 unpublished YANG modules: 1118 urn:ietf:params:xml:ns:yang: 1120 The following example URNs would be valid namespace statement values 1121 for Standards Track modules: 1123 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1125 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1127 urn:ietf:params:xml:ns:yang:ietf-netconf 1129 Note that a different URN prefix string SHOULD be used for non- 1130 Standards-Track modules. The string SHOULD be selected according to 1131 the guidelines in [RFC7950]. 1133 The following URIs exemplify what might be used by non Standards 1134 Track modules. Note that the domain "example.com" SHOULD be used by 1135 example modules in IETF drafts. 1137 Example URIs using URLs per RFC 3986 [RFC3986]: 1139 http://example.com/ns/example-interfaces 1141 http://example.com/ns/example-system 1143 Example URIs using tags per RFC 4151 [RFC4151]: 1145 tag:example.com,2017:example-interfaces 1147 tag:example.com,2017:example-system 1149 4.10. Top-Level Data Definitions 1151 The top-level data organization SHOULD be considered carefully, in 1152 advance. Data model designers need to consider how the functionality 1153 for a given protocol or protocol family will grow over time. 1155 The separation of configuration data and operational state SHOULD be 1156 considered carefully. It is sometimes useful to define separate top- 1157 level containers for configuration and non-configuration data. For 1158 some existing top-level data nodes, configuration data was not in 1159 scope, so only one container representing operational state was 1160 created. 1162 The number of top-level data nodes within a module SHOULD be 1163 minimized. It is often useful to retrieve related information within 1164 a single subtree. If data is too distributed, is becomes difficult 1165 to retrieve all at once. 1167 The names and data organization SHOULD reflect persistent 1168 information, such as the name of a protocol. The name of the working 1169 group SHOULD NOT be used because this may change over time. 1171 A mandatory database data definition is defined as a node that a 1172 client must provide for the database to be valid. The server is not 1173 required to provide a value. 1175 Top-level database data definitions MUST NOT be mandatory. If a 1176 mandatory node appears at the top level, it will immediately cause 1177 the database to be invalid. This can occur when the server boots or 1178 when a module is loaded dynamically at runtime. 1180 4.11. Data Types 1182 Selection of an appropriate data type (i.e., built-in type, existing 1183 derived type, or new derived type) is very subjective, and therefore 1184 few requirements can be specified on that subject. 1186 Data model designers SHOULD use the most appropriate built-in data 1187 type for the particular application. 1189 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1190 'int64') SHOULD NOT be used unless negative values are allowed for 1191 the desired semantics. 1193 4.11.1. Fixed Value Extensibility 1195 If the set of values is fixed and the data type contents are 1196 controlled by a single naming authority, then an enumeration data 1197 type SHOULD be used. 1199 leaf foo { 1200 type enumeration { 1201 enum one; 1202 enum two; 1203 } 1204 } 1206 If extensibility of enumerated values is required, then the 1207 'identityref' data type SHOULD be used instead of an enumeration or 1208 other built-in type. 1210 identity foo-type { 1211 description "Base for the extensible type"; 1212 } 1214 identity one { 1215 base f:foo-type; 1216 } 1217 identity two { 1218 base f:foo-type; 1219 } 1221 leaf foo { 1222 type identityref { 1223 base f:foo-type; 1224 } 1225 } 1227 Note that any module can declare an identity with base "foo-type" 1228 that is valid for the "foo" leaf. Identityref values are considered 1229 to be qualified names. 1231 4.11.2. Patterns and Ranges 1233 For string data types, if a machine-readable pattern can be defined 1234 for the desired semantics, then one or more pattern statements SHOULD 1235 be present. A single quoted string SHOULD be used to specify the 1236 pattern, since a double-quoted string can modify the content. 1238 The following typedef from [RFC6991] demonstrates the proper use of 1239 the "pattern" statement: 1241 typedef ipv4-address-no-zone { 1242 type inet:ipv4-address { 1243 pattern '[0-9\.]*'; 1244 } 1245 ... 1246 } 1248 For string data types, if the length of the string is required to be 1249 bounded in all implementations, then a length statement MUST be 1250 present. 1252 The following typedef from [RFC6991] demonstrates the proper use of 1253 the "length" statement: 1255 typedef yang-identifier { 1256 type string { 1257 length "1..max"; 1258 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1259 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1260 } 1261 ... 1262 } 1264 For numeric data types, if the values allowed by the intended 1265 semantics are different than those allowed by the unbounded intrinsic 1266 data type (e.g., 'int32'), then a range statement SHOULD be present. 1268 The following typedef from [RFC6991] demonstrates the proper use of 1269 the "range" statement: 1271 typedef dscp { 1272 type uint8 { 1273 range "0..63"; 1274 } 1275 ... 1276 } 1278 4.11.3. Enumerations and Bits 1280 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1281 or 'bit' SHOULD be documented. A separate description statement 1282 (within each 'enum' or 'bit' statement) SHOULD be present. 1284 leaf foo { 1285 // INCORRECT 1286 type enumeration { 1287 enum one; 1288 enum two; 1289 } 1290 description 1291 "The foo enum... 1292 one: The first enum 1293 two: The second enum"; 1294 } 1296 leaf foo { 1297 // CORRECT 1298 type enumeration { 1299 enum one { 1300 description "The first enum"; 1301 } 1302 enum two { 1303 description "The second enum"; 1304 } 1305 } 1306 description 1307 "The foo enum... "; 1308 } 1310 4.11.4. Union Types 1312 The YANG "union" type is evaluated by testing a value against each 1313 member type in the union. The first type definition that accepts a 1314 value as valid is the member type used. In general, member types 1315 SHOULD be ordered from most restrictive to least restrictive types. 1317 In the following example, the "enumeration" type will never be 1318 matched because the preceding "string" type will match everything. 1320 Incorrect: 1322 type union { 1323 type string; 1324 type enumeration { 1325 enum up; 1326 enum down; 1327 } 1328 } 1330 Correct: 1332 type union { 1333 type enumeration { 1334 enum up; 1335 enum down; 1336 } 1337 type string; 1338 } 1340 It is possible for different member types to match, depending on the 1341 input encoding format. In XML, all values are passed as string 1342 nodes, but in JSON there are different value types for numbers, 1343 booleans, and strings. 1345 In the following example, a JSON numeric value will always be matched 1346 by the "int32" type but in XML the string value representing a number 1347 will be matched by the "string" type. The second version will match 1348 the "int32" member type no matter how the input is encoded. 1350 Incorrect: 1352 type union { 1353 type string; 1354 type int32; 1355 } 1357 Correct: 1359 type union { 1360 type int32; 1361 type string; 1362 } 1364 4.11.5. Empty and Boolean 1366 YANG provides an "empty" data type, which has one value (i.e., 1367 present). The default is "not present", which is not actually a 1368 value. When used within a list key, only one value can (and must) 1369 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1370 key leaf since it is pointless. 1372 There is really no difference between a leaf of type "empty" and a 1373 leaf-list of type "empty". Both are limited to one instance. The 1374 type "empty" SHOULD NOT be used for a leaf-list. 1376 The advantage of using type "empty" instead of type "boolean" is that 1377 the default (not present) does not take up any bytes in a 1378 representation. The disadvantage is that the client may not be sure 1379 if an empty leaf is missing because it was filtered somehow or not 1380 implemented. The client may not have a complete and accurate schema 1381 for the data returned by the server, and not be aware of the missing 1382 leaf. 1384 The YANG "boolean" data type provides two values ("true" and 1385 "false"). When used within a list key, two entries can exist for 1386 this key leaf. Default values are ignored for key leafs, but a 1387 default statement is often used for plain boolean leafs. The 1388 advantage of the "boolean" type is that the leaf or leaf-list has a 1389 clear representation for both values. The default value is usually 1390 not returned unless explicitly requested by the client, so no bytes 1391 are used in a typical representation. 1393 In general, the "boolean" data type SHOULD be used instead of the 1394 "empty" data type, as shown in the example below: 1396 Incorrect: 1398 leaf flag1 { 1399 type empty; 1400 } 1402 Correct: 1404 leaf flag2 { 1405 type boolean; 1406 default false; 1407 } 1409 4.12. Reusable Type Definitions 1411 If an appropriate derived type exists in any standard module, such as 1412 [RFC6991], then it SHOULD be used instead of defining a new derived 1413 type. 1415 If an appropriate units identifier can be associated with the desired 1416 semantics, then a units statement SHOULD be present. 1418 If an appropriate default value can be associated with the desired 1419 semantics, then a default statement SHOULD be present. 1421 If a significant number of derived types are defined, and it is 1422 anticipated that these data types will be reused by multiple modules, 1423 then these derived types SHOULD be contained in a separate module or 1424 submodule, to allow easier reuse without unnecessary coupling. 1426 The description statement MUST be present. 1428 If the type definition semantics are defined in an external document 1429 (other than another YANG module indicated by an import statement), 1430 then the reference statement MUST be present. 1432 4.13. Reusable Groupings 1434 A reusable grouping is a YANG grouping that can be imported by 1435 another module, and is intended for use by other modules. This is 1436 not the same as a grouping that is used within the module it is 1437 defined, but happens to be exportable to another module because it is 1438 defined at the top-level of the YANG module. 1440 The following guidelines apply to reusable groupings, in order to 1441 make them as robust as possible: 1443 o Clearly identify the purpose of the grouping in the "description" 1444 statement. 1446 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1447 output, notification, config=true data nodes, and all data nodes). 1448 Clearly identify which XPath contexts are applicable or excluded 1449 for the grouping. 1451 o Do not reference data outside the grouping in any "path", "must", 1452 or "when" statements. 1454 o Do not include a "default" sub-statement on a leaf or choice 1455 unless the value applies on all possible contexts. 1457 o Do not include a "config" sub-statement on a data node unless the 1458 value applies on all possible contexts. 1460 o Clearly identify any external dependencies in the grouping 1461 "description" statement, such as nodes referenced by absolute path 1462 from a "path", "must", or "when" statement. 1464 4.14. Data Definitions 1466 The description statement MUST be present in the following YANG 1467 statements: 1469 o anyxml 1471 o augment 1473 o choice 1474 o container 1476 o extension 1478 o feature 1480 o grouping 1482 o identity 1484 o leaf 1486 o leaf-list 1488 o list 1490 o notification 1492 o rpc 1494 o typedef 1496 If the data definition semantics are defined in an external document, 1497 (other than another YANG module indicated by an import statement), 1498 then a reference statement MUST be present. 1500 The 'anyxml' construct may be useful to represent an HTML banner 1501 containing markup elements, such as '<b>' and '</b>', and 1502 MAY be used in such cases. However, this construct SHOULD NOT be 1503 used if other YANG data node types can be used instead to represent 1504 the desired syntax and semantics. 1506 It has been found that the 'anyxml' statement is not implemented 1507 consistently across all servers. It is possible that mixed mode XML 1508 will not be supported, or configuration anyxml nodes will not 1509 supported. 1511 If there are referential integrity constraints associated with the 1512 desired semantics that can be represented with XPath, then one or 1513 more 'must' statements SHOULD be present. 1515 For list and leaf-list data definitions, if the number of possible 1516 instances is required to be bounded for all implementations, then the 1517 max-elements statements SHOULD be present. 1519 If any 'must' or 'when' statements are used within the data 1520 definition, then the data definition description statement SHOULD 1521 describe the purpose of each one. 1523 The "choice" statement is allowed to be directly present within a 1524 "case" statement in YANG 1.1. This needs to be considered carefully. 1525 Consider simply including the nested "choice" as additional "case" 1526 statements within the parent "choice" statement. Note that the 1527 "mandatory" and "default" statements within a nested "choice" 1528 statement only apply if the "case" containing the nested "choice" 1529 statement is first selected. 1531 4.14.1. Non-Presence Containers 1533 A non-presence container is used to organize data into specific 1534 subtrees. It is not intended to have semantics within the data model 1535 beyond this purpose, although YANG allows it (e.g., "must" statement 1536 within the non-presence container). 1538 Example using container wrappers: 1540 container top { 1541 container foos { 1542 list foo { ... } 1543 } 1544 container bars { 1545 list bar { ... } 1546 } 1547 } 1549 Example without container wrappers: 1551 container top { 1552 list foo { ... } 1553 list bar { ... } 1554 } 1556 Use of non-presence containers to organize data is a subjective 1557 matter similar to use of sub-directories in a file system. The 1558 NETCONF and RESTCONF protocols do not currently support the ability 1559 to delete all list (or leaf-list) entries at once. This deficiency 1560 is sometimes avoided by use of a parent container (i.e., deleting the 1561 container also removes all child entries). 1563 4.14.2. Top-Level Data Nodes 1565 Use of top-level objects needs to be considered carefully 1567 -top-level siblings are not ordered -top-level siblings not are not 1568 static, and depends on the modules that are loaded 1569 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1570 treated as a content-match node for all top-level-siblings 1572 o a top-level list with many instances may impact performance 1574 4.15. Operation Definitions 1576 If the operation semantics are defined in an external document (other 1577 than another YANG module indicated by an import statement), then a 1578 reference statement MUST be present. 1580 If the operation impacts system behavior in some way, it SHOULD be 1581 mentioned in the description statement. 1583 If the operation is potentially harmful to system behavior in some 1584 way, it MUST be mentioned in the Security Considerations section of 1585 the document. 1587 4.16. Notification Definitions 1589 The description statement MUST be present. 1591 If the notification semantics are defined in an external document 1592 (other than another YANG module indicated by an import statement), 1593 then a reference statement MUST be present. 1595 If the notification refers to a specific resource instance, then this 1596 instance SHOULD be identified in the notification data. This is 1597 usually done by including 'leafref' leaf nodes with the key leaf 1598 values for the resource instance. For example: 1600 notification interface-up { 1601 description "Sent when an interface is activated."; 1602 leaf name { 1603 type leafref { 1604 path "/if:interfaces/if:interface/if:name"; 1605 } 1606 } 1607 } 1609 Note that there are no formal YANG statements to identify any data 1610 node resources associated with a notification. The description 1611 statement for the notification SHOULD specify if and how the 1612 notification identifies any data node resources associated with the 1613 specific event. 1615 4.17. Feature Definitions 1617 The YANG "feature" statement is used to define a label for a set of 1618 optional functionality within a module. The "if-feature" statement 1619 is used in the YANG statements associated with a feature. 1621 The set of YANG features available in a module should be considered 1622 carefully. The description-stmt within a feature-stmt MUST specify 1623 any interactions with other features. 1625 If there is a large set of objects associated with a YANG feature, 1626 then consider moving those objects to a separate module, instead of 1627 using a YANG feature. Note that the set of features within a module 1628 is easily discovered by the reader, but the set of related modules 1629 within the entire YANG library is not as easy to identity. Module 1630 names with a common prefix can help readers identity the set of 1631 related modules, but this assumes the reader will have discovered and 1632 installed all the relevant modules. 1634 Another consideration for deciding whether to create a new module or 1635 add a YANG feature is the stability of the module in question. It 1636 may be desirable to have a stable base module that is not changed 1637 frequently. If new functionality is placed in a separate module, 1638 then the base module does not need to be republished. If it is 1639 designed as a YANG feature then the module will need to be 1640 republished. 1642 If one feature requires implementation of another feature, then an 1643 "if-feature" statement SHOULD be used in the dependent "feature" 1644 statement. 1646 For example, feature2 requires implementation of feature1: 1648 feature feature1 { 1649 description "Some protocol feature"; 1650 } 1652 feature feature2 { 1653 if-feature "feature1"; 1654 description "Another protocol feature"; 1655 } 1657 4.18. YANG Data Node Constraints 1659 4.18.1. Controlling Quantity 1661 The "min-elements" and "max-elements" statements can be use to 1662 control how many list or leaf-list instances are required for a 1663 particular data node. YANG constraint statements SHOULD be used to 1664 identify conditions that apply to all implementations of the data 1665 model. If platform-specific limitations (e.g., the "max-elements" 1666 supported for a particular list) are relevant to operations, then a 1667 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1668 used to identify the limit. 1670 4.18.2. must vs. when 1672 The "must" and "when" YANG statements are used to provide cross- 1673 object referential tests. They have very different behavior. The 1674 "when" statement causes data node instances to be silently deleted as 1675 soon as the condition becomes false. A false "when" expression is 1676 not considered to be an error. 1678 The "when" statement SHOULD be used together with the "augment" or 1679 "uses" statements to achieve conditional model composition. The 1680 condition SHOULD be based on static properties of the augmented entry 1681 (e.g., list key leafs). 1683 The "must" statement causes a datastore validation error if the 1684 condition is false. This statement SHOULD be used for enforcing 1685 parameter value restrictions that involve more than one data node 1686 (e.g., end-time parameter must be after the start-time parameter). 1688 4.19. Augment Statements 1690 The YANG "augment" statement is used to define a set of data 1691 definition statements that will be added as child nodes of a target 1692 data node. The module namespace for these data nodes will be the 1693 augmenting module, not the augmented module. 1695 A top-level "augment" statement SHOULD NOT be used if the target data 1696 node is in the same module or submodule as the evaluated "augment" 1697 statement. The data definition statements SHOULD be added inline 1698 instead. 1700 4.19.1. Conditional Augment Statements 1702 The "augment" statement is often used together with the "when" 1703 statement and/or "if-feature" statement to make the augmentation 1704 conditional on some portion of the data model. 1706 The following example from [RFC7223] shows how a conditional 1707 container called "ethernet" is added to the "interface" list only for 1708 entries of the type "ethernetCsmacd". 1710 augment "/if:interfaces/if:interface" { 1711 when "if:type = 'ianaift:ethernetCsmacd'"; 1713 container ethernet { 1714 leaf duplex { 1715 ... 1716 } 1717 } 1718 } 1720 4.19.2. Conditionally Mandatory Data Definition Statements 1722 YANG has very specific rules about how configuration data can be 1723 updated in new releases of a module. These rules allow an "old 1724 client" to continue interoperating with a "new server". 1726 If data nodes are added to an existing entry, the old client MUST NOT 1727 be required to provide any mandatory parameters that were not in the 1728 original module definition. 1730 It is possible to add conditional augment statements such that the 1731 old client would not know about the new condition, and would not 1732 specify the new condition. The conditional augment statement can 1733 contain mandatory objects only if the condition is false unless 1734 explicitly requested by the client. 1736 Only a conditional augment statement that uses the "when" statement 1737 form of condition can be used in this manner. The YANG features 1738 enabled on the server cannot be controlled by the client in any way, 1739 so it is not safe to add mandatory augmenting data nodes based on the 1740 "if-feature" statement. 1742 The XPath "when" statement condition MUST NOT reference data outside 1743 of target data node because the client does not have any control over 1744 this external data. 1746 In the following dummy example, it is OK to augment the "interface" 1747 entry with "mandatory-leaf" because the augmentation depends on 1748 support for "some-new-iftype". The old client does not know about 1749 this type so it would never select this type, and therefore not be 1750 adding a mandatory data node. 1752 module example-module { 1753 namespace "http://example.com/ns/example-module"; 1754 prefix mymod; 1756 import iana-if-type { prefix iana; } 1757 import ietf-interfaces { prefix if; } 1759 identity some-new-iftype { 1760 base iana:iana-interface-type; 1761 } 1763 augment "/if:interfaces/if:interface" { 1764 when "if:type = 'mymod:some-new-iftype'"; 1766 leaf mandatory-leaf { 1767 mandatory true; 1768 ... 1769 } 1770 } 1771 } 1773 Note that this practice is safe only for creating data resources. It 1774 is not safe for replacing or modifying resources if the client does 1775 not know about the new condition. The YANG data model MUST be 1776 packaged in a way that requires the client to be aware of the 1777 mandatory data nodes if it is aware of the condition for this data. 1778 In the example above, the "some-new-iftype" identity is defined in 1779 the same module as the "mandatory-leaf" data definition statement. 1781 This practice is not safe for identities defined in a common module 1782 such as "iana-if-type" because the client is not required to know 1783 about "my-module" just because it knows about the "iana-if-type" 1784 module. 1786 4.20. Deviation Statements 1788 The YANG "deviation" statement cannot appear in IETF YANG modules, 1789 but it can be useful for documenting server capabilities. Deviation 1790 statements are not reusable and typically not shared across all 1791 platforms. 1793 There are several reasons that deviations might be needed in an 1794 implementation, e.g., an object cannot be supported on all platforms, 1795 or feature delivery is done in multiple development phases. 1796 Deviation statements can also be used to add annotations to a module, 1797 which does not affect the conformance requirements for the module. 1799 It is suggested that deviation statements be defined in separate 1800 modules from regular YANG definitions. This allows the deviations to 1801 be platform-specific and/or temporary. 1803 The order that deviation statements are evaluated can affect the 1804 result. Therefore multiple deviation statements in the same module, 1805 for the same target object, SHOULD NOT be used. 1807 The "max-elements" statement is intended to describe an architectural 1808 limit to the number of list entries. It is not intended to describe 1809 platform limitations. It is better to use a "deviation" statement 1810 for the platforms that have a hard resource limit. 1812 Example documenting platform resource limits: 1814 Wrong: (max-elements in the list itself) 1816 container backups { 1817 list backup { 1818 ... 1819 max-elements 10; 1820 ... 1821 } 1822 } 1824 Correct: (max-elements in a deviation) 1826 deviation /bk:backups/bk:backup { 1827 deviate add { 1828 max-elements 10; 1829 } 1830 } 1832 4.21. Extension Statements 1834 The YANG "extension" statement is used to specify external 1835 definitions. This appears in the YANG syntax as an 1836 "unknown-statement". Usage of extension statements in a published 1837 module needs to be considered carefully. 1839 The following guidelines apply to the usage of YANG extensions: 1841 o The semantics of the extension MUST NOT contradict any YANG 1842 statements. Extensions can add semantics not covered by the 1843 normal YANG statements. 1845 o The module containing the extension statement MUST clearly 1846 identify the conformance requirements for the extension. It 1847 should be clear whether all implementations of the YANG module 1848 containing the extension need to also implement the extension. If 1849 not, identify what conditions apply that would require 1850 implementation of the extension. 1852 o The extension MUST clearly identify where it can be used within 1853 other YANG statements. 1855 o The extension MUST clearly identify if YANG statements or other 1856 extensions are allowed or required within the extension as sub- 1857 statements. 1859 4.22. Data Correlation 1861 Data can be correlated in various ways, using common data types, 1862 common data naming, and common data organization. There are several 1863 ways to extend the functionality of a module, based on the degree of 1864 coupling between the old and new functionality: 1866 o inline: update the module with new protocol-accessible objects. 1867 The naming and data organization of the original objects is used. 1868 The new objects are in the original module namespace. 1870 o augment: create a new module with new protocol-accessible objects 1871 that augment the original data structure. The naming and data 1872 organization of the original objects is used. The new objects are 1873 in the new module namespace. 1875 o mirror: create new objects in a new module or the original module, 1876 except use new a naming scheme and data location. The naming can 1877 be coupled in different ways. Tight coupling is achieved with a 1878 "leafref" data type, with the "require-instance" sub-statement set 1879 to "true". This method SHOULD be used. 1881 If the new data instances are not limited to the values in use in the 1882 original data structure, then the "require-instance" sub-statement 1883 MUST be set to "false". Loose coupling is achieved by using key 1884 leafs with the same data type as the original data structure. This 1885 has the same semantics as setting the "require-instance" sub- 1886 statement to "false". 1888 It is sometimes useful to separate configuration data and operational 1889 state, so that they do not not even share the exact same naming 1890 characteristics. The correlation between configuration the 1891 operational state that is affected by changes in configuration is a 1892 complex problem. There may not be a simple 1:1 relationship between 1893 a configuration data node and an operational state node. Further 1894 work is needed in YANG to clarify this relationship. Protocol work 1895 may also be needed to allow a client to retrieve this type of 1896 information from a server. At this time the best practice is to 1897 clearly document any relationship to other data structures in the 1898 "description" statement. 1900 4.22.1. Use of Leafref for Key Correlation 1902 Sometimes it is not practical to augment a data structure. For 1903 example, the correlated data could have different keys or contain 1904 mandatory nodes. 1906 The following example shows the use of the "leafref" data type for 1907 data correlation purposes: 1909 Not preferred: 1911 list foo { 1912 key name; 1913 leaf name { 1914 type string; 1915 } 1916 ... 1917 } 1919 list foo-addon { 1920 key name; 1921 config false; 1922 leaf name { 1923 type string; 1924 } 1925 ... 1926 } 1928 Preferred: 1930 list foo { 1931 key name; 1932 leaf name { 1933 type string; 1934 } 1935 ... 1936 } 1938 list foo-addon { 1939 key name; 1940 config false; 1941 leaf name { 1942 type leafref { 1943 path "/foo/name"; 1944 require-instance false; 1945 } 1946 } 1947 leaf addon { 1948 type string; 1949 mandatory true; 1950 } 1951 } 1953 4.23. Operational State 1955 The modeling operational state with YANG has been refined over time. 1956 At first, only data that has a "config" statement value of "false" 1957 was considered to be operational state. This data was not considered 1958 to be part of any datastore, which made YANG XPath definition much 1959 more complicated. 1961 Operational state is now modeled using YANG according to new NMDA, 1962 and is now conceptually contained in the operational state datastore, 1963 which also includes the operational values of configuration data. 1964 There is no longer any need to duplicate data structures to provide 1965 separate configuration and operational state sections. 1967 This section describes some data modeling issues related to 1968 operational state, and guidelines for transitioning YANG data model 1969 design to be NMDA-compatible. 1971 4.23.1. Combining Operational State and Configuration Data 1973 If possible, operational state SHOULD be combined with its associated 1974 configuration data. This prevents duplication of key leafs and 1975 ancestor nodes. It also prevents race conditions for retrieval of 1976 dynamic entries, and allows configuration and operational state to be 1977 retrieved together with minimal message overhead. 1979 container foo { 1980 ... 1981 // contains config=true and config=false nodes that have 1982 // no corresponding config=true object (e.g., counters) 1983 } 1985 4.23.2. Representing Operational Values of Configuration Data 1987 If possible the same data type SHOULD be used to represent the 1988 configured value and the operational value, for a given leaf or leaf- 1989 list object. 1991 Sometimes the configured value set is different than the operational 1992 value set for that object. For example, the "admin-state" and 1993 "oper-state" leafs in [RFC7223]. In this case a separate object MAY 1994 be used to represent the configured and operational values. 1996 Sometimes the list keys are not identical for configuration data and 1997 the corresponding operational state. In this case separate lists MAY 1998 be used to represent the configured and operational values. 2000 If it is not possible to combine configuration and operational state, 2001 then the keys used to represent list entries SHOULD be the same type. 2002 The "leafref" data type SHOULD be used in operational state for key 2003 leafs that have corresponding configuration instances. The 2004 "require-instance" statement MAY be set to "false" (in YANG 1.1 2005 modules only) to indicate instances are allowed in the operational 2006 state that do not exist in the associated configuration data. 2008 The need to replicate objects or define different operational state 2009 objects depends on the data model. It is not possible to define one 2010 approach that will be optimal for all data models. 2012 Designers SHOULD describe and justify any NMDA exceptions in detail, 2013 such as the use of separate subtrees and/or separate leafs. The 2014 "description" statements for both the configuration and the 2015 operational state SHOULD be used for this purpose. 2017 4.23.3. NMDA Transition Guidelines 2019 YANG modules SHOULD be designed assuming they will be used on servers 2020 supporting the operational state datastore. With this in mind, YANG 2021 modules SHOULD define config "false" wherever they make sense to the 2022 data model. Config "false" nodes SHOULD NOT be defined to provide 2023 the operational value for configuration nodes, except when the value 2024 space of a configured and operational values may differ, in which 2025 case a distinct config "false" node SHOULD be defined to hold the 2026 operational value for the configured node. 2028 The following guidelines are meant to help modelers develop YANG 2029 modules that will maximize the utility of the model with both current 2030 and new implementations. 2032 New modules and modules that are not concerned with the operational 2033 state of configuration information SHOULD immediately be structured 2034 to be NMDA-compatible, as described in Section 4.23.1. This 2035 transition MAY be deferred if the module does not contain any 2036 configuration datastore objects. 2038 The remaining are options that MAY be followed during the time that 2039 NMDA mechanisms are being defined. 2041 (a) Modules that require immediate support for the NMDA features 2042 SHOULD be structured for NMDA. A temporary non-NMDA version of this 2043 type of module MAY exist, either an existing model or a model created 2044 either by hand or with suitable tools that mirror the current 2045 modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 2046 be published in the same document, with NMDA modules in the document 2047 main body and the non-NMDA modules in a non-normative appendix. The 2048 use of the non-NMDA module will allow temporary bridging of the time 2049 period until NMDA implementations are available. 2051 (b) For published models, the model should be republished with an 2052 NMDA-compatible structure, deprecating non-NMDA constructs. For 2053 example, the "ietf-interfaces" model in [RFC7223] will be 2054 restructured as an NMDA-compatible model. The "/interfaces-state" 2055 hierarchy will be marked "status deprecated". Models that mark their 2056 "/foo-state" hierarchy with "status deprecated" will allow NMDA- 2057 capable implementations to avoid the cost of duplicating the state 2058 nodes, while enabling non-NMDA-capable implementations to utilize 2059 them for access to the operational values. 2061 (c) For models that augment models which have not been structured 2062 with the NMDA, the modeler will have to consider the structure of the 2063 base model and the guidelines listed above. Where possible, such 2064 models should move to new revisions of the base model that are NMDA- 2065 compatible. When that is not possible, augmenting "state" containers 2066 SHOULD be avoided, with the expectation that the base model will be 2067 re-released with the state containers marked as deprecated. It is 2068 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 2069 Where this recommendation cannot be followed, then any new "state" 2070 elements SHOULD be included in their own module. 2072 4.23.3.1. Temporary non-NMDA Modules 2074 A temporary non-NMDA module allows a non-NMDA aware client to access 2075 operational state from an NMDA-compliant server. It contains the 2076 top-level config=false data nodes that would have been defined in a 2077 legacy YANG module (before NMDA). 2079 A server that needs to support both NMDA and non-NMDA clients can 2080 advertise both the new NMDA module and the temporary non-NMDA module. 2081 A non-NMDA client can use separate "foo" and "foo-state" subtrees, 2082 except the "foo-state" subtree is located in a different (temporary) 2083 module. The NMDA module can be used by a non-NMDA client to access 2084 the conventional configuration datastores, and the deprecated 2085 operation to access nested config=false data nodes. 2087 To create the temporary non-NMDA model from an NMDA model, the 2088 following steps can be taken: 2090 o Change the module name by appending "-state" to the original 2091 module name 2093 o Change the namespace by appending "-state" to the original 2094 namespace value 2096 o Change the prefix by appending "-s" to the original prefix value 2098 o Add an import to the original module (e.g., for typedef 2099 definitions) 2101 o Retain or create only the top-level nodes that have a "config" 2102 statement value "false". These subtrees represent config=false 2103 data nodes that were combined into the configuration subtree, and 2104 therefore not available to non-NMDA aware clients. Set the 2105 "status" statement to "deprecated" for each new node. 2107 o The module description SHOULD clearly identify the module as a 2108 temporary non-NMDA module 2110 4.23.3.2. Example: Create a New NMDA Module 2112 Create an NMDA-compliant module, using combined configuration and 2113 state subtrees, whenever possible. 2115 module example-foo { 2116 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2117 prefix "foo"; 2119 container foo { 2120 // configuration data child nodes 2121 // operational value in operational state datastore only 2122 // may contain config=false nodes as needed 2123 } 2125 } 2127 4.23.3.3. Example: Convert an old Non-NMDA Module 2129 Do not remove non-compliant objects from existing modules. Instead, 2130 change the status to "deprecated". At some point, usually after 1 2131 year, the status MAY be changed to "obsolete". 2133 Old Module: 2135 module example-foo { 2136 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2137 prefix "foo"; 2139 container foo { 2140 // configuration data child nodes 2141 } 2143 container foo-state { 2144 config false; 2145 // operational state child nodes 2146 } 2147 } 2149 Converted NMDA Module: 2151 module example-foo { 2152 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2153 prefix "foo"; 2155 container foo { 2156 // configuration data child nodes 2157 // operational value in operational state datastore only 2158 // may contain config=false nodes as needed 2159 // will contain any data nodes from old foo-state 2160 } 2162 // keep original foo-state but change status to deprecated 2163 container foo-state { 2164 config false; 2165 status deprecated; 2166 // operational state child nodes 2167 } 2168 } 2170 4.23.3.4. Example: Create a Temporary NMDA Module: 2172 Create a new module that contains the top-level operational state 2173 data nodes that would have been available before they were combined 2174 with configuration data nodes (to be NMDA compliant). 2176 module example-foo-state { 2177 namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; 2178 prefix "foo-s"; 2180 // import new or converted module; not used in this example 2181 import example-foo { prefix foo; } 2183 container foo-state { 2184 config false; 2185 status deprecated; 2186 // operational state child nodes 2187 } 2188 } 2190 4.24. Performance Considerations 2192 It is generally likely that certain YANG statements require more 2193 runtime resources than other statements. Although there are no 2194 performance requirements for YANG validation, the following 2195 information MAY be considered when designing YANG data models: 2197 o Lists are generally more expensive than containers 2199 o "when-stmt" evaluation is generally more expensive than 2200 "if-feature" or "choice" statements 2202 o "must" statement is generally more expensive than "min-entries", 2203 "max-entries", "mandatory", or "unique" statements 2205 o "identityref" leafs are generally more expensive than 2206 "enumeration" leafs 2208 o "leafref" and "instance-identifier" types with "require-instance" 2209 set to true are generally more expensive than if 2210 "require-instance" is set to false 2212 4.25. Open Systems Considerations 2214 A YANG module MUST NOT be designed such that the set of modules found 2215 on a server implementation can be predetermined in advance. Only the 2216 modules imported by a particular module can be assumed to be present 2217 in an implementation. An open system MAY include any combination of 2218 YANG modules. 2220 4.26. YANG 1.1 Guidelines 2222 The set of YANG 1.1 guidelines will grow as operational experience is 2223 gained with the new language features. This section contains an 2224 initial set of guidelines. 2226 4.26.1. Importing Multiple Revisions 2228 Standard modules SHOULD NOT import multiple revisions of the same 2229 module into a module. This MAY be done if the authors can 2230 demonstrate that the "avoided" definitions from the most recent of 2231 the multiple revisions are somehow broken or harmful to 2232 interoperability. 2234 4.26.2. Using Feature Logic 2236 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2237 "description" statement SHOULD describe the "if-feature" logic in 2238 text, to help readers understand the module. 2240 YANG features SHOULD be used instead of the "when" statement, if 2241 possible. Features are advertised by the server and objects 2242 conditional by if-feature are conceptually grouped together. There 2243 is no such commonality supported for "when" statements. 2245 Features generally require less server implementation complexity and 2246 runtime resources than objects that use "when" statements. Features 2247 are generally static (i.e., set when module is loaded and not changed 2248 at runtime). However every client edit might cause a "when" 2249 statement result to change. 2251 4.26.3. anyxml vs. anydata 2253 The "anyxml" statement MUST NOT be used to represent a conceptual 2254 subtree of YANG data nodes. The "anydata" statement MUST be used for 2255 this purpose. 2257 4.26.4. action vs. rpc 2259 The use of "action" statements or "rpc" statements is a subjective 2260 design decision. RPC operations are not associated with any 2261 particular data node. Actions are associated with a specific data 2262 node definition. An "action" statement SHOULD be used if the 2263 protocol operation is specific to a subset of all data nodes instead 2264 of all possible data nodes. 2266 The same action name MAY be used in different definitions within 2267 different data node. For example, a "reset" action defined with a 2268 data node definition for an interface might have different parameters 2269 than for a power supply or a VLAN. The same action name SHOULD be 2270 used to represent similar semantics. 2272 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2273 parameter access control for RPC operations. The user is given 2274 permission (or not) to invoke the RPC operation with any parameters. 2275 For example, if each client is only allowed to reset their own 2276 interface, then NACM cannot be used. 2278 For example, NACM cannot enforce access access control based on the 2279 value of the "interface" parameter, only the "reset" operation 2280 itself: 2282 rpc reset { 2283 input { 2284 leaf interface { 2285 type if:interface-ref; 2286 mandatory true; 2287 description "The interface to reset."; 2288 } 2289 } 2290 } 2292 However, NACM can enforce access access control for individual 2293 interface instances, using a "reset" action, If the user does not 2294 have read access to the specific "interface" instance, then it cannot 2295 invoke the "reset" action for that interface instance: 2297 container interfaces { 2298 list interface { 2299 ... 2300 action reset { } 2301 } 2302 } 2304 4.27. Updating YANG Modules (Published vs. Unpublished) 2306 YANG modules can change over time. Typically, new data model 2307 definitions are needed to support new features. YANG update rules 2308 defined in section 11 of [RFC7950] MUST be followed for published 2309 modules. They MAY be followed for unpublished modules. 2311 The YANG update rules only apply to published module revisions. Each 2312 organization will have their own way to identify published work which 2313 is considered to be stable, and unpublished work which is considered 2314 to be unstable. For example, in the IETF, the RFC document is used 2315 for published work, and the Internet-Draft is used for unpublished 2316 work. 2318 5. IANA Considerations 2320 -- RFC Ed: These registries need to be updated to reference this 2321 RFC instead of RFC 6087 for the ietf-template module, and 2322 remove this note. 2324 This document registers one URI in the IETF XML registry [RFC3688]. 2326 The following registration has been made in [RFC6087] and updated by 2327 this document. 2329 URI: urn:ietf:params:xml:ns:yang:ietf-template 2331 Registrant Contact: The NETMOD WG of the IETF. 2333 XML: N/A, the requested URI is an XML namespace. 2335 The following assignment has been made in [RFC6087] and updated by 2336 this document in the YANG Module Names Registry, or the YANG module 2337 template in Appendix C. 2339 +-----------+-------------------------------------------+ 2340 | Field | Value | 2341 +-----------+-------------------------------------------+ 2342 | Name | ietf-template | 2343 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2344 | Prefix | temp | 2345 | Reference | RFC XXXX | 2346 +-----------+-------------------------------------------+ 2348 YANG Registry Assignment 2350 6. Security Considerations 2352 This document defines documentation guidelines for NETCONF or 2353 RESTCONF content defined with the YANG data modeling language. The 2354 guidelines for how to write a Security Considerations section for a 2355 YANG module are defined in the online document 2357 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2358 yang-security-guidelines 2360 This document does not introduce any new or increased security risks 2361 into the management system. 2363 The following section contains the security considerations template 2364 dated 2010-06-16. Be sure to check the webpage at the URL listed 2365 above in case there is a more recent version available. 2367 Each specification that defines one or more YANG modules MUST contain 2368 a section that discusses security considerations relevant to those 2369 modules. This section MUST be patterned after the latest approved 2370 template (available at 2372 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2374 In particular, writable data nodes that could be especially 2375 disruptive if abused MUST be explicitly listed by name and the 2376 associated security risks MUST be spelled out. 2378 Similarly, readable data nodes that contain especially sensitive 2379 information or that raise significant privacy concerns MUST be 2380 explicitly listed by name and the reasons for the sensitivity/privacy 2381 concerns MUST be explained. 2383 Further, if new RPC operations have been defined, then the security 2384 considerations of each new RPC operation MUST be explained. 2386 6.1. Security Considerations Section Template 2388 X. Security Considerations 2390 The YANG module defined in this memo is designed to be accessed via 2391 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2392 secure transport layer and the mandatory-to-implement secure 2393 transport is SSH [RFC6242]. 2395 -- if you have any writable data nodes (those are all the 2396 -- "config true" nodes, and remember, that is the default) 2397 -- describe their specific sensitivity or vulnerability. 2399 There are a number of data nodes defined in this YANG module which 2400 are writable/creatable/deletable (i.e., config true, which is the 2401 default). These data nodes may be considered sensitive or vulnerable 2402 in some network environments. Write operations (e.g., edit-config) 2403 to these data nodes without proper protection can have a negative 2404 effect on network operations. These are the subtrees and data nodes 2405 and their sensitivity/vulnerability: 2407 2409 -- for all YANG modules you must evaluate whether any readable data 2410 -- nodes (those are all the "config false" nodes, but also all other 2411 -- nodes, because they can also be read via operations like get or 2412 -- get-config) are sensitive or vulnerable (for instance, if they 2413 -- might reveal customer information or violate personal privacy 2414 -- laws such as those of the European Union if exposed to 2415 -- unauthorized parties) 2417 Some of the readable data nodes in this YANG module may be considered 2418 sensitive or vulnerable in some network environments. It is thus 2419 important to control read access (e.g., via get, get-config, or 2420 notification) to these data nodes. These are the subtrees and data 2421 nodes and their sensitivity/vulnerability: 2423 2425 -- if your YANG module has defined any rpc operations 2426 -- describe their specific sensitivity or vulnerability. 2428 Some of the RPC operations in this YANG module may be considered 2429 sensitive or vulnerable in some network environments. It is thus 2430 important to control access to these operations. These are the 2431 operations and their sensitivity/vulnerability: 2433 2435 7. Acknowledgments 2437 The structure and contents of this document are adapted from 2438 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2440 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2441 Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive 2442 reviews and contributions to this document. 2444 8. Changes Since RFC 6087 2446 The following changes have been made to the guidelines published in 2447 [RFC6087]: 2449 o Updated NETCONF reference from RFC 4741 to RFC 6241 2451 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2453 o Updated YANG Types reference from RFC 6021 to RFC 6991 2455 o Updated obsolete URLs for IETF resources 2457 o Changed top-level data node guideline 2459 o Clarified XPath usage for a literal value representing a YANG 2460 identity 2462 o Clarified XPath usage for a when-stmt 2464 o Clarified XPath usage for 'proceeding-sibling' and 2465 'following-sibling' axes 2467 o Added terminology guidelines 2469 o Added YANG tree diagram definition and guideline 2471 o Updated XPath guidelines for type conversions and function library 2472 usage. 2474 o Updated data types section 2476 o Updated notifications section 2478 o Clarified conditional key leaf nodes 2480 o Clarify usage of 'uint64' and 'int64' data types 2482 o Added text on YANG feature usage 2484 o Added Identifier Naming Conventions 2486 o Clarified use of mandatory nodes with conditional augmentations 2488 o Clarified namespace and domain conventions for example modules 2490 o Clarified conventions for identifying code components 2491 o Added YANG 1.1 guidelines 2493 o Added Data Model Constraints section 2495 o Added mention of RESTCONF protocol 2497 o Added guidelines for NMDA Revised Datastores 2499 9. References 2501 9.1. Normative References 2503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2504 Requirement Levels", BCP 14, RFC 2119, March 1997. 2506 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2507 January 2004. 2509 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2510 Resource Identifier (URI): Generic Syntax", STD 66, 2511 RFC 3986, January 2005. 2513 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2514 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2516 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2517 Network Configuration Protocol (NETCONF)", RFC 6020, 2518 October 2010. 2520 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2521 July 2013. 2523 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2524 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2525 . 2527 [W3C.REC-xpath-19991116] 2528 Clark, J. and S. DeRose, "XML Path Language (XPath) 2529 Version 1.0", World Wide Web Consortium 2530 Recommendation REC-xpath-19991116, November 1999, 2531 . 2533 9.2. Informative References 2535 [I-D.ietf-netmod-revised-datastores] 2536 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2537 and R. Wilton, "Network Management Datastore 2538 Architecture", draft-ietf-netmod-revised-datastores-04 2539 (work in progress), August 2017. 2541 [I-D.ietf-netmod-yang-tree-diagrams] 2542 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2543 draft-ietf-netmod-yang-tree-diagrams-01 (work in 2544 progress), June 2017. 2546 [RFC-STYLE] 2547 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2548 Style", September 2009, 2549 . 2551 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2552 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2553 . 2555 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2556 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2557 . 2559 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2560 Documents", BCP 111, RFC 4181, September 2005. 2562 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2563 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2564 May 2008. 2566 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2567 Data Model Documents", RFC 6087, January 2011. 2569 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2570 and A. Bierman, Ed., "Network Configuration Protocol 2571 (NETCONF)", RFC 6241, June 2011. 2573 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2574 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2575 . 2577 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2578 Protocol (NETCONF) Access Control Model", RFC 6536, 2579 March 2012. 2581 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2582 Management", RFC 7223, May 2014. 2584 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2585 DOI 10.17487/RFC7322, September 2014, 2586 . 2588 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2589 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2590 DOI 10.17487/RFC7841, May 2016, 2591 . 2593 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2594 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2595 . 2597 Appendix A. Change Log 2599 -- RFC Ed.: remove this section before publication. 2601 A.1. v13 to v14 2603 o Replaced sec. 4.23 Operational Data with Operational Data from 2604 NMDA text by Lou Berger and Kent Watsen 2606 o Added NMDA Terms section 2608 o Changed term operational data to operational state 2610 o Clarified that reference-stmt SHOULD be present in import-stmt 2612 A.2. v12 to v13 2614 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2615 YANG file extraction macro. 2617 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2618 module name registries. 2620 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2622 o Update Operation Data section to consider revised datastores. 2624 o Add reference to YANG Tree Diagrams and update 2 sections that use 2625 this reference. 2627 o Add reference to Revised Datastores and guidelines drafts 2629 A.3. v11 to v12 2631 o fix incorrect location of new Module Usage Examples section 2633 A.4. v10 to v11 2635 o updated YANG tree diagram syntax to align with pyang 1.7.1 2637 o added general guideline to include module usage examples 2639 A.5. v09 to v10 2641 o clarified is only for normative modules 2643 o clarified example module namespace URI conventions 2644 o clarified pyang usage for normative and example modules 2646 o updated YANG tree diagrams section with text from RFC 8022 2648 A.6. v08 to v09 2650 o fixed references 2652 o added mention of RESTCONF to abstract and intro 2654 o created separate section for code components 2656 o fixed document status 2658 A.7. v07 to v08 2660 o changed CODE BEGINS guideline for example modules 2662 o updated tree diagram guidelines 2664 o clarified published and unpublished terms 2666 o added section on Empty and Boolean data types 2668 o clarified how to update the revision statement 2670 o updated operational state guidelines 2672 o added 'YANG fragment' to terminology section 2674 A.8. v06 to v07 2676 o update contact statement guideline 2678 o update example modules guidelines 2680 o add guidelines on top-level data nodes 2682 o add guideline on use of NP containers 2684 o added guidelines on union types 2686 o add guideline on deviations 2688 o added section on open systems considerations 2690 o added guideline about definitions reserved for future use 2692 A.9. v05 to v06 2694 o Changed example 'my-module' to 'example-module' 2696 o Added section Updating YANG Modules (Published vs. Unpublished) 2698 o Added Example Modules section 2700 o Added "" convention for full example modules 2702 o Added section on using action vs. rpc 2704 o Changed term "operational state" to "operational data" 2706 o Added section on YANG Data Node Constraints 2708 o Added guidelines on using must vs. when statements 2710 o Made ietf-foo module validate for I-D submission 2712 A.10. v04 to v05 2714 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2715 no YANG 1.1 features needed 2717 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2718 standards track documents only) 2720 o Clarified module naming conventions for normative modules, example 2721 modules, and modules from other SDOs. 2723 o Added prefix value selection guidelines 2725 o Added new section on guidelines for reusable groupings 2727 o Made header guidelines less IETF-specific 2729 o Added new section on guidelines for extension statements 2731 o Added guidelines for nested "choice" statement within a "case" 2732 statement 2734 A.11. v03 ot v04 2736 o Added sections for deviation statements and performance 2737 considerations 2739 o Added YANG 1.1 section 2741 o Updated YANG reference from 1.0 to 1.1 2743 A.12. v02 to v03 2745 o Updated draft based on github data tracker issues added by Benoit 2746 Clause (Issues 12 - 18) 2748 A.13. v01 to v02 2750 o Updated draft based on mailing list comments. 2752 A.14. v00 to v01 2754 All issues from the issue tracker have been addressed. 2756 https://github.com/netmod-wg/rfc6087bis/issues 2758 o Issue 1: Tree Diagrams: Added Section 2.5.1 so RFCs with YANG 2759 modules can use an Informative reference to this RFC for tree 2760 diagrams. Updated guidelines to reference this RFC when tree 2761 diagrams are used 2763 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2764 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2765 functions 2767 o Issue 3: XPath function document order issues: Added paragraph in 2768 XPath usage section about node-set ordering for 'local-name', 2769 'namespace-uri', 'name', 'string' and 'number' functions. Also 2770 any function that implicitly converts a node-set to a string. 2772 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2773 and text in XPath usage section already has proposed text from 2774 Lada. 2776 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2777 exception and example in XPath Usage section for augmented nodes. 2779 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2780 to 'numeric and boolean expressions' 2782 o Issue 7: XPath module containment: Added sub-section on XPath 2783 wildcards 2785 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2786 section about transitioning from active to deprecated and then to 2787 obsolete. 2789 o Issue 9: resource identification in notifications: Add text to 2790 Notifications section about identifying resources and using the 2791 leafref data type. 2793 o Issue 10: single quoted strings: Added text to Data Types section 2794 about using a single-quoted string for patterns. 2796 Appendix B. Module Review Checklist 2798 This section is adapted from RFC 4181. 2800 The purpose of a YANG module review is to review the YANG module both 2801 for technical correctness and for adherence to IETF documentation 2802 requirements. The following checklist may be helpful when reviewing 2803 an Internet-Draft: 2805 o I-D Boilerplate -- verify that the draft contains the required 2806 Internet-Draft boilerplate (see 2807 http://www.ietf.org/id-info/guidelines.html), including the 2808 appropriate statement to permit publication as an RFC, and that 2809 I-D boilerplate does not contain references or section numbers. 2811 o Abstract -- verify that the abstract does not contain references, 2812 that it does not have a section number, and that its content 2813 follows the guidelines in 2814 http://www.ietf.org/id-info/guidelines.html. 2816 o Copyright Notice -- verify that the draft has the appropriate text 2817 regarding the rights that document contributers provide to the 2818 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2819 copyright notice at the beginning of the document. The IETF Trust 2820 Legal Provisions (TLP) can be found at: 2822 http://trustee.ietf.org/license-info/ 2824 o Security Considerations section -- verify that the draft uses the 2825 latest approved template from the OPS area website (http:// 2826 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2827 and that the guidelines therein have been followed. 2829 o IANA Considerations section -- this section must always be 2830 present. For each module within the document, ensure that the 2831 IANA Considerations section contains entries for the following 2832 IANA registries: 2834 XML Namespace Registry: Register the YANG module namespace. 2836 YANG Module Registry: Register the YANG module name, prefix, 2837 namespace, and RFC number, according to the rules specified 2838 in [RFC7950]. 2840 o References -- verify that the references are properly divided 2841 between normative and informative references, that RFC 2119 is 2842 included as a normative reference if the terminology defined 2843 therein is used in the document, that all references required by 2844 the boilerplate are present, that all YANG modules containing 2845 imported items are cited as normative references, and that all 2846 citations point to the most current RFCs unless there is a valid 2847 reason to do otherwise (for example, it is OK to include an 2848 informative reference to a previous version of a specification to 2849 help explain a feature included for backward compatibility). Be 2850 sure citations for all imported modules are present somewhere in 2851 the document text (outside the YANG module). 2853 o License -- verify that the draft contains the Simplified BSD 2854 License in each YANG module or submodule. Some guidelines related 2855 to this requirement are described in Section 3.1. Make sure that 2856 the correct year is used in all copyright dates. Use the approved 2857 text from the latest Trust Legal Provisions (TLP) document, which 2858 can be found at: 2860 http://trustee.ietf.org/license-info/ 2862 o Other Issues -- check for any issues mentioned in 2863 http://www.ietf.org/id-info/checklist.html that are not covered 2864 elsewhere. 2866 o Technical Content -- review the actual technical content for 2867 compliance with the guidelines in this document. The use of a 2868 YANG module compiler is recommended when checking for syntax 2869 errors. A list of freely available tools and other information 2870 can be found at: 2872 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2874 Checking for correct syntax, however, is only part of the job. 2875 It is just as important to actually read the YANG module document 2876 from the point of view of a potential implementor. It is 2877 particularly important to check that description statements are 2878 sufficiently clear and unambiguous to allow interoperable 2879 implementations to be created. 2881 Appendix C. YANG Module Template 2883 file "ietf-template@2016-03-20.yang" 2885 module ietf-template { 2887 // replace this string with a unique namespace URN value 2888 namespace 2889 "urn:ietf:params:xml:ns:yang:ietf-template"; 2891 // replace this string, and try to pick a unique prefix 2892 prefix "temp"; 2894 // import statements here: e.g., 2895 // import ietf-yang-types { prefix yang; } 2896 // import ietf-inet-types { prefix inet; } 2898 // identify the IETF working group if applicable 2899 organization 2900 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2902 // update this contact statement with your info 2903 contact 2904 "WG Web: 2905 WG List: 2907 Editor: your-name 2908 "; 2910 // replace the first sentence in this description statement. 2911 // replace the copyright notice with the most recent 2912 // version, if it has been updated since the publication 2913 // of this document 2914 description 2915 "This module defines a template for other YANG modules. 2917 Copyright (c) IETF Trust and the persons 2918 identified as authors of the code. All rights reserved. 2920 Redistribution and use in source and binary forms, with or 2921 without modification, is permitted pursuant to, and subject 2922 to the license terms contained in, the Simplified BSD License 2923 set forth in Section 4.c of the IETF Trust's Legal Provisions 2924 Relating to IETF Documents 2925 (http://trustee.ietf.org/license-info). 2927 This version of this YANG module is part of RFC XXXX; see 2928 the RFC itself for full legal notices."; 2930 // RFC Ed.: replace XXXX with actual RFC number and remove 2931 // this note 2933 reference "RFC XXXX"; 2935 // RFC Ed.: remove this note 2936 // Note: extracted from RFC XXXX 2938 // replace '2016-03-20' with the module publication date 2939 // The format is (year-month-day) 2940 revision "2016-03-20" { 2941 description "what changed in this revision"; 2942 reference "document containing this module"; 2943 } 2945 // extension statements 2947 // feature statements 2949 // identity statements 2951 // typedef statements 2953 // grouping statements 2955 // data definition statements 2957 // augment statements 2959 // rpc statements 2961 // notification statements 2963 // DO NOT put deviation statements in a published module 2965 } 2967 2969 Author's Address 2971 Andy Bierman 2972 YumaWorks 2974 Email: andy@yumaworks.com