idnits 2.17.1 draft-ietf-netmod-rfc6087bis-19.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 11, 2018) is 2238 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: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC5378' is defined on line 2581, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ID-Guidelines' ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-07) exists of draft-flanagan-7322bis-02 -- 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: 1 error (**), 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) March 11, 2018 5 Intended status: BCP 6 Expires: September 12, 2018 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-19 11 Abstract 13 This memo provides guidelines for authors and reviewers of 14 specifications containing YANG data model modules. Recommendations 15 and procedures are defined, which are intended to increase 16 interoperability and usability of Network Configuration Protocol 17 (NETCONF) and RESTCONF protocol implementations that utilize YANG 18 data model modules. This document obsoletes RFC 6087. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 12, 2018. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 57 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8 58 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8 59 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 60 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 61 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 3. General Documentation Guidelines . . . . . . . . . . . . . . . 10 63 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10 64 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 11 65 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11 66 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11 67 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 12 68 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 69 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 13 70 3.7. Security Considerations Section . . . . . . . . . . . . . 13 71 3.7.1. Security Considerations Section Template . . . . . . . 14 72 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 15 73 3.8.1. Documents that Create a New Namespace . . . . . . . . 15 74 3.8.2. Documents that Extend an Existing Namespace . . . . . 16 75 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 16 76 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 77 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 17 78 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 17 79 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 18 80 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 18 81 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 20 83 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 20 84 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 21 85 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 21 86 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 22 87 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 22 88 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 23 89 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 24 90 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 24 91 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 25 92 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 26 93 4.7. YANG Definition Lifecycle Management . . . . . . . . . . . 27 94 4.8. Module Header, Meta, and Revision Statements . . . . . . . 28 95 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 29 96 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 31 97 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 31 98 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 32 99 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 32 100 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 33 101 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 34 102 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 35 103 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 36 104 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 37 105 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 37 106 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 39 107 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 40 108 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 40 109 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 40 110 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 41 111 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 42 112 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 42 113 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 42 114 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 42 115 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 43 116 4.19.2. Conditionally Mandatory Data Definition Statements . . 43 117 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 44 118 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45 119 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 46 120 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 47 121 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 48 122 4.23.1. Combining Operational State and Configuration Data . . 48 123 4.23.2. Representing Operational Values of Configuration 124 Data . . . . . . . . . . . . . . . . . . . . . . . . . 49 125 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 49 126 4.24. Performance Considerations . . . . . . . . . . . . . . . . 53 127 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 54 128 4.26. Guidelines for YANG 1.1 Specific Constructs . . . . . . . 54 129 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 54 130 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 54 131 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 55 132 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 55 133 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 56 134 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 135 6. Security Considerations . . . . . . . . . . . . . . . . . . . 58 136 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59 137 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 138 8.1. Normative References . . . . . . . . . . . . . . . . . . . 60 139 8.2. Informative References . . . . . . . . . . . . . . . . . . 61 140 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 63 141 A.1. v18 to v19 . . . . . . . . . . . . . . . . . . . . . . . . 63 142 A.2. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 63 143 A.3. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 63 144 A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 145 A.5. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 146 A.6. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 63 147 A.7. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 63 148 A.8. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 64 149 A.9. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 64 150 A.10. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 64 151 A.11. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 64 152 A.12. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 64 153 A.13. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 65 154 A.14. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 65 155 A.15. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 65 156 A.16. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 66 157 A.17. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 66 158 A.18. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 66 159 A.19. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 67 160 A.20. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 67 161 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 68 162 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 70 163 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 165 1. Introduction 167 The standardization of network configuration interfaces for use with 168 network configuration management protocols, such as the Network 169 Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a 170 modular set of data models, which can be reused and extended over 171 time. 173 This document defines a set of usage guidelines for documents 174 containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models. 175 YANG is used to define the data structures, protocol operations, and 176 notification content used within a NETCONF and/or RESTCONF server. A 177 NETCONF or RESTCONF server that supports a particular YANG module 178 will support client NETCONF and/or RESTCONF operation requests, as 179 indicated by the specific content defined in the YANG module. 181 Many YANG constructs are defined as optional to use, such as the 182 description statement. However, in order to make YANG modules more 183 useful, it is desirable to define a set of usage guidelines that 184 entails a higher level of compliance than the minimum level defined 185 in the YANG specification. 187 In addition, YANG allows constructs such as infinite length 188 identifiers and string values, or top-level mandatory nodes, that a 189 compliant server is not required to support. Only constructs that 190 all servers are required to support can be used in IETF YANG modules. 192 This document defines usage guidelines related to the NETCONF 193 operations layer and NETCONF content layer, as defined in [RFC6241], 194 and the RESTCONF methods and RESTCONF resources, as defined in 195 [RFC8040], 197 These guidelines are intended to be used by authors and reviewers to 198 improve the readability and interoperability of published YANG data 199 models. 201 Note that this document is not a YANG tutorial and the reader is 202 expected to know the YANG data modeling language before using this 203 document. 205 1.1. Changes Since RFC 6087 207 The following changes have been made to the guidelines published in 208 [RFC6087]: 210 o Updated NETCONF reference from RFC 4741 to RFC 6241 211 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 213 o Updated YANG Types reference from RFC 6021 to RFC 6991 215 o Updated obsolete URLs for IETF resources 217 o Changed top-level data node guideline 219 o Clarified XPath usage for a literal value representing a YANG 220 identity 222 o Clarified XPath usage for a when-stmt 224 o Clarified XPath usage for 'proceeding-sibling' and 225 'following-sibling' axes 227 o Added terminology guidelines 229 o Added YANG tree diagram guidelines 231 o Updated XPath guidelines for type conversions and function library 232 usage. 234 o Updated data types section 236 o Updated notifications section 238 o Clarified conditional key leaf nodes 240 o Clarify usage of 'uint64' and 'int64' data types 242 o Added text on YANG feature usage 244 o Added Identifier Naming Conventions 246 o Clarified use of mandatory nodes with conditional augmentations 248 o Clarified namespace and domain conventions for example modules 250 o Clarified conventions for identifying code components 252 o Added YANG 1.1 guidelines 254 o Added Data Model Constraints section 256 o Added mention of RESTCONF protocol 257 o Added guidelines for NMDA Revised Datastores 259 2. Terminology 261 2.1. Requirements Notation 263 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 264 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 265 document are to be interpreted as described in BCP 14 [RFC2119] 266 [RFC8174] when, and only when, they appear in all capitals, as shown 267 here. 269 2.2. NETCONF Terms 271 The following terms are defined in [RFC6241] and are not redefined 272 here: 274 o capabilities 276 o client 278 o operation 280 o server 282 2.3. YANG Terms 284 The following terms are defined in [RFC7950] and are not redefined 285 here: 287 o data node 289 o module 291 o namespace 293 o submodule 295 o version 297 o YANG 299 o YIN 301 Note that the term 'module' may be used as a generic term for a YANG 302 module or submodule. When describing properties that are specific to 303 submodules, the term 'submodule' is used instead. 305 2.4. NMDA Terms 307 The following terms are defined in the Network Management Datastore 308 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not 309 redefined here: 311 o configuration 313 o conventional configuration datastore 315 o datastore 317 o operational state 319 o operational state datastore 321 2.5. Terms 323 The following terms are used throughout this document: 325 o published: A stable release of a module or submodule. For example 326 the "Request for Comments" described in section 2.1 of [RFC2026] 327 is considered a stable publication. 329 o unpublished: An unstable release of a module or submodule. For 330 example the "Internet-Draft" described in section 2.2 of [RFC2026] 331 is considered an unstable publication that is a work-in-progress, 332 subject to change at any time. 334 o YANG fragment: A set of YANG statements that are not intended to 335 represent a complete YANG module or submodule. These statements 336 are not intended for actual use, except to provide an example of 337 YANG statement usage. The invalid syntax "..." is sometimes used 338 to indicate that additional YANG statements would be present in a 339 real YANG module. 341 o YANG tree diagram: a diagram representing the contents of a YANG 342 module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also 343 called a "tree diagram". 345 3. General Documentation Guidelines 347 YANG data model modules under review are likely to be contained in 348 Internet-Drafts. All guidelines for Internet-Draft authors 349 [ID-Guidelines] MUST be followed. The RFC Editor provides guidelines 350 for authors of RFCs, which are first published as Internet-Drafts. 351 These guidelines should be followed and are defined in [RFC7322] and 352 updated in [RFC7841], "RFC Document Style" [RFC-STYLE], and 353 [I-D.flanagan-7322bis]. 355 The following sections MUST be present in an Internet-Draft 356 containing a module: 358 o Narrative sections 360 o Definitions section 362 o Security Considerations section 364 o IANA Considerations section 366 o References section 368 There are three usage scenarios for YANG that can appear in an 369 Internet-Draft or RFC: 371 o normative module or submodule 373 o example module or submodule 375 o example YANG fragment not part of any module or submodule 377 The guidelines in this document refer mainly to a normative module or 378 submodule, but may be applicable to example modules and YANG 379 fragments as well. 381 3.1. Module Copyright 383 The module description statement MUST contain a reference to the 384 latest approved IETF Trust Copyright statement, which is available 385 online at: 387 https://trustee.ietf.org/license-info/ 389 3.2. Code Components 391 Each normative YANG module or submodule contained within an Internet- 392 Draft or RFC is considered to be a code component. The strings 393 "" and "" MUST be used to identify each code 394 component. 396 The "" tag SHOULD be followed by a string identifying 397 the file name specified in Section 5.2 of [RFC7950]. The name string 398 form that includes the revision-date SHOULD be used. The revision 399 date MUST match the date used in the most recent revision of the 400 module. 402 The following example is for the '2016-03-20' revision of the 403 'ietf-foo' module: 405 file "ietf-foo@2016-03-20.yang" 407 module ietf-foo { 408 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 409 prefix "foo"; 410 organization "..."; 411 contact "..."; 412 description "..."; 413 revision 2016-03-20 { 414 description "Latest revision"; 415 reference "RFC XXXX"; 416 } 417 // ... more statements 418 } 420 422 3.2.1. Example Modules 424 Example modules are not code components. The 425 convention MUST NOT be used for example modules. 427 An example module SHOULD be named using the term "example", followed 428 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 429 See Section 4.9 regarding the namespace guidelines for example 430 modules. 432 3.3. Terminology Section 434 A terminology section MUST be present if any terms are defined in the 435 document or if any terms are imported from other documents. 437 3.4. Tree Diagrams 439 YANG tree diagrams provide a concise representation of a YANG module, 440 and SHOULD be included to help readers understand YANG module 441 structure. Guidelines on tree diagrams can be found in Section 3 of 442 [I-D.ietf-netmod-yang-tree-diagrams]. 444 If YANG tree diagrams are used, then an informative reference to the 445 YANG tree diagrams specification MUST be included in the document. 446 Refer to Section 2.2 of [I-D.ietf-netmod-rfc8022bis] for an example 447 of such a reference. 449 3.5. Narrative Sections 451 The narrative part MUST include an overview section that describes 452 the scope and field of application of the module(s) defined by the 453 specification and that specifies the relationship (if any) of these 454 modules to other standards, particularly to standards containing 455 other YANG modules. The narrative part SHOULD include one or more 456 sections to briefly describe the structure of the modules defined in 457 the specification. 459 If the module(s) defined by the specification imports definitions 460 from other modules (except for those defined in the [RFC7950] or 461 [RFC6991] documents), or are always implemented in conjunction with 462 other modules, then those facts MUST be noted in the overview 463 section, as MUST be noted any special interpretations of definitions 464 in other modules. Refer to section 2.3 of 465 [I-D.ietf-netmod-rfc8022bis] for an example of this overview section. 467 If the documents contains YANG module(s) that are compliant with the 468 Network Management Datastore Architecture (NMDA) 469 [I-D.ietf-netmod-revised-datastores], then the Introduction section 470 should mention this fact. 472 Example: 474 The YANG model in this document conforms to the Network 475 Management Datastore Architecture defined in 476 [I-D.ietf-netmod-revised-datastores]. 478 Consistent indentation SHOULD be used for all examples, including 479 YANG fragments and protocol message instance data. If line wrapping 480 is done for formatting purposes, then this SHOULD be noted, as shown 481 in the following example: 483 [note: '\' line wrapping for formatting only] 484 \ 485 this is a long value so the line needs to wrap to stay\ 486 within 72 characters\ 487 489 3.6. Definitions Section 491 This section contains the module(s) defined by the specification. 492 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 493 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 494 semantics are needed in the module. If any of the imported YANG 495 modules are written using YANG 1.1, then the module MUST be written 496 using YANG 1.1. 498 A YIN syntax version of the module MAY also be present in the 499 document. There MAY also be other types of modules present in the 500 document, such as SMIv2, which are not affected by these guidelines. 502 Note that if the module itself is considered normative and not an 503 example module or example YANG fragment, then all YANG statements 504 within a YANG module are considered normative. The use of keywords 505 defined in [RFC2119] apply to YANG description statements in 506 normative modules exactly as they would in any other normative 507 section. 509 Example YANG modules and example YANG fragments MUST NOT contain any 510 normative text, including any all-uppercase reserved words from 511 [RFC2119]. 513 Consistent indentation and formatting SHOULD be used in all YANG 514 statements within a module. 516 See Section 4 for guidelines on YANG usage. 518 3.7. Security Considerations Section 520 Each specification that defines one or more modules MUST contain a 521 section that discusses security considerations relevant to those 522 modules. 524 This section MUST be patterned after the latest approved template 525 (available at 526 https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines). 527 Section 3.7.1 contains the security considerations template dated 528 2013-05-08 and last updated 2017-12-21. Authors MUST check the WEB 529 page at the URL listed above in case there is a more recent version 530 available. 532 In particular: 534 o Writable data nodes that could be especially disruptive if abused 535 MUST be explicitly listed by name and the associated security 536 risks MUST be explained. 538 o Readable data nodes that contain especially sensitive information 539 or that raise significant privacy concerns MUST be explicitly 540 listed by name and the reasons for the sensitivity/privacy 541 concerns MUST be explained. 543 o Operations (i.e., YANG 'rpc' statements) that are potentially 544 harmful to system behavior or that raise significant privacy 545 concerns MUST be explicitly listed by name and the reasons for the 546 sensitivity/privacy concerns MUST be explained. 548 3.7.1. Security Considerations Section Template 550 X. Security Considerations 552 The YANG module specified in this document defines a schema for data 553 that is designed to be accessed via network management protocols such 554 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 555 is the secure transport layer, and the mandatory-to-implement secure 556 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 557 is HTTPS, and the mandatory-to-implement secure transport is TLS 558 [RFC5246]. 560 The NETCONF access control model [RFC6536] provides the means to 561 restrict access for particular NETCONF or RESTCONF users to a 562 preconfigured subset of all available NETCONF or RESTCONF protocol 563 operations and content. 565 -- if you have any writeable data nodes (those are all the 566 -- "config true" nodes, and remember, that is the default) 567 -- describe their specific sensitivity or vulnerability. 569 There are a number of data nodes defined in this YANG module that are 570 writable/creatable/deletable (i.e., config true, which is the 571 default). These data nodes may be considered sensitive or vulnerable 572 in some network environments. Write operations (e.g., edit-config) 573 to these data nodes without proper protection can have a negative 574 effect on network operations. These are the subtrees and data nodes 575 and their sensitivity/vulnerability: 577 578 -- for all YANG modules you must evaluate whether any readable data 579 -- nodes (those are all the "config false" nodes, but also all other 580 -- nodes, because they can also be read via operations like get or 581 -- get-config) are sensitive or vulnerable (for instance, if they 582 -- might reveal customer information or violate personal privacy 583 -- laws such as those of the European Union if exposed to 584 -- unauthorized parties) 586 Some of the readable data nodes in this YANG module may be considered 587 sensitive or vulnerable in some network environments. It is thus 588 important to control read access (e.g., via get, get-config, or 589 notification) to these data nodes. These are the subtrees and data 590 nodes and their sensitivity/vulnerability: 592 594 -- if your YANG module has defined any rpc operations 595 -- describe their specific sensitivity or vulnerability. 597 Some of the RPC operations in this YANG module may be considered 598 sensitive or vulnerable in some network environments. It is thus 599 important to control access to these operations. These are the 600 operations and their sensitivity/vulnerability: 602 604 3.8. IANA Considerations Section 606 In order to comply with IESG policy as set forth in 607 https://www.ietf.org/id-info/checklist.html, every Internet-Draft 608 that is submitted to the IESG for publication MUST contain an IANA 609 Considerations section. The requirements for this section vary 610 depending on what actions are required of the IANA. If there are no 611 IANA considerations applicable to the document, then the IANA 612 Considerations section stating that there are no actions might be 613 removed by the RFC Editor before publication. Refer to the 614 guidelines in [RFC8126] for more details. 616 Each normative YANG module MUST be registered in the XML namespace 617 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 618 This applies to new modules and updated modules. Examples of these 619 registrations for the "ietf-template" module can be found in 620 Section 5. 622 3.8.1. Documents that Create a New Namespace 624 If an Internet-Draft defines a new namespace that is to be 625 administered by the IANA, then the document MUST include an IANA 626 Considerations section that specifies how the namespace is to be 627 administered. 629 Specifically, if any YANG module namespace statement value contained 630 in the document is not already registered with IANA, then a new YANG 631 Namespace registry entry MUST be requested from the IANA. The 632 [RFC7950] specification includes the procedure for this purpose in 633 its IANA Considerations section. 635 3.8.2. Documents that Extend an Existing Namespace 637 It is possible to extend an existing namespace using a YANG submodule 638 that belongs to an existing module already administered by IANA. In 639 this case, the document containing the main module MUST be updated to 640 use the latest revision of the submodule. 642 3.9. Reference Sections 644 For every import or include statement that appears in a module 645 contained in the specification, that identifies a module in a 646 separate document, a corresponding normative reference to that 647 document MUST appear in the Normative References section. The 648 reference MUST correspond to the specific module version actually 649 used within the specification. 651 For every normative reference statement that appears in a module 652 contained in the specification, that identifies a separate document, 653 a corresponding normative reference to that document SHOULD appear in 654 the Normative References section. The reference SHOULD correspond to 655 the specific document version actually used within the specification. 656 If the reference statement identifies an informative reference, that 657 identifies a separate document, a corresponding informative reference 658 to that document MAY appear in the Informative References section. 660 3.10. Validation Tools 662 All modules need to be validated before submission in an Internet 663 Draft. The 'pyang' YANG compiler is freely available from github: 665 https://github.com/mbj4668/pyang 667 If the 'pyang' compiler is used to validate a normative module, then 668 the "--ietf" command line option MUST be used to identify any IETF 669 guideline issues. 671 If the 'pyang' compiler is used to validate an example module, then 672 the "--ietf" command line option MAY be used to identify any IETF 673 guideline issues. 675 The "yanglint" program is also freely available from github. 677 https://github.com/CESNET/libyang 679 This tool can be used to validate XPath statements within YANG 680 modules. 682 3.11. Module Extraction Tools 684 A version of 'rfcstrip' is available which will extract YANG modules 685 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 686 YANG module extraction is freely available: 688 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 690 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 692 can be extracted correctly. 694 The "xym" tool is freely available on github and can be used to 695 extract YANG modules from a document. 697 https://github.com/xym-tool/xym 699 3.12. Module Usage Examples 701 Each specification that defines one or more modules SHOULD contain 702 usage examples, either throughout the document or in an appendix. 703 This includes example instance document snippets in an appropriate 704 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 705 the YANG module(s). Example modules MUST be validated. Refer to 706 Section 3.10 for tools which validate YANG modules. If IP addresses 707 are used, then either a mix of IPv4 and IPv6 addresses or IPv6 708 addresses exclusively SHOULD be used in the examples. 710 4. YANG Usage Guidelines 712 Modules in IETF Standards Track specifications MUST comply with all 713 syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the 714 exception for YANG 1.0 in Section 3.6. The guidelines in this 715 section are intended to supplement the YANG specification, which is 716 intended to define a minimum set of conformance requirements. 718 In order to promote interoperability and establish a set of practices 719 based on previous experience, the following sections establish usage 720 guidelines for specific YANG constructs. 722 Only guidelines that clarify or restrict the minimum conformance 723 requirements are included here. 725 4.1. Module Naming Conventions 727 Normative modules contained in Standards Track documents MUST be 728 named according to the guidelines in the IANA Considerations section 729 of [RFC7950]. 731 A distinctive word or acronym (e.g., protocol name or working group 732 acronym) SHOULD be used in the module name. If new definitions are 733 being defined to extend one or more existing modules, then the same 734 word or acronym should be reused, instead of creating a new one. 736 All published module names MUST be unique. For a YANG module 737 published in an RFC, this uniqueness is guaranteed by IANA. For 738 unpublished modules, the authors need to check that no other work in 739 progress is using the same module name. 741 Example modules are non-normative, and SHOULD be named with the 742 prefix "example-". 744 It is suggested that a stable prefix be selected representing the 745 entire organization. All normative YANG modules published by the 746 IETF MUST begin with the prefix "ietf-". Another standards 747 organization, such as the IEEE, might use the prefix "ieee-" for all 748 YANG modules. 750 Once a module name is published, it MUST NOT be reused, even if the 751 RFC containing the module is reclassified to 'Historic' status. A 752 module name cannot be changed in YANG, and this would be treated as a 753 a new module, not a name change. 755 4.2. Prefixes 757 All YANG definitions are scoped by the module containing the 758 definition being referenced. This allows definitions from multiple 759 modules to be used, even if the names are not unique. In the example 760 below, the identifier "foo" is used in all 3 modules: 762 module example-foo { 763 namespace "tag:example.com,2017:example-foo"; 764 prefix f; 766 container foo; 767 } 769 module example-bar { 770 namespace "tag:example.com,2017:example-bar"; 771 prefix b; 773 typedef foo { type uint32; } 774 } 776 module example-one { 777 namespace "tag:example.com,2017:example-one"; 778 prefix one; 779 import example-foo { prefix f; } 780 import example-bar { prefix b; } 782 augment "/f:foo" { 783 leaf foo { type b:foo; } 784 } 785 } 787 YANG defines the following rules for prefix usage: 789 o Prefixes are never used for built in data types and YANG keywords. 791 o A prefix MUST be used for any external statement (i.e., a 792 statement defined with the YANG "extension" statement) 794 o The proper module prefix MUST be used for all identifiers imported 795 from other modules 797 o The proper module prefix MUST be used for all identifiers included 798 from a submodule. 800 The following guidelines apply to prefix usage of the current (local) 801 module: 803 o The local module prefix SHOULD be used instead of no prefix in all 804 path expressions. 806 o The local module prefix MUST be used instead of no prefix in all 807 "default" statements for an "identityref" or "instance-identifier" 808 data type 810 o The local module prefix MAY be used for references to typedefs, 811 groupings, extensions, features, and identities defined in the 812 module. 814 Prefix values SHOULD be short, but also likely to be unique. Prefix 815 values SHOULD NOT conflict with known modules that have been 816 previously published. 818 4.3. Identifiers 820 Identifiers for all YANG identifiers in published modules MUST be 821 between 1 and 64 characters in length. These include any construct 822 specified as an 'identifier-arg-str' token in the ABNF in Section 13 823 of [RFC7950]. 825 4.3.1. Identifier Naming Conventions 827 Identifiers SHOULD follow a consistent naming pattern throughout the 828 module. Only lower-case letters, numbers, and dashes SHOULD be used 829 in identifier names. Upper-case characters, the period character, 830 and the underscore character MAY be used if the identifier represents 831 a well-known value that uses these characters. YANG does not permit 832 any other characters in YANG identifiers. 834 Identifiers SHOULD include complete words and/or well-known acronyms 835 or abbreviations. Child nodes within a container or list SHOULD NOT 836 replicate the parent identifier. YANG identifiers are hierarchical 837 and are only meant to be unique within the the set of sibling nodes 838 defined in the same module namespace. 840 It is permissible to use common identifiers such as "name" or "id" in 841 data definition statements, especially if these data nodes share a 842 common data type. 844 Identifiers SHOULD NOT carry any special semantics that identify data 845 modelling properties. Only YANG statements and YANG extension 846 statements are designed to convey machine readable data modelling 847 properties. For example, naming an object "config" or "state" does 848 not change whether it is configuration data or state data. Only 849 defined YANG statements or YANG extension statements can be used to 850 assign semantics in a machine readable format in YANG. 852 4.4. Defaults 854 In general, it is suggested that substatements containing very common 855 default values SHOULD NOT be present. The following substatements 856 are commonly used with the default value, which would make the module 857 difficult to read if used everywhere they are allowed. 859 +--------------+---------------+ 860 | Statement | Default Value | 861 +--------------+---------------+ 862 | config | true | 863 | mandatory | false | 864 | max-elements | unbounded | 865 | min-elements | 0 | 866 | ordered-by | system | 867 | status | current | 868 | yin-element | false | 869 +--------------+---------------+ 871 Statement Defaults 873 4.5. Conditional Statements 875 A module may be conceptually partitioned in several ways, using the 876 'if-feature' and/or 'when' statements. 878 Data model designers need to carefully consider all modularity 879 aspects, including the use of YANG conditional statements. 881 If a data definition is optional, depending on server support for a 882 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 883 statement SHOULD be defined. The defined "feature" statement SHOULD 884 then be used in the conditional "if-feature" statement referencing 885 the optional data definition. 887 If any notification data, or any data definition, for a non- 888 configuration data node is not mandatory, then the server may or may 889 not be required to return an instance of this data node. If any 890 conditional requirements exist for returning the data node in a 891 notification payload or retrieval request, they MUST be documented 892 somewhere. For example, a 'when' or 'if-feature' statement could 893 apply to the data node, or the conditional requirements could be 894 explained in a 'description' statement within the data node or one of 895 its ancestors (if any). 897 If any 'if-feature' statements apply to a list node, then the same 898 'if-feature' statements MUST apply to any key leaf nodes for the 899 list. There MUST NOT be any 'if-feature' statements applied to any 900 key leaf that do not also apply to the parent list node. 902 There SHOULD NOT be any 'when' statements applied to a key leaf node. 903 It is possible that a 'when' statement for an ancestor node of a key 904 leaf will have the exact node-set result as the key leaf. In such a 905 case, the 'when' statement for the key leaf is redundant and SHOULD 906 be avoided. 908 4.6. XPath Usage 910 This section describes guidelines for using the XML Path Language 911 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 913 4.6.1. XPath Evaluation Contexts 915 YANG defines 5 separate contexts for evaluation of XPath statements: 917 1) The "running" datastore: collection of all YANG configuration data 918 nodes. The document root is the conceptual container, (e.g., 919 "config" in the "edit-config" operation), which is the parent of all 920 top-level data definition statements with a "config" statement value 921 of "true". 923 2) State data + the "running" datastore: collection of all YANG data 924 nodes. The document root is the conceptual container, parent of all 925 top-level data definition statements. 927 3) Notification: an event notification document. The document root 928 is the notification element. 930 4) RPC Input: The document root is the conceptual "input" node, which 931 is the parent of all RPC input parameter definitions. 933 5) RPC Output: The document root is the conceptual "output" node, 934 which is the parent of all RPC output parameter definitions. 936 Note that these XPath contexts cannot be mixed. For example, a 937 "when" statement in a notification context cannot reference 938 configuration data. 940 notification foo { 941 leaf mtu { 942 // NOT OK because when-stmt context is this notification 943 when "/if:interfaces/if:interface[name='eth0']"; 944 type leafref { 945 // OK because path-stmt has a different context 946 path "/if:interfaces/if:interface/if:mtu"; 947 } 948 } 949 } 951 It is especially important to consider the XPath evaluation context 952 for XPath expressions defined in groupings. An XPath expression 953 defined in a grouping may not be portable, meaning it cannot be used 954 in multiple contexts and produce proper results. 956 If the XPath expressions defined in a grouping are intended for a 957 particular context, then this context SHOULD be identified in the 958 "description" statement for the grouping. 960 4.6.2. Function Library 962 The 'position' and 'last' functions SHOULD NOT be used. This applies 963 to implicit use of the 'position' function as well (e.g., 964 '//chapter[42]'). A server is only required to maintain the relative 965 XML document order of all instances of a particular user-ordered list 966 or leaf-list. The 'position' and 'last' functions MAY be used if 967 they are evaluated in a context where the context node is a user- 968 ordered 'list' or 'leaf-list'. 970 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 971 present in YANG documents so this function has no meaning. The YANG 972 compiler SHOULD return an empty string for this function. 974 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 975 Expanded names in XPath are different than YANG. A specific 976 canonical representation of a YANG expanded name does not exist. 978 The 'lang' function SHOULD NOT be used. This function does not apply 979 to YANG because there is no 'lang' attribute set with the document. 980 The YANG compiler SHOULD return 'false' for this function. 982 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 983 functions SHOULD NOT be used if the argument is a node-set. If so, 984 the function result will be determined by the document order of the 985 node-set. Since this order can be different on each server, the 986 function results can also be different. Any function call that 987 implicitly converts a node-set to a string will also have this issue. 989 The 'local-name' function SHOULD NOT be used to reference local names 990 outside of the YANG module defining the must or when expression 991 containing the 'local-name' function. Example of a local-name 992 function that should not be used: 994 /*[local-name()='foo'] 996 The 'derived-from-or-self' function SHOULD be used instead of an 997 equality expression for identityref values. This allows the 998 identities to be conceptually augmented. 1000 Example: 1002 // do not use 1003 when "md-name-format = 'name-format-null'"; 1005 // this is preferred 1006 when "derived-from-or-self(md-name-format, 'name-format-null')"; 1008 4.6.3. Axes 1010 The 'attribute' and 'namespace' axes are not supported in YANG, and 1011 MAY be empty in a NETCONF or RESTCONF server implementation. 1013 The 'preceding', and 'following' axes SHOULD NOT be used. These 1014 constructs rely on XML document order within a NETCONF or RESTCONF 1015 server configuration database, which may not be supported 1016 consistently or produce reliable results across implementations. 1017 Predicate expressions based on static node properties (e.g., element 1018 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 1019 instead. The 'preceding' and 'following' axes MAY be used if 1020 document order is not relevant to the outcome of the expression 1021 (e.g., check for global uniqueness of a parameter value). 1023 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 1024 however they MAY be used if document order is not relevant to the 1025 outcome of the expression. 1027 A server is only required to maintain the relative XML document order 1028 of all instances of a particular user-ordered list or leaf-list. The 1029 'preceding-sibling' and 'following-sibling' axes MAY be used if they 1030 are evaluated in a context where the context node is a user-ordered 1031 'list' or 'leaf-list'. 1033 4.6.4. Types 1035 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 1036 be used within numeric or boolean expressions. There are boundary 1037 conditions in which the translation from the YANG 64-bit type to an 1038 XPath number can cause incorrect results. Specifically, an XPath 1039 'double' precision floating point number cannot represent very large 1040 positive or negative 64-bit numbers because it only provides a total 1041 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 1042 used in numeric expressions if the value can be represented with no 1043 more than 53 bits of precision. 1045 Data modelers need to be careful not to confuse the YANG value space 1046 and the XPath value space. The data types are not the same in both, 1047 and conversion between YANG and XPath data types SHOULD be considered 1048 carefully. 1050 Explicit XPath data type conversions MAY be used (e.g., 'string', 1051 'boolean', or 'number' functions), instead of implicit XPath data 1052 type conversions. 1054 XPath expressions that contain a literal value representing a YANG 1055 identity SHOULD always include the declared prefix of the module 1056 where the identity is defined. 1058 XPath expressions for 'when' statements SHOULD NOT reference the 1059 context node or any descendant nodes of the context node. They MAY 1060 reference descendant nodes if the 'when' statement is contained 1061 within an 'augment' statement, and the referenced nodes are not 1062 defined within the 'augment' statement. 1064 Example: 1066 augment "/rt:active-route/rt:input/rt:destination-address" { 1067 when "rt:address-family='v4ur:ipv4-unicast'" { 1068 description 1069 "This augment is valid only for IPv4 unicast."; 1070 } 1071 // nodes defined here within the augment-stmt 1072 // cannot be referenced in the when-stmt 1073 } 1075 4.6.5. Wildcards 1077 It is possible to construct XPath expressions that will evaluate 1078 differently when combined with several modules within a server 1079 implementation, then when evaluated within the single module. This 1080 is due to augmenting nodes from other modules. 1082 Wildcard expansion is done within a server against all the nodes from 1083 all namespaces, so it is possible for a 'must' or 'when' expression 1084 that uses the '*' operator will always evaluate to false if processed 1085 within a single YANG module. In such cases, the 'description' 1086 statement SHOULD clarify that augmenting objects are expected to 1087 match the wildcard expansion. 1089 when /foo/services/*/active { 1090 description 1091 "No services directly defined in this module. 1092 Matches objects that have augmented the services container."; 1093 } 1095 4.6.6. Boolean Expressions 1097 The YANG "must" and "when" statements use an XPath boolean expression 1098 to define the test condition for the statement. It is important to 1099 specify these expressions in a way that will not cause inadvertent 1100 changes in the result if the objects referenced in the expression are 1101 updated in future revisions of the module. 1103 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 1104 to "one" or "three": 1106 leaf foo1 { 1107 type enumeration { 1108 enum one; 1109 enum two; 1110 enum three; 1111 } 1112 } 1114 leaf foo2 { 1115 // INCORRECT 1116 must "/f:foo1 != 'two'"; 1117 type string; 1118 } 1120 leaf foo2 { 1121 // CORRECT 1122 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 1123 type string; 1124 } 1126 In the next revision of the module, leaf "foo1" is extended with a 1127 new enum named "four": 1129 leaf foo1 { 1130 type enumeration { 1131 enum one; 1132 enum two; 1133 enum three; 1134 enum four; 1135 } 1136 } 1138 Now the first XPath expression will allow the enum "four" to be 1139 accepted in addition to the "one" and "three" enum values. 1141 4.7. YANG Definition Lifecycle Management 1143 The YANG status statement MUST be present within a definition if its 1144 value is 'deprecated' or 'obsolete'. The status SHOULD NOT be 1145 changed from 'current' directly to 'obsolete'. An object SHOULD be 1146 available for at least one year with 'deprecated' status before it is 1147 changed to 'obsolete'. 1149 The module or submodule name MUST NOT be changed, once the document 1150 containing the module or submodule is published. 1152 The module namespace URI value MUST NOT be changed, once the document 1153 containing the module is published. 1155 The revision-date substatement within the import statement SHOULD be 1156 present if any groupings are used from the external module. 1158 The revision-date substatement within the include statement SHOULD be 1159 present if any groupings are used from the external submodule. 1161 If an import statement is for a module from a stable source (e.g., an 1162 RFC for an IETF module), then a reference-stmt SHOULD be present 1163 within an import statement. 1165 import ietf-yang-types { 1166 prefix yang; 1167 reference "RFC 6991"; 1168 } 1170 If submodules are used, then the document containing the main module 1171 MUST be updated so that the main module revision date is equal or 1172 more recent than the revision date of any submodule that is (directly 1173 or indirectly) included by the main module. 1175 Definitions for future use SHOULD NOT be specified in a module. Do 1176 not specify placeholder objects like the "reserved" example below: 1178 leaf reserved { 1179 type string; 1180 description 1181 "This object has no purpose at this time, but a future 1182 revision of this module might define a purpose 1183 for this object."; 1184 } 1185 } 1187 4.8. Module Header, Meta, and Revision Statements 1189 For published modules, the namespace MUST be a globally unique URI, 1190 as defined in [RFC3986]. This value is usually assigned by the IANA. 1192 The organization statement MUST be present. If the module is 1193 contained in a document intended for IETF Standards Track status, 1194 then the organization SHOULD be the IETF working group chartered to 1195 write the document. For other standards organizations, a similar 1196 approach is also suggested. 1198 The contact statement MUST be present. If the module is contained in 1199 a document intended for Standards Track status, then the working 1200 group web and mailing information SHOULD be present, and the main 1201 document author or editor contact information SHOULD be present. If 1202 additional authors or editors exist, their contact information MAY be 1203 present. There is no need to include the contact information for 1204 Working Group chairs. 1206 The description statement MUST be present. For modules published 1207 within IETF documents, the appropriate IETF Trust Copyright text MUST 1208 be present, as described in Section 3.1. 1210 If the module relies on information contained in other documents, 1211 which are not the same documents implied by the import statements 1212 present in the module, then these documents MUST be identified in the 1213 reference statement. 1215 A revision statement MUST be present for each published version of 1216 the module. The revision statement MUST have a reference 1217 substatement. It MUST identify the published document that contains 1218 the module. Modules are often extracted from their original 1219 documents, and it is useful for developers and operators to know how 1220 to find the original source document in a consistent manner. The 1221 revision statement MAY have a description substatement. 1223 The following example shows the revision statement for a published 1224 YANG module: 1226 revision "2012-02-22" { 1227 description 1228 "Initial version"; 1229 reference 1230 "RFC 6536: Network Configuration Protocol (NETCONF) 1231 Access Control Model"; 1232 } 1234 For an unpublished module, a complete history of each unpublished 1235 module revision is not required. That is, within a sequence of draft 1236 versions, only the most recent revision need be recorded in the 1237 module. Do not remove or reuse a revision statement for a published 1238 module. A new revision date is not required unless the module 1239 contents have changed. If the module contents have changed, then the 1240 revision date of that new module version MUST be updated to a date 1241 later than that of the previous version. 1243 The following example shows the two revision statements for an 1244 unpublished update to a published YANG module: 1246 revision "2017-12-11" { 1247 description 1248 "Added support for YANG 1.1 actions and notifications tied to 1249 data nodes. Clarify how NACM extensions can be used by other 1250 data models."; 1251 reference 1252 "RFC XXXX: Network Configuration Protocol (NETCONF) 1253 Access Control Model"; 1254 } 1256 revision "2012-02-22" { 1257 description 1258 "Initial version"; 1259 reference 1260 "RFC 6536: Network Configuration Protocol (NETCONF) 1261 Access Control Model"; 1262 } 1264 4.9. Namespace Assignments 1266 It is RECOMMENDED that only valid YANG modules be included in 1267 documents, whether or not the modules are published yet. This 1268 allows: 1270 o the module to compile correctly instead of generating disruptive 1271 fatal errors. 1273 o early implementors to use the modules without picking a random 1274 value for the XML namespace. 1276 o early interoperability testing since independent implementations 1277 will use the same XML namespace value. 1279 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1280 provided for the namespace statement in a YANG module. A value 1281 SHOULD be selected that is not likely to collide with other YANG 1282 namespaces. Standard module names, prefixes, and URI strings already 1283 listed in the YANG Module Registry MUST NOT be used. 1285 A standard namespace statement value SHOULD have the following form: 1287 : 1289 The following URN prefix string SHOULD be used for published and 1290 unpublished YANG modules: 1292 urn:ietf:params:xml:ns:yang: 1294 The following example URNs would be valid namespace statement values 1295 for Standards Track modules: 1297 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1299 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1301 urn:ietf:params:xml:ns:yang:ietf-netconf 1303 Note that a different URN prefix string SHOULD be used for non- 1304 Standards-Track modules. The string SHOULD be selected according to 1305 the guidelines in [RFC7950]. 1307 The following URIs exemplify what might be used by non Standards 1308 Track modules. Note that the domain "example.com" SHOULD be used by 1309 example modules in IETF drafts. These URIs are not intended to be 1310 de-referenced. They are used for module namespace identification 1311 only. 1313 Example URIs using URLs per RFC 3986 [RFC3986]: 1315 https://example.com/ns/example-interfaces 1317 https://example.com/ns/example-system 1319 Example URIs using tags per RFC 4151 [RFC4151]: 1321 tag:example.com,2017:example-interfaces 1323 tag:example.com,2017:example-system 1325 4.10. Top-Level Data Definitions 1327 The top-level data organization SHOULD be considered carefully, in 1328 advance. Data model designers need to consider how the functionality 1329 for a given protocol or protocol family will grow over time. 1331 The separation of configuration data and operational state SHOULD be 1332 considered carefully. It is sometimes useful to define separate top- 1333 level containers for configuration and non-configuration data. For 1334 some existing top-level data nodes, configuration data was not in 1335 scope, so only one container representing operational state was 1336 created. Refer to the Network Management Datastore Architecture 1337 (NMDA) [I-D.ietf-netmod-revised-datastores]. for details. 1339 The number of top-level data nodes within a module SHOULD be 1340 minimized. It is often useful to retrieve related information within 1341 a single subtree. If data is too distributed, is becomes difficult 1342 to retrieve all at once. 1344 The names and data organization SHOULD reflect persistent 1345 information, such as the name of a protocol. The name of the working 1346 group SHOULD NOT be used because this may change over time. 1348 A mandatory database data definition is defined as a node that a 1349 client must provide for the database to be valid. The server is not 1350 required to provide a value. 1352 Top-level database data definitions MUST NOT be mandatory. If a 1353 mandatory node appears at the top level, it will immediately cause 1354 the database to be invalid. This can occur when the server boots or 1355 when a module is loaded dynamically at runtime. 1357 4.11. Data Types 1359 Selection of an appropriate data type (i.e., built-in type, existing 1360 derived type, or new derived type) is very subjective, and therefore 1361 few requirements can be specified on that subject. 1363 Data model designers SHOULD use the most appropriate built-in data 1364 type for the particular application. 1366 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1367 'int64') SHOULD NOT be used unless negative values are allowed for 1368 the desired semantics. 1370 4.11.1. Fixed Value Extensibility 1372 If the set of values is fixed and the data type contents are 1373 controlled by a single naming authority, then an enumeration data 1374 type SHOULD be used. 1376 leaf foo { 1377 type enumeration { 1378 enum one; 1379 enum two; 1380 } 1381 } 1383 If extensibility of enumerated values is required, then the 1384 'identityref' data type SHOULD be used instead of an enumeration or 1385 other built-in type. 1387 identity foo-type { 1388 description "Base for the extensible type"; 1389 } 1391 identity one { 1392 base f:foo-type; 1393 } 1394 identity two { 1395 base f:foo-type; 1396 } 1398 leaf foo { 1399 type identityref { 1400 base f:foo-type; 1401 } 1402 } 1404 Note that any module can declare an identity with base "foo-type" 1405 that is valid for the "foo" leaf. Identityref values are considered 1406 to be qualified names. 1408 4.11.2. Patterns and Ranges 1410 For string data types, if a machine-readable pattern can be defined 1411 for the desired semantics, then one or more pattern statements SHOULD 1412 be present. A single quoted string SHOULD be used to specify the 1413 pattern, since a double-quoted string can modify the content. If the 1414 patterns used in a type definition have known limitations such as 1415 false negative or false positive matches, then these limitations 1416 SHOULD be documented within the typedef or data definition. 1418 The following typedef from [RFC6991] demonstrates the proper use of 1419 the "pattern" statement: 1421 typedef ipv4-address-no-zone { 1422 type inet:ipv4-address { 1423 pattern '[0-9\.]*'; 1424 } 1425 ... 1426 } 1428 For string data types, if the length of the string is required to be 1429 bounded in all implementations, then a length statement MUST be 1430 present. 1432 The following typedef from [RFC6991] demonstrates the proper use of 1433 the "length" statement: 1435 typedef yang-identifier { 1436 type string { 1437 length "1..max"; 1438 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1439 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1440 } 1441 ... 1442 } 1444 For numeric data types, if the values allowed by the intended 1445 semantics are different than those allowed by the unbounded intrinsic 1446 data type (e.g., 'int32'), then a range statement SHOULD be present. 1448 The following typedef from [RFC6991] demonstrates the proper use of 1449 the "range" statement: 1451 typedef dscp { 1452 type uint8 { 1453 range "0..63"; 1454 } 1455 ... 1456 } 1458 4.11.3. Enumerations and Bits 1460 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1461 or 'bit' SHOULD be documented. A separate description statement 1462 (within each 'enum' or 'bit' statement) SHOULD be present. 1464 leaf foo { 1465 // INCORRECT 1466 type enumeration { 1467 enum one; 1468 enum two; 1469 } 1470 description 1471 "The foo enum... 1472 one: The first enum 1473 two: The second enum"; 1474 } 1476 leaf foo { 1477 // CORRECT 1478 type enumeration { 1479 enum one { 1480 description "The first enum"; 1481 } 1482 enum two { 1483 description "The second enum"; 1484 } 1485 } 1486 description 1487 "The foo enum... "; 1488 } 1490 4.11.4. Union Types 1492 The YANG "union" type is evaluated by testing a value against each 1493 member type in the union. The first type definition that accepts a 1494 value as valid is the member type used. In general, member types 1495 SHOULD be ordered from most restrictive to least restrictive types. 1497 In the following example, the "enumeration" type will never be 1498 matched because the preceding "string" type will match everything. 1500 Incorrect: 1502 type union { 1503 type string; 1504 type enumeration { 1505 enum up; 1506 enum down; 1507 } 1508 } 1510 Correct: 1512 type union { 1513 type enumeration { 1514 enum up; 1515 enum down; 1516 } 1517 type string; 1518 } 1520 It is possible for different member types to match, depending on the 1521 input encoding format. In XML, all values are passed as string 1522 nodes, but in JSON there are different value types for numbers, 1523 booleans, and strings. 1525 In the following example, a JSON numeric value will always be matched 1526 by the "int32" type but in XML the string value representing a number 1527 will be matched by the "string" type. The second version will match 1528 the "int32" member type no matter how the input is encoded. 1530 Incorrect: 1532 type union { 1533 type string; 1534 type int32; 1535 } 1537 Correct: 1539 type union { 1540 type int32; 1541 type string; 1542 } 1544 4.11.5. Empty and Boolean 1546 YANG provides an "empty" data type, which has one value (i.e., 1547 present). The default is "not present", which is not actually a 1548 value. When used within a list key, only one value can (and must) 1549 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1550 key leaf since it is pointless. 1552 There is really no difference between a leaf of type "empty" and a 1553 leaf-list of type "empty". Both are limited to one instance. The 1554 type "empty" SHOULD NOT be used for a leaf-list. 1556 The advantage of using type "empty" instead of type "boolean" is that 1557 the default (not present) does not take up any bytes in a 1558 representation. The disadvantage is that the client may not be sure 1559 if an empty leaf is missing because it was filtered somehow or not 1560 implemented. The client may not have a complete and accurate schema 1561 for the data returned by the server, and not be aware of the missing 1562 leaf. 1564 The YANG "boolean" data type provides two values ("true" and 1565 "false"). When used within a list key, two entries can exist for 1566 this key leaf. Default values are ignored for key leafs, but a 1567 default statement is often used for plain boolean leafs. The 1568 advantage of the "boolean" type is that the leaf or leaf-list has a 1569 clear representation for both values. The default value is usually 1570 not returned unless explicitly requested by the client, so no bytes 1571 are used in a typical representation. 1573 In general, the "boolean" data type SHOULD be used instead of the 1574 "empty" data type, as shown in the example below: 1576 Incorrect: 1578 leaf flag1 { 1579 type empty; 1580 } 1582 Correct: 1584 leaf flag2 { 1585 type boolean; 1586 default false; 1587 } 1589 4.12. Reusable Type Definitions 1591 If an appropriate derived type exists in any standard module, such as 1592 [RFC6991], then it SHOULD be used instead of defining a new derived 1593 type. 1595 If an appropriate units identifier can be associated with the desired 1596 semantics, then a units statement SHOULD be present. 1598 If an appropriate default value can be associated with the desired 1599 semantics, then a default statement SHOULD be present. 1601 If a significant number of derived types are defined, and it is 1602 anticipated that these data types will be reused by multiple modules, 1603 then these derived types SHOULD be contained in a separate module or 1604 submodule, to allow easier reuse without unnecessary coupling. 1606 The description statement MUST be present. 1608 If the type definition semantics are defined in an external document 1609 (other than another YANG module indicated by an import statement), 1610 then the reference statement MUST be present. 1612 4.13. Reusable Groupings 1614 A reusable grouping is a YANG grouping that can be imported by 1615 another module, and is intended for use by other modules. This is 1616 not the same as a grouping that is used within the module it is 1617 defined, but happens to be exportable to another module because it is 1618 defined at the top-level of the YANG module. 1620 The following guidelines apply to reusable groupings, in order to 1621 make them as robust as possible: 1623 o Clearly identify the purpose of the grouping in the "description" 1624 statement. 1626 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1627 output, notification, config=true data nodes, and all data nodes). 1628 Clearly identify which XPath contexts are applicable or excluded 1629 for the grouping. 1631 o Do not reference data outside the grouping in any "path", "must", 1632 or "when" statements. 1634 o Do not include a "default" sub-statement on a leaf or choice 1635 unless the value applies on all possible contexts. 1637 o Do not include a "config" sub-statement on a data node unless the 1638 value applies on all possible contexts. 1640 o Clearly identify any external dependencies in the grouping 1641 "description" statement, such as nodes referenced by absolute path 1642 from a "path", "must", or "when" statement. 1644 4.14. Data Definitions 1646 The description statement MUST be present in the following YANG 1647 statements: 1649 o anyxml 1651 o augment 1653 o choice 1654 o container 1656 o extension 1658 o feature 1660 o grouping 1662 o identity 1664 o leaf 1666 o leaf-list 1668 o list 1670 o notification 1672 o rpc 1674 o typedef 1676 If the data definition semantics are defined in an external document, 1677 (other than another YANG module indicated by an import statement), 1678 then a reference statement MUST be present. 1680 The 'anyxml' construct may be useful to represent an HTML banner 1681 containing markup elements, such as '<b>' and '</b>', and 1682 MAY be used in such cases. However, this construct SHOULD NOT be 1683 used if other YANG data node types can be used instead to represent 1684 the desired syntax and semantics. 1686 It has been found that the 'anyxml' statement is not implemented 1687 consistently across all servers. It is possible that mixed mode XML 1688 will not be supported, or configuration anyxml nodes will not 1689 supported. 1691 If there are referential integrity constraints associated with the 1692 desired semantics that can be represented with XPath, then one or 1693 more 'must' statements SHOULD be present. 1695 For list and leaf-list data definitions, if the number of possible 1696 instances is required to be bounded for all implementations, then the 1697 max-elements statements SHOULD be present. 1699 If any 'must' or 'when' statements are used within the data 1700 definition, then the data definition description statement SHOULD 1701 describe the purpose of each one. 1703 The "choice" statement is allowed to be directly present within a 1704 "case" statement in YANG 1.1. This needs to be considered carefully. 1705 Consider simply including the nested "choice" as additional "case" 1706 statements within the parent "choice" statement. Note that the 1707 "mandatory" and "default" statements within a nested "choice" 1708 statement only apply if the "case" containing the nested "choice" 1709 statement is first selected. 1711 If a list defines any key leafs, then these leafs SHOULD be defined 1712 in order, as the first child nodes within the list. The key leafs 1713 MAY be in a different order in some cases, e.g., they are defined in 1714 a grouping, not inline in the list statement. 1716 4.14.1. Non-Presence Containers 1718 A non-presence container is used to organize data into specific 1719 subtrees. It is not intended to have semantics within the data model 1720 beyond this purpose, although YANG allows it (e.g., "must" statement 1721 within the non-presence container). 1723 Example using container wrappers: 1725 container top { 1726 container foos { 1727 list foo { ... } 1728 } 1729 container bars { 1730 list bar { ... } 1731 } 1732 } 1734 Example without container wrappers: 1736 container top { 1737 list foo { ... } 1738 list bar { ... } 1739 } 1741 Use of non-presence containers to organize data is a subjective 1742 matter similar to use of sub-directories in a file system. Although 1743 these containers do not have any semantics, they can impact protocol 1744 operations for the descendant data nodes within a non-presence 1745 container, so use of these containers SHOULD be considered carefully. 1747 The NETCONF and RESTCONF protocols do not currently support the 1748 ability to delete all list (or leaf-list) entries at once. This 1749 deficiency is sometimes avoided by use of a parent container (i.e., 1750 deleting the container also removes all child entries). 1752 4.14.2. Top-Level Data Nodes 1754 Use of top-level objects needs to be considered carefully: 1756 o top-level siblings are not ordered 1758 o top-level siblings not are not static, and depends on the modules 1759 that are loaded 1761 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1762 treated as a content-match node for all top-level-siblings 1764 o a top-level list with many instances may impact performance 1766 4.15. Operation Definitions 1768 If the operation semantics are defined in an external document (other 1769 than another YANG module indicated by an import statement), then a 1770 reference statement MUST be present. 1772 If the operation impacts system behavior in some way, it SHOULD be 1773 mentioned in the description statement. 1775 If the operation is potentially harmful to system behavior in some 1776 way, it MUST be mentioned in the Security Considerations section of 1777 the document. 1779 4.16. Notification Definitions 1781 The description statement MUST be present. 1783 If the notification semantics are defined in an external document 1784 (other than another YANG module indicated by an import statement), 1785 then a reference statement MUST be present. 1787 If the notification refers to a specific resource instance, then this 1788 instance SHOULD be identified in the notification data. This is 1789 usually done by including 'leafref' leaf nodes with the key leaf 1790 values for the resource instance. For example: 1792 notification interface-up { 1793 description "Sent when an interface is activated."; 1794 leaf name { 1795 type leafref { 1796 path "/if:interfaces/if:interface/if:name"; 1797 } 1798 } 1799 } 1801 Note that there are no formal YANG statements to identify any data 1802 node resources associated with a notification. The description 1803 statement for the notification SHOULD specify if and how the 1804 notification identifies any data node resources associated with the 1805 specific event. 1807 4.17. Feature Definitions 1809 The YANG "feature" statement is used to define a label for a set of 1810 optional functionality within a module. The "if-feature" statement 1811 is used in the YANG statements associated with a feature. The 1812 description-stmt within a feature-stmt MUST specify any interactions 1813 with other features. 1815 The set of YANG features defined in a module should be considered 1816 carefully. Very fine granular features increase interoperability 1817 complexity and should be avoided. A likely misuse of the feature 1818 mechanism is the tagging of individual leafs (e.g., counters) with 1819 separate features. 1821 If there is a large set of objects associated with a YANG feature, 1822 then consider moving those objects to a separate module, instead of 1823 using a YANG feature. Note that the set of features within a module 1824 is easily discovered by the reader, but the set of related modules 1825 within the entire YANG library is not as easy to identity. Module 1826 names with a common prefix can help readers identity the set of 1827 related modules, but this assumes the reader will have discovered and 1828 installed all the relevant modules. 1830 Another consideration for deciding whether to create a new module or 1831 add a YANG feature is the stability of the module in question. It 1832 may be desirable to have a stable base module that is not changed 1833 frequently. If new functionality is placed in a separate module, 1834 then the base module does not need to be republished. If it is 1835 designed as a YANG feature then the module will need to be 1836 republished. 1838 If one feature requires implementation of another feature, then an 1839 "if-feature" statement SHOULD be used in the dependent "feature" 1840 statement. 1842 For example, feature2 requires implementation of feature1: 1844 feature feature1 { 1845 description "Some protocol feature"; 1846 } 1848 feature feature2 { 1849 if-feature "feature1"; 1850 description "Another protocol feature"; 1851 } 1853 4.18. YANG Data Node Constraints 1855 4.18.1. Controlling Quantity 1857 The "min-elements" and "max-elements" statements can be use to 1858 control how many list or leaf-list instances are required for a 1859 particular data node. YANG constraint statements SHOULD be used to 1860 identify conditions that apply to all implementations of the data 1861 model. If platform-specific limitations (e.g., the "max-elements" 1862 supported for a particular list) are relevant to operations, then a 1863 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1864 used to identify the limit. 1866 4.18.2. must vs. when 1868 The "must" and "when" YANG statements are used to provide cross- 1869 object referential tests. They have very different behavior. The 1870 "when" statement causes data node instances to be silently deleted as 1871 soon as the condition becomes false. A false "when" expression is 1872 not considered to be an error. 1874 The "when" statement SHOULD be used together with the "augment" or 1875 "uses" statements to achieve conditional model composition. The 1876 condition SHOULD be based on static properties of the augmented entry 1877 (e.g., list key leafs). 1879 The "must" statement causes a datastore validation error if the 1880 condition is false. This statement SHOULD be used for enforcing 1881 parameter value restrictions that involve more than one data node 1882 (e.g., end-time parameter must be after the start-time parameter). 1884 4.19. Augment Statements 1886 The YANG "augment" statement is used to define a set of data 1887 definition statements that will be added as child nodes of a target 1888 data node. The module namespace for these data nodes will be the 1889 augmenting module, not the augmented module. 1891 A top-level "augment" statement SHOULD NOT be used if the target data 1892 node is in the same module or submodule as the evaluated "augment" 1893 statement. The data definition statements SHOULD be added inline 1894 instead. 1896 4.19.1. Conditional Augment Statements 1898 The "augment" statement is often used together with the "when" 1899 statement and/or "if-feature" statement to make the augmentation 1900 conditional on some portion of the data model. 1902 The following example from [RFC7223] shows how a conditional 1903 container called "ethernet" is added to the "interface" list only for 1904 entries of the type "ethernetCsmacd". 1906 augment "/if:interfaces/if:interface" { 1907 when "if:type = 'ianaift:ethernetCsmacd'"; 1909 container ethernet { 1910 leaf duplex { 1911 ... 1912 } 1913 } 1914 } 1916 4.19.2. Conditionally Mandatory Data Definition Statements 1918 YANG has very specific rules about how configuration data can be 1919 updated in new releases of a module. These rules allow an "old 1920 client" to continue interoperating with a "new server". 1922 If data nodes are added to an existing entry, the old client MUST NOT 1923 be required to provide any mandatory parameters that were not in the 1924 original module definition. 1926 It is possible to add conditional augment statements such that the 1927 old client would not know about the new condition, and would not 1928 specify the new condition. The conditional augment statement can 1929 contain mandatory objects only if the condition is false unless 1930 explicitly requested by the client. 1932 Only a conditional augment statement that uses the "when" statement 1933 form of condition can be used in this manner. The YANG features 1934 enabled on the server cannot be controlled by the client in any way, 1935 so it is not safe to add mandatory augmenting data nodes based on the 1936 "if-feature" statement. 1938 The XPath "when" statement condition MUST NOT reference data outside 1939 of target data node because the client does not have any control over 1940 this external data. 1942 In the following dummy example, it is OK to augment the "interface" 1943 entry with "mandatory-leaf" because the augmentation depends on 1944 support for "some-new-iftype". The old client does not know about 1945 this type so it would never select this type, and therefore not be 1946 adding a mandatory data node. 1948 module example-module { 1949 namespace "tag:example.com,2017:example-module"; 1950 prefix mymod; 1952 import iana-if-type { prefix iana; } 1953 import ietf-interfaces { prefix if; } 1955 identity some-new-iftype { 1956 base iana:iana-interface-type; 1957 } 1959 augment "/if:interfaces/if:interface" { 1960 when "if:type = 'mymod:some-new-iftype'"; 1962 leaf mandatory-leaf { 1963 mandatory true; 1964 ... 1965 } 1966 } 1967 } 1969 Note that this practice is safe only for creating data resources. It 1970 is not safe for replacing or modifying resources if the client does 1971 not know about the new condition. The YANG data model MUST be 1972 packaged in a way that requires the client to be aware of the 1973 mandatory data nodes if it is aware of the condition for this data. 1974 In the example above, the "some-new-iftype" identity is defined in 1975 the same module as the "mandatory-leaf" data definition statement. 1977 This practice is not safe for identities defined in a common module 1978 such as "iana-if-type" because the client is not required to know 1979 about "my-module" just because it knows about the "iana-if-type" 1980 module. 1982 4.20. Deviation Statements 1984 Per RFC 7950, 7.20.3, the YANG "deviation" statement is not allowed 1985 to appear in IETF YANG modules, but it can be useful for documenting 1986 server capabilities. Deviation statements are not reusable and 1987 typically not shared across all platforms. 1989 There are several reasons that deviations might be needed in an 1990 implementation, e.g., an object cannot be supported on all platforms, 1991 or feature delivery is done in multiple development phases. 1992 Deviation statements can also be used to add annotations to a module, 1993 which does not affect the conformance requirements for the module. 1995 It is suggested that deviation statements be defined in separate 1996 modules from regular YANG definitions. This allows the deviations to 1997 be platform-specific and/or temporary. 1999 The order that deviation statements are evaluated can affect the 2000 result. Therefore multiple deviation statements in the same module, 2001 for the same target object, SHOULD NOT be used. 2003 The "max-elements" statement is intended to describe an architectural 2004 limit to the number of list entries. It is not intended to describe 2005 platform limitations. It is better to use a "deviation" statement 2006 for the platforms that have a hard resource limit. 2008 Example documenting platform resource limits: 2010 Wrong: (max-elements in the list itself) 2012 container backups { 2013 list backup { 2014 ... 2015 max-elements 10; 2016 ... 2017 } 2018 } 2020 Correct: (max-elements in a deviation) 2022 deviation /bk:backups/bk:backup { 2023 deviate add { 2024 max-elements 10; 2025 } 2026 } 2028 4.21. Extension Statements 2030 The YANG "extension" statement is used to specify external 2031 definitions. This appears in the YANG syntax as an 2032 "unknown-statement". Usage of extension statements in a published 2033 module needs to be considered carefully. 2035 The following guidelines apply to the usage of YANG extensions: 2037 o The semantics of the extension MUST NOT contradict any YANG 2038 statements. Extensions can add semantics not covered by the 2039 normal YANG statements. 2041 o The module containing the extension statement MUST clearly 2042 identify the conformance requirements for the extension. It 2043 should be clear whether all implementations of the YANG module 2044 containing the extension need to also implement the extension. If 2045 not, identify what conditions apply that would require 2046 implementation of the extension. 2048 o The extension MUST clearly identify where it can be used within 2049 other YANG statements. 2051 o The extension MUST clearly identify if YANG statements or other 2052 extensions are allowed or required within the extension as sub- 2053 statements. 2055 4.22. Data Correlation 2057 Data can be correlated in various ways, using common data types, 2058 common data naming, and common data organization. There are several 2059 ways to extend the functionality of a module, based on the degree of 2060 coupling between the old and new functionality: 2062 o inline: update the module with new protocol-accessible objects. 2063 The naming and data organization of the original objects is used. 2064 The new objects are in the original module namespace. 2066 o augment: create a new module with new protocol-accessible objects 2067 that augment the original data structure. The naming and data 2068 organization of the original objects is used. The new objects are 2069 in the new module namespace. 2071 o mirror: create new objects in a new module or the original module, 2072 except use new a naming scheme and data location. The naming can 2073 be coupled in different ways. Tight coupling is achieved with a 2074 "leafref" data type, with the "require-instance" sub-statement set 2075 to "true". This method SHOULD be used. 2077 If the new data instances are not limited to the values in use in the 2078 original data structure, then the "require-instance" sub-statement 2079 MUST be set to "false". Loose coupling is achieved by using key 2080 leafs with the same data type as the original data structure. This 2081 has the same semantics as setting the "require-instance" sub- 2082 statement to "false". 2084 The relationship between configuration and operational state has been 2085 clarified in NMDA [I-D.ietf-netmod-revised-datastores]. 2087 4.22.1. Use of Leafref for Key Correlation 2089 Sometimes it is not practical to augment a data structure. For 2090 example, the correlated data could have different keys or contain 2091 mandatory nodes. 2093 The following example shows the use of the "leafref" data type for 2094 data correlation purposes: 2096 Not preferred: 2098 list foo { 2099 key name; 2100 leaf name { 2101 type string; 2102 } 2103 ... 2104 } 2106 list foo-addon { 2107 key name; 2108 config false; 2109 leaf name { 2110 type string; 2111 } 2112 ... 2113 } 2115 Preferred: 2117 list foo { 2118 key name; 2119 leaf name { 2120 type string; 2121 } 2122 ... 2123 } 2125 list foo-addon { 2126 key name; 2127 config false; 2128 leaf name { 2129 type leafref { 2130 path "/foo/name"; 2131 require-instance false; 2132 } 2133 } 2134 leaf addon { 2135 type string; 2136 mandatory true; 2137 } 2138 } 2140 4.23. Operational State 2142 The modeling of operational state with YANG has been refined over 2143 time. At first, only data that has a "config" statement value of 2144 "false" was considered to be operational state. This data was not 2145 considered to be part of any datastore, which made YANG XPath 2146 definition much more complicated. 2148 Operational state is now modeled using YANG according to the new NMDA 2149 [I-D.ietf-netmod-revised-datastores], and is now conceptually 2150 contained in the operational state datastore, which also includes the 2151 operational values of configuration data. There is no longer any 2152 need to duplicate data structures to provide separate configuration 2153 and operational state sections. 2155 This section describes some data modeling issues related to 2156 operational state, and guidelines for transitioning YANG data model 2157 design to be NMDA-compatible. 2159 4.23.1. Combining Operational State and Configuration Data 2161 If possible, operational state SHOULD be combined with its associated 2162 configuration data. This prevents duplication of key leafs and 2163 ancestor nodes. It also prevents race conditions for retrieval of 2164 dynamic entries, and allows configuration and operational state to be 2165 retrieved together with minimal message overhead. 2167 container foo { 2168 ... 2169 // contains config=true and config=false nodes that have 2170 // no corresponding config=true object (e.g., counters) 2171 } 2173 4.23.2. Representing Operational Values of Configuration Data 2175 If possible the same data type SHOULD be used to represent the 2176 configured value and the operational value, for a given leaf or leaf- 2177 list object. 2179 Sometimes the configured value set is different than the operational 2180 value set for that object. For example, the "admin-state" and 2181 "oper-state" leafs in [RFC7223]. In this case a separate object MAY 2182 be used to represent the configured and operational values. 2184 Sometimes the list keys are not identical for configuration data and 2185 the corresponding operational state. In this case separate lists MAY 2186 be used to represent the configured and operational values. 2188 If it is not possible to combine configuration and operational state, 2189 then the keys used to represent list entries SHOULD be the same type. 2190 The "leafref" data type SHOULD be used in operational state for key 2191 leafs that have corresponding configuration instances. The 2192 "require-instance" statement MAY be set to "false" (in YANG 1.1 2193 modules only) to indicate instances are allowed in the operational 2194 state that do not exist in the associated configuration data. 2196 The need to replicate objects or define different operational state 2197 objects depends on the data model. It is not possible to define one 2198 approach that will be optimal for all data models. 2200 Designers SHOULD describe and justify any NMDA exceptions in detail, 2201 such as the use of separate subtrees and/or separate leafs. The 2202 "description" statements for both the configuration and the 2203 operational state SHOULD be used for this purpose. 2205 4.23.3. NMDA Transition Guidelines 2207 YANG modules SHOULD be designed assuming they will be used on servers 2208 supporting the operational state datastore. With this in mind, YANG 2209 modules SHOULD define config "false" wherever they make sense to the 2210 data model. Config "false" nodes SHOULD NOT be defined to provide 2211 the operational value for configuration nodes, except when the value 2212 space of a configured and operational values may differ, in which 2213 case a distinct config "false" node SHOULD be defined to hold the 2214 operational value for the configured node. 2216 The following guidelines are meant to help modelers develop YANG 2217 modules that will maximize the utility of the model with both current 2218 and new implementations. 2220 New modules and modules that are not concerned with the operational 2221 state of configuration information SHOULD immediately be structured 2222 to be NMDA-compatible, as described in Section 4.23.1. This 2223 transition MAY be deferred if the module does not contain any 2224 configuration datastore objects. 2226 The remaining are options that MAY be followed during the time that 2227 NMDA mechanisms are being defined. 2229 (a) Modules that require immediate support for the NMDA features 2230 SHOULD be structured for NMDA. A temporary non-NMDA version of this 2231 type of module MAY exist, either an existing model or a model created 2232 either by hand or with suitable tools that mirror the current 2233 modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 2234 be published in the same document, with NMDA modules in the document 2235 main body and the non-NMDA modules in a non-normative appendix. The 2236 use of the non-NMDA module will allow temporary bridging of the time 2237 period until NMDA implementations are available. 2239 (b) For published models, the model should be republished with an 2240 NMDA-compatible structure, deprecating non-NMDA constructs. For 2241 example, the "ietf-interfaces" model in [RFC7223] has been 2242 restructured as an NMDA-compatible model in 2243 [I-D.ietf-netmod-rfc7223bis]. The "/interfaces-state" hierarchy has 2244 been marked "status deprecated". Models that mark their "/foo-state" 2245 hierarchy with "status deprecated" will allow NMDA-capable 2246 implementations to avoid the cost of duplicating the state nodes, 2247 while enabling non-NMDA-capable implementations to utilize them for 2248 access to the operational values. 2250 (c) For models that augment models which have not been structured 2251 with the NMDA, the modeler will have to consider the structure of the 2252 base model and the guidelines listed above. Where possible, such 2253 models should move to new revisions of the base model that are NMDA- 2254 compatible. When that is not possible, augmenting "state" containers 2255 SHOULD be avoided, with the expectation that the base model will be 2256 re-released with the state containers marked as deprecated. It is 2257 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 2258 Where this recommendation cannot be followed, then any new "state" 2259 elements SHOULD be included in their own module. 2261 4.23.3.1. Temporary non-NMDA Modules 2263 A temporary non-NMDA module allows a non-NMDA aware client to access 2264 operational state from an NMDA-compliant server. It contains the 2265 top-level config=false data nodes that would have been defined in a 2266 legacy YANG module (before NMDA). 2268 A server that needs to support both NMDA and non-NMDA clients can 2269 advertise both the new NMDA module and the temporary non-NMDA module. 2270 A non-NMDA client can use separate "foo" and "foo-state" subtrees, 2271 except the "foo-state" subtree is located in a different (temporary) 2272 module. The NMDA module can be used by a non-NMDA client to access 2273 the conventional configuration datastores, and the deprecated 2274 operation to access nested config=false data nodes. 2276 To create the temporary non-NMDA model from an NMDA model, the 2277 following steps can be taken: 2279 o Change the module name by appending "-state" to the original 2280 module name 2282 o Change the namespace by appending "-state" to the original 2283 namespace value 2285 o Change the prefix by appending "-s" to the original prefix value 2287 o Add an import to the original module (e.g., for typedef 2288 definitions) 2290 o Retain or create only the top-level nodes that have a "config" 2291 statement value "false". These subtrees represent config=false 2292 data nodes that were combined into the configuration subtree, and 2293 therefore not available to non-NMDA aware clients. Set the 2294 "status" statement to "deprecated" for each new node. 2296 o The module description SHOULD clearly identify the module as a 2297 temporary non-NMDA module 2299 4.23.3.2. Example: Create a New NMDA Module 2301 Create an NMDA-compliant module, using combined configuration and 2302 state subtrees, whenever possible. 2304 module example-foo { 2305 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2306 prefix "foo"; 2308 container foo { 2309 // configuration data child nodes 2310 // operational value in operational state datastore only 2311 // may contain config=false nodes as needed 2312 } 2313 } 2315 4.23.3.3. Example: Convert an old Non-NMDA Module 2317 Do not remove non-compliant objects from existing modules. Instead, 2318 change the status to "deprecated". At some point, usually after 1 2319 year, the status MAY be changed to "obsolete". 2321 Old Module: 2323 module example-foo { 2324 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2325 prefix "foo"; 2327 container foo { 2328 // configuration data child nodes 2329 } 2331 container foo-state { 2332 config false; 2333 // operational state child nodes 2334 } 2335 } 2337 Converted NMDA Module: 2339 module example-foo { 2340 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2341 prefix "foo"; 2343 container foo { 2344 // configuration data child nodes 2345 // operational value in operational state datastore only 2346 // may contain config=false nodes as needed 2347 // will contain any data nodes from old foo-state 2348 } 2350 // keep original foo-state but change status to deprecated 2351 container foo-state { 2352 config false; 2353 status deprecated; 2354 // operational state child nodes 2355 } 2356 } 2358 4.23.3.4. Example: Create a Temporary NMDA Module: 2360 Create a new module that contains the top-level operational state 2361 data nodes that would have been available before they were combined 2362 with configuration data nodes (to be NMDA compliant). 2364 module example-foo-state { 2365 namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; 2366 prefix "foo-s"; 2368 // import new or converted module; not used in this example 2369 import example-foo { prefix foo; } 2371 container foo-state { 2372 config false; 2373 status deprecated; 2374 // operational state child nodes 2375 } 2376 } 2378 4.24. Performance Considerations 2380 It is generally likely that certain YANG statements require more 2381 runtime resources than other statements. Although there are no 2382 performance requirements for YANG validation, the following 2383 information MAY be considered when designing YANG data models: 2385 o Lists are generally more expensive than containers 2387 o "when-stmt" evaluation is generally more expensive than 2388 "if-feature" or "choice" statements 2390 o "must" statement is generally more expensive than "min-entries", 2391 "max-entries", "mandatory", or "unique" statements 2393 o "identityref" leafs are generally more expensive than 2394 "enumeration" leafs 2396 o "leafref" and "instance-identifier" types with "require-instance" 2397 set to true are generally more expensive than if 2398 "require-instance" is set to false 2400 4.25. Open Systems Considerations 2402 Only the modules imported by a particular module can be assumed to be 2403 present in an implementation. An open system MAY include any 2404 combination of YANG modules. 2406 4.26. Guidelines for YANG 1.1 Specific Constructs 2408 The set of YANG 1.1 guidelines will grow as operational experience is 2409 gained with the new language features. This section contains an 2410 initial set of guidelines for new YANG 1.1 language features. 2412 4.26.1. Importing Multiple Revisions 2414 Standard modules SHOULD NOT import multiple revisions of the same 2415 module into a module. This MAY be done if independent definitions 2416 (e.g. enumeration typedefs) from specific revisions are needed in the 2417 importing module. 2419 4.26.2. Using Feature Logic 2421 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2422 "description" statement SHOULD describe the "if-feature" logic in 2423 text, to help readers understand the module. 2425 YANG features SHOULD be used instead of the "when" statement, if 2426 possible. Features are advertised by the server and objects 2427 conditional by if-feature are conceptually grouped together. There 2428 is no such commonality supported for "when" statements. 2430 Features generally require less server implementation complexity and 2431 runtime resources than objects that use "when" statements. Features 2432 are generally static (i.e., set when module is loaded and not changed 2433 at runtime). However every client edit might cause a "when" 2434 statement result to change. 2436 4.26.3. anyxml vs. anydata 2438 The "anyxml" statement MUST NOT be used to represent a conceptual 2439 subtree of YANG data nodes. The "anydata" statement MUST be used for 2440 this purpose. 2442 4.26.4. action vs. rpc 2444 The use of "action" statements or "rpc" statements is a subjective 2445 design decision. RPC operations are not associated with any 2446 particular data node. Actions are associated with a specific data 2447 node definition. An "action" statement SHOULD be used if the 2448 protocol operation is specific to a subset of all data nodes instead 2449 of all possible data nodes. 2451 The same action name MAY be used in different definitions within 2452 different data node. For example, a "reset" action defined with a 2453 data node definition for an interface might have different parameters 2454 than for a power supply or a VLAN. The same action name SHOULD be 2455 used to represent similar semantics. 2457 The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis] 2458 does not support parameter-based access control for RPC operations. 2459 The user is given permission (or not) to invoke the RPC operation 2460 with any parameters. For example, if each client is only allowed to 2461 reset their own interface, then NACM cannot be used. 2463 For example, NACM cannot enforce access access control based on the 2464 value of the "interface" parameter, only the "reset" operation 2465 itself: 2467 rpc reset { 2468 input { 2469 leaf interface { 2470 type if:interface-ref; 2471 mandatory true; 2472 description "The interface to reset."; 2473 } 2474 } 2475 } 2477 However, NACM can enforce access access control for individual 2478 interface instances, using a "reset" action, If the user does not 2479 have read access to the specific "interface" instance, then it cannot 2480 invoke the "reset" action for that interface instance: 2482 container interfaces { 2483 list interface { 2484 ... 2485 action reset { } 2486 } 2487 } 2489 4.27. Updating YANG Modules (Published vs. Unpublished) 2491 YANG modules can change over time. Typically, new data model 2492 definitions are needed to support new features. YANG update rules 2493 defined in section 11 of [RFC7950] MUST be followed for published 2494 modules. They MAY be followed for unpublished modules. 2496 The YANG update rules only apply to published module revisions. Each 2497 organization will have their own way to identify published work which 2498 is considered to be stable, and unpublished work which is considered 2499 to be unstable. For example, in the IETF, the RFC document is used 2500 for published work, and the Internet-Draft is used for unpublished 2501 work. 2503 5. IANA Considerations 2505 -- RFC Ed: These registries need to be updated to reference this 2506 RFC instead of RFC 6087 for the ietf-template module, and 2507 remove this note. 2509 This document registers one URI in the IETF XML registry [RFC3688]. 2511 The following registration has been made in [RFC6087] and updated by 2512 this document. 2514 URI: urn:ietf:params:xml:ns:yang:ietf-template 2516 Registrant Contact: The IESG. 2518 XML: N/A, the requested URI is an XML namespace. 2520 The following assignment has been made in [RFC6087] and updated by 2521 this document in the YANG Module Names Registry, or the YANG module 2522 template in Appendix C. 2524 +-----------+-------------------------------------------+ 2525 | Field | Value | 2526 +-----------+-------------------------------------------+ 2527 | Name | ietf-template | 2528 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2529 | Prefix | temp | 2530 | Reference | RFC XXXX | 2531 +-----------+-------------------------------------------+ 2533 YANG Registry Assignment 2535 6. Security Considerations 2537 This document defines documentation guidelines for NETCONF or 2538 RESTCONF content defined with the YANG data modeling language, and 2539 therefore does not introduce any new or increased security risks into 2540 the management system. 2542 7. Acknowledgments 2544 The structure and contents of this document are adapted from 2545 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2547 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2548 Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive 2549 reviews and contributions to this document. 2551 8. References 2553 8.1. Normative References 2555 [I-D.ietf-netmod-revised-datastores] 2556 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2557 and R. Wilton, "Network Management Datastore 2558 Architecture", draft-ietf-netmod-revised-datastores-10 2559 (work in progress), January 2018. 2561 [ID-Guidelines] 2562 Housley, R., Ed., "Guidelines to Authors of Internet- 2563 Drafts", December 2010, 2564 . 2566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2567 Requirement Levels", BCP 14, RFC 2119, March 1997. 2569 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2570 January 2004. 2572 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2573 Resource Identifier (URI): Generic Syntax", STD 66, 2574 RFC 3986, January 2005. 2576 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2577 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 2578 RFC5246, August 2008, 2579 . 2581 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2582 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2584 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2585 Network Configuration Protocol (NETCONF)", RFC 6020, 2586 October 2010. 2588 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2589 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2590 . 2592 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2593 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2594 May 2017, . 2596 [W3C.REC-xpath-19991116] 2597 Clark, J. and S. DeRose, "XML Path Language (XPath) 2598 Version 1.0", World Wide Web Consortium 2599 Recommendation REC-xpath-19991116, November 1999, 2600 . 2602 8.2. Informative References 2604 [I-D.flanagan-7322bis] 2605 Flanagan, H. and R. Editor, "RFC Style Guide", 2606 draft-flanagan-7322bis-02 (work in progress), 2607 September 2017. 2609 [I-D.ietf-netconf-rfc6536bis] 2610 Bierman, A. and M. Bjorklund, "Network Configuration 2611 Access Control Module", draft-ietf-netconf-rfc6536bis-09 2612 (work in progress), December 2017. 2614 [I-D.ietf-netmod-rfc7223bis] 2615 Bjorklund, M., "A YANG Data Model for Interface 2616 Management", draft-ietf-netmod-rfc7223bis-03 (work in 2617 progress), January 2018. 2619 [I-D.ietf-netmod-rfc8022bis] 2620 Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 2621 Routing Management (NMDA Version)", 2622 draft-ietf-netmod-rfc8022bis-11 (work in progress), 2623 January 2018. 2625 [I-D.ietf-netmod-yang-tree-diagrams] 2626 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2627 draft-ietf-netmod-yang-tree-diagrams-06 (work in 2628 progress), February 2018. 2630 [RFC-STYLE] 2631 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2632 Style", September 2009, 2633 . 2635 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2636 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2637 . 2639 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2640 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2641 . 2643 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2644 Documents", BCP 111, RFC 4181, September 2005. 2646 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2647 Data Model Documents", RFC 6087, January 2011. 2649 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2650 and A. Bierman, Ed., "Network Configuration Protocol 2651 (NETCONF)", RFC 6241, June 2011. 2653 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2654 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2655 . 2657 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2658 Protocol (NETCONF) Access Control Model", RFC 6536, 2659 March 2012. 2661 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2662 July 2013. 2664 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2665 Management", RFC 7223, May 2014. 2667 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2668 DOI 10.17487/RFC7322, September 2014, 2669 . 2671 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2672 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2673 DOI 10.17487/RFC7841, May 2016, 2674 . 2676 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2677 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2678 . 2680 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2681 Writing an IANA Considerations Section in RFCs", BCP 26, 2682 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2683 . 2685 Appendix A. Change Log 2687 -- RFC Ed.: remove this section before publication. 2689 A.1. v18 to v19 2691 o address IESG ballot comments 2693 A.2. v17 to v18 2695 o address Area Director review comments Part 2 2697 o clarify preferred list key order 2699 A.3. v16 to v17 2701 o address Area Director review comments Part 1 2703 A.4. v15 to v16 2705 o address Area Director review comments posted 2018-01-25 2707 A.5. v15 to v16 2709 o address document shephard comments posted 2018-01-15 2711 o add yang-version to template module 2713 A.6. v14 to v15 2715 o changed Intended status from Informational to BCP 2717 o update tree diagram guidelines section 2719 o Change IANA template to list IESG instead of NETMOD WG as the 2720 Registrant 2722 o Update some references 2724 A.7. v13 to v14 2726 o Replaced sec. 4.23 Operational Data with Operational Data from 2727 NMDA text by Lou Berger and Kent Watsen 2729 o Added NMDA Terms section 2731 o Changed term operational data to operational state 2732 o Clarified that reference-stmt SHOULD be present in import-stmt 2734 A.8. v12 to v13 2736 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2737 YANG file extraction macro. 2739 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2740 module name registries. 2742 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2744 o Update Operation Data section to consider revised datastores. 2746 o Add reference to YANG Tree Diagrams and update 2 sections that use 2747 this reference. 2749 o Add reference to Revised Datastores and guidelines drafts 2751 A.9. v11 to v12 2753 o fix incorrect location of new Module Usage Examples section 2755 A.10. v10 to v11 2757 o updated YANG tree diagram syntax to align with pyang 1.7.1 2759 o added general guideline to include module usage examples 2761 A.11. v09 to v10 2763 o clarified is only for normative modules 2765 o clarified example module namespace URI conventions 2767 o clarified pyang usage for normative and example modules 2769 o updated YANG tree diagrams section with text from RFC 8022 2771 A.12. v08 to v09 2773 o fixed references 2775 o added mention of RESTCONF to abstract and intro 2777 o created separate section for code components 2778 o fixed document status 2780 A.13. v07 to v08 2782 o changed CODE BEGINS guideline for example modules 2784 o updated tree diagram guidelines 2786 o clarified published and unpublished terms 2788 o added section on Empty and Boolean data types 2790 o clarified how to update the revision statement 2792 o updated operational state guidelines 2794 o added 'YANG fragment' to terminology section 2796 A.14. v06 to v07 2798 o update contact statement guideline 2800 o update example modules guidelines 2802 o add guidelines on top-level data nodes 2804 o add guideline on use of NP containers 2806 o added guidelines on union types 2808 o add guideline on deviations 2810 o added section on open systems considerations 2812 o added guideline about definitions reserved for future use 2814 A.15. v05 to v06 2816 o Changed example 'my-module' to 'example-module' 2818 o Added section Updating YANG Modules (Published vs. Unpublished) 2820 o Added Example Modules section 2822 o Added "" convention for full example modules 2824 o Added section on using action vs. rpc 2825 o Changed term "operational state" to "operational data" 2827 o Added section on YANG Data Node Constraints 2829 o Added guidelines on using must vs. when statements 2831 o Made ietf-foo module validate for I-D submission 2833 A.16. v04 to v05 2835 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2836 no YANG 1.1 features needed 2838 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2839 standards track documents only) 2841 o Clarified module naming conventions for normative modules, example 2842 modules, and modules from other SDOs. 2844 o Added prefix value selection guidelines 2846 o Added new section on guidelines for reusable groupings 2848 o Made header guidelines less IETF-specific 2850 o Added new section on guidelines for extension statements 2852 o Added guidelines for nested "choice" statement within a "case" 2853 statement 2855 A.17. v03 ot v04 2857 o Added sections for deviation statements and performance 2858 considerations 2860 o Added YANG 1.1 section 2862 o Updated YANG reference from 1.0 to 1.1 2864 A.18. v02 to v03 2866 o Updated draft based on github data tracker issues added by Benoit 2867 Clause (Issues 12 - 18) 2869 A.19. v01 to v02 2871 o Updated draft based on mailing list comments. 2873 A.20. v00 to v01 2875 All issues from the issue tracker have been addressed. 2877 https://github.com/netmod-wg/rfc6087bis/issues 2879 o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with 2880 YANG modules can use an Informative reference to this RFC for tree 2881 diagrams. Updated guidelines to reference this RFC when tree 2882 diagrams are used 2884 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2885 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2886 functions 2888 o Issue 3: XPath function document order issues: Added paragraph in 2889 XPath usage section about node-set ordering for 'local-name', 2890 'namespace-uri', 'name', 'string' and 'number' functions. Also 2891 any function that implicitly converts a node-set to a string. 2893 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2894 and text in XPath usage section already has proposed text from 2895 Lada. 2897 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2898 exception and example in XPath Usage section for augmented nodes. 2900 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2901 to 'numeric and boolean expressions' 2903 o Issue 7: XPath module containment: Added sub-section on XPath 2904 wildcards 2906 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2907 section about transitioning from active to deprecated and then to 2908 obsolete. 2910 o Issue 9: resource identification in notifications: Add text to 2911 Notifications section about identifying resources and using the 2912 leafref data type. 2914 o Issue 10: single quoted strings: Added text to Data Types section 2915 about using a single-quoted string for patterns. 2917 Appendix B. Module Review Checklist 2919 This section is adapted from RFC 4181. 2921 The purpose of a YANG module review is to review the YANG module both 2922 for technical correctness and for adherence to IETF documentation 2923 requirements. The following checklist may be helpful when reviewing 2924 an Internet-Draft: 2926 o I-D Boilerplate -- verify that the draft contains the required 2927 Internet-Draft boilerplate (see 2928 https://www.ietf.org/id-info/guidelines.html), including the 2929 appropriate statement to permit publication as an RFC, and that 2930 I-D boilerplate does not contain references or section numbers. 2932 o Abstract -- verify that the abstract does not contain references, 2933 that it does not have a section number, and that its content 2934 follows the guidelines in 2935 https://www.ietf.org/id-info/guidelines.html. 2937 o Copyright Notice -- verify that the draft has the appropriate text 2938 regarding the rights that document contributers provide to the 2939 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2940 copyright notice at the beginning of the document. The IETF Trust 2941 Legal Provisions (TLP) can be found at: 2943 https://trustee.ietf.org/license-info/ 2945 o Security Considerations section -- verify that the draft uses the 2946 latest approved template from the OPS area website (https:// 2947 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2948 and that the guidelines therein have been followed. 2950 o IANA Considerations section -- this section must always be 2951 present. For each module within the document, ensure that the 2952 IANA Considerations section contains entries for the following 2953 IANA registries: 2955 XML Namespace Registry: Register the YANG module namespace. 2957 YANG Module Registry: Register the YANG module name, prefix, 2958 namespace, and RFC number, according to the rules specified 2959 in [RFC6020]. 2961 o References -- verify that the references are properly divided 2962 between normative and informative references, that RFC 2119 and 2963 RFC 8174 are included as normative references if the terminology 2964 defined therein is used in the document, that all references 2965 required by the boilerplate are present, that all YANG modules 2966 containing imported items are cited as normative references, and 2967 that all citations point to the most current RFCs unless there is 2968 a valid reason to do otherwise (for example, it is OK to include 2969 an informative reference to a previous version of a specification 2970 to help explain a feature included for backward compatibility). 2971 Be sure citations for all imported modules are present somewhere 2972 in the document text (outside the YANG module). If a YANG module 2973 contains reference or description statements that refer to an 2974 Internet Draft (I-D), then the I-D is included as an Informative 2975 Reference. 2977 o License -- verify that the draft contains the Simplified BSD 2978 License in each YANG module or submodule. Some guidelines related 2979 to this requirement are described in Section 3.1. Make sure that 2980 the correct year is used in all copyright dates. Use the approved 2981 text from the latest Trust Legal Provisions (TLP) document, which 2982 can be found at: 2984 https://trustee.ietf.org/license-info/ 2986 o Other Issues -- check for any issues mentioned in 2987 https://www.ietf.org/id-info/checklist.html that are not covered 2988 elsewhere. 2990 o Technical Content -- review the actual technical content for 2991 compliance with the guidelines in this document. The use of a 2992 YANG module compiler is recommended when checking for syntax 2993 errors. A list of freely available tools and other information 2994 can be found at: 2996 https://trac.tools.ietf.org/wg/netconf/trac/wiki 2998 Checking for correct syntax, however, is only part of the job. 2999 It is just as important to actually read the YANG module document 3000 from the point of view of a potential implementor. It is 3001 particularly important to check that description statements are 3002 sufficiently clear and unambiguous to allow interoperable 3003 implementations to be created. 3005 Appendix C. YANG Module Template 3007 file "ietf-template@2016-03-20.yang" 3009 module ietf-template { 3011 yang-version 1.1; 3013 // replace this string with a unique namespace URN value 3014 namespace 3015 "urn:ietf:params:xml:ns:yang:ietf-template"; 3017 // replace this string, and try to pick a unique prefix 3018 prefix "temp"; 3020 // import statements here: e.g., 3021 // import ietf-yang-types { prefix yang; } 3022 // import ietf-inet-types { prefix inet; } 3024 // identify the IETF working group if applicable 3025 organization 3026 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 3028 // update this contact statement with your info 3029 contact 3030 "WG Web: 3031 WG List: 3033 Editor: your-name 3034 "; 3036 // replace the first sentence in this description statement. 3037 // replace the copyright notice with the most recent 3038 // version, if it has been updated since the publication 3039 // of this document 3040 description 3041 "This module defines a template for other YANG modules. 3043 Copyright (c) IETF Trust and the persons 3044 identified as authors of the code. All rights reserved. 3046 Redistribution and use in source and binary forms, with or 3047 without modification, is permitted pursuant to, and subject 3048 to the license terms contained in, the Simplified BSD License 3049 set forth in Section 4.c of the IETF Trust's Legal Provisions 3050 Relating to IETF Documents 3051 (http://trustee.ietf.org/license-info). 3052 This version of this YANG module is part of RFC XXXX; see 3053 the RFC itself for full legal notices."; 3055 // RFC Ed.: replace XXXX with actual RFC number and remove 3056 // this note 3058 reference "RFC XXXX"; 3060 // RFC Ed.: remove this note 3061 // Note: extracted from RFC XXXX 3063 // replace '2016-03-20' with the module publication date 3064 // The format is (year-month-day) 3065 revision "2016-03-20" { 3066 description "what changed in this revision"; 3067 reference "document containing this module"; 3068 } 3070 // extension statements 3072 // feature statements 3074 // identity statements 3076 // typedef statements 3078 // grouping statements 3080 // data definition statements 3082 // augment statements 3084 // rpc statements 3086 // notification statements 3088 // DO NOT put deviation statements in a published module 3090 } 3092 3094 Author's Address 3096 Andy Bierman 3097 YumaWorks 3099 Email: andy@yumaworks.com