idnits 2.17.1 draft-ietf-netmod-rfc6087bis-20.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 13, 2018) is 2235 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 2582, 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 13, 2018 5 Intended status: BCP 6 Expires: September 14, 2018 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-20 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 14, 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. v19 to v20 . . . . . . . . . . . . . . . . . . . . . . . . 63 142 A.2. v18 to v19 . . . . . . . . . . . . . . . . . . . . . . . . 63 143 A.3. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 63 144 A.4. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 63 145 A.5. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 146 A.6. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 147 A.7. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 63 148 A.8. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 63 149 A.9. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 64 150 A.10. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 64 151 A.11. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 64 152 A.12. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 64 153 A.13. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 64 154 A.14. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 65 155 A.15. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 65 156 A.16. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 65 157 A.17. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 66 158 A.18. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 66 159 A.19. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 66 160 A.20. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 67 161 A.21. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 67 162 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 68 163 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 70 164 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 166 1. Introduction 168 The standardization of network configuration interfaces for use with 169 network configuration management protocols, such as the Network 170 Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a 171 modular set of data models, which can be reused and extended over 172 time. 174 This document defines a set of usage guidelines for documents 175 containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models. 176 YANG is used to define the data structures, protocol operations, and 177 notification content used within a NETCONF and/or RESTCONF server. A 178 NETCONF or RESTCONF server that supports a particular YANG module 179 will support client NETCONF and/or RESTCONF operation requests, as 180 indicated by the specific content defined in the YANG module. 182 Many YANG constructs are defined as optional to use, such as the 183 description statement. However, in order to make YANG modules more 184 useful, it is desirable to define a set of usage guidelines that 185 entails a higher level of compliance than the minimum level defined 186 in the YANG specification. 188 In addition, YANG allows constructs such as infinite length 189 identifiers and string values, or top-level mandatory nodes, that a 190 compliant server is not required to support. Only constructs that 191 all servers are required to support can be used in IETF YANG modules. 193 This document defines usage guidelines related to the NETCONF 194 operations layer and NETCONF content layer, as defined in [RFC6241], 195 and the RESTCONF methods and RESTCONF resources, as defined in 196 [RFC8040], 198 These guidelines are intended to be used by authors and reviewers to 199 improve the readability and interoperability of published YANG data 200 models. 202 Note that this document is not a YANG tutorial and the reader is 203 expected to know the YANG data modeling language before using this 204 document. 206 1.1. Changes Since RFC 6087 208 The following changes have been made to the guidelines published in 209 [RFC6087]: 211 o Updated NETCONF reference from RFC 4741 to RFC 6241 212 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 214 o Updated YANG Types reference from RFC 6021 to RFC 6991 216 o Updated obsolete URLs for IETF resources 218 o Changed top-level data node guideline 220 o Clarified XPath usage for a literal value representing a YANG 221 identity 223 o Clarified XPath usage for a when-stmt 225 o Clarified XPath usage for 'proceeding-sibling' and 226 'following-sibling' axes 228 o Added terminology guidelines 230 o Added YANG tree diagram guidelines 232 o Updated XPath guidelines for type conversions and function library 233 usage. 235 o Updated data types section 237 o Updated notifications section 239 o Clarified conditional key leaf nodes 241 o Clarify usage of 'uint64' and 'int64' data types 243 o Added text on YANG feature usage 245 o Added Identifier Naming Conventions 247 o Clarified use of mandatory nodes with conditional augmentations 249 o Clarified namespace and domain conventions for example modules 251 o Clarified conventions for identifying code components 253 o Added YANG 1.1 guidelines 255 o Added Data Model Constraints section 257 o Added mention of RESTCONF protocol 258 o Added guidelines for NMDA Revised Datastores 260 2. Terminology 262 2.1. Requirements Notation 264 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 265 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 266 document are to be interpreted as described in BCP 14 [RFC2119] 267 [RFC8174] when, and only when, they appear in all capitals, as shown 268 here. 270 2.2. NETCONF Terms 272 The following terms are defined in [RFC6241] and are not redefined 273 here: 275 o capabilities 277 o client 279 o operation 281 o server 283 2.3. YANG Terms 285 The following terms are defined in [RFC7950] and are not redefined 286 here: 288 o data node 290 o module 292 o namespace 294 o submodule 296 o version 298 o YANG 300 o YIN 302 Note that the term 'module' may be used as a generic term for a YANG 303 module or submodule. When describing properties that are specific to 304 submodules, the term 'submodule' is used instead. 306 2.4. NMDA Terms 308 The following terms are defined in the Network Management Datastore 309 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not 310 redefined here: 312 o configuration 314 o conventional configuration datastore 316 o datastore 318 o operational state 320 o operational state datastore 322 2.5. Terms 324 The following terms are used throughout this document: 326 o published: A stable release of a module or submodule. For example 327 the "Request for Comments" described in section 2.1 of [RFC2026] 328 is considered a stable publication. 330 o unpublished: An unstable release of a module or submodule. For 331 example the "Internet-Draft" described in section 2.2 of [RFC2026] 332 is considered an unstable publication that is a work-in-progress, 333 subject to change at any time. 335 o YANG fragment: A set of YANG statements that are not intended to 336 represent a complete YANG module or submodule. These statements 337 are not intended for actual use, except to provide an example of 338 YANG statement usage. The invalid syntax "..." is sometimes used 339 to indicate that additional YANG statements would be present in a 340 real YANG module. 342 o YANG tree diagram: a diagram representing the contents of a YANG 343 module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also 344 called a "tree diagram". 346 3. General Documentation Guidelines 348 YANG data model modules under review are likely to be contained in 349 Internet-Drafts. All guidelines for Internet-Draft authors 350 [ID-Guidelines] MUST be followed. The RFC Editor provides guidelines 351 for authors of RFCs, which are first published as Internet-Drafts. 352 These guidelines should be followed and are defined in [RFC7322] and 353 updated in [RFC7841], "RFC Document Style" [RFC-STYLE], and 354 [I-D.flanagan-7322bis]. 356 The following sections MUST be present in an Internet-Draft 357 containing a module: 359 o Narrative sections 361 o Definitions section 363 o Security Considerations section 365 o IANA Considerations section 367 o References section 369 There are three usage scenarios for YANG that can appear in an 370 Internet-Draft or RFC: 372 o normative module or submodule 374 o example module or submodule 376 o example YANG fragment not part of any module or submodule 378 The guidelines in this document refer mainly to a normative module or 379 submodule, but may be applicable to example modules and YANG 380 fragments as well. 382 3.1. Module Copyright 384 The module description statement MUST contain a reference to the 385 latest approved IETF Trust Copyright statement, which is available 386 online at: 388 https://trustee.ietf.org/license-info/ 390 3.2. Code Components 392 Each normative YANG module or submodule contained within an Internet- 393 Draft or RFC is considered to be a code component. The strings 394 "" and "" MUST be used to identify each code 395 component. 397 The "" tag SHOULD be followed by a string identifying 398 the file name specified in Section 5.2 of [RFC7950]. The name string 399 form that includes the revision-date SHOULD be used. The revision 400 date MUST match the date used in the most recent revision of the 401 module. 403 The following example is for the '2016-03-20' revision of the 404 'ietf-foo' module: 406 file "ietf-foo@2016-03-20.yang" 408 module ietf-foo { 409 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 410 prefix "foo"; 411 organization "..."; 412 contact "..."; 413 description "..."; 414 revision 2016-03-20 { 415 description "Latest revision"; 416 reference "RFC XXXX: Foo Protocol"; 417 } 418 // ... more statements 419 } 421 423 3.2.1. Example Modules 425 Example modules are not code components. The 426 convention MUST NOT be used for example modules. 428 An example module SHOULD be named using the term "example", followed 429 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 430 See Section 4.9 regarding the namespace guidelines for example 431 modules. 433 3.3. Terminology Section 435 A terminology section MUST be present if any terms are defined in the 436 document or if any terms are imported from other documents. 438 3.4. Tree Diagrams 440 YANG tree diagrams provide a concise representation of a YANG module, 441 and SHOULD be included to help readers understand YANG module 442 structure. Guidelines on tree diagrams can be found in Section 3 of 443 [I-D.ietf-netmod-yang-tree-diagrams]. 445 If YANG tree diagrams are used, then an informative reference to the 446 YANG tree diagrams specification MUST be included in the document. 447 Refer to Section 2.2 of [I-D.ietf-netmod-rfc8022bis] for an example 448 of such a reference. 450 3.5. Narrative Sections 452 The narrative part MUST include an overview section that describes 453 the scope and field of application of the module(s) defined by the 454 specification and that specifies the relationship (if any) of these 455 modules to other standards, particularly to standards containing 456 other YANG modules. The narrative part SHOULD include one or more 457 sections to briefly describe the structure of the modules defined in 458 the specification. 460 If the module(s) defined by the specification imports definitions 461 from other modules (except for those defined in the [RFC7950] or 462 [RFC6991] documents), or are always implemented in conjunction with 463 other modules, then those facts MUST be noted in the overview 464 section, as MUST be noted any special interpretations of definitions 465 in other modules. Refer to section 2.3 of 466 [I-D.ietf-netmod-rfc8022bis] for an example of this overview section. 468 If the documents contains YANG module(s) that are compliant with the 469 Network Management Datastore Architecture (NMDA) 470 [I-D.ietf-netmod-revised-datastores], then the Introduction section 471 should mention this fact. 473 Example: 475 The YANG model in this document conforms to the Network 476 Management Datastore Architecture defined in 477 [I-D.ietf-netmod-revised-datastores]. 479 Consistent indentation SHOULD be used for all examples, including 480 YANG fragments and protocol message instance data. If line wrapping 481 is done for formatting purposes, then this SHOULD be noted, as shown 482 in the following example: 484 [note: '\' line wrapping for formatting only] 485 \ 486 this is a long value so the line needs to wrap to stay\ 487 within 72 characters\ 488 490 3.6. Definitions Section 492 This section contains the module(s) defined by the specification. 493 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 494 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 495 semantics are needed in the module. If any of the imported YANG 496 modules are written using YANG 1.1, then the module MUST be written 497 using YANG 1.1. 499 A YIN syntax version of the module MAY also be present in the 500 document. There MAY also be other types of modules present in the 501 document, such as SMIv2, which are not affected by these guidelines. 503 Note that if the module itself is considered normative and not an 504 example module or example YANG fragment, then all YANG statements 505 within a YANG module are considered normative. The use of keywords 506 defined in [RFC2119] apply to YANG description statements in 507 normative modules exactly as they would in any other normative 508 section. 510 Example YANG modules and example YANG fragments MUST NOT contain any 511 normative text, including any all-uppercase reserved words from 512 [RFC2119]. 514 Consistent indentation and formatting SHOULD be used in all YANG 515 statements within a module. 517 See Section 4 for guidelines on YANG usage. 519 3.7. Security Considerations Section 521 Each specification that defines one or more modules MUST contain a 522 section that discusses security considerations relevant to those 523 modules. 525 This section MUST be patterned after the latest approved template 526 (available at 527 https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines). 528 Section 3.7.1 contains the security considerations template dated 529 2013-05-08 and last updated 2017-12-21. Authors MUST check the WEB 530 page at the URL listed above in case there is a more recent version 531 available. 533 In particular: 535 o Writable data nodes that could be especially disruptive if abused 536 MUST be explicitly listed by name and the associated security 537 risks MUST be explained. 539 o Readable data nodes that contain especially sensitive information 540 or that raise significant privacy concerns MUST be explicitly 541 listed by name and the reasons for the sensitivity/privacy 542 concerns MUST be explained. 544 o Operations (i.e., YANG 'rpc' statements) that are potentially 545 harmful to system behavior or that raise significant privacy 546 concerns MUST be explicitly listed by name and the reasons for the 547 sensitivity/privacy concerns MUST be explained. 549 3.7.1. Security Considerations Section Template 551 X. Security Considerations 553 The YANG module specified in this document defines a schema for data 554 that is designed to be accessed via network management protocols such 555 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 556 is the secure transport layer, and the mandatory-to-implement secure 557 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 558 is HTTPS, and the mandatory-to-implement secure transport is TLS 559 [RFC5246]. 561 The NETCONF access control model [RFC6536] provides the means to 562 restrict access for particular NETCONF or RESTCONF users to a 563 preconfigured subset of all available NETCONF or RESTCONF protocol 564 operations and content. 566 -- if you have any writeable data nodes (those are all the 567 -- "config true" nodes, and remember, that is the default) 568 -- describe their specific sensitivity or vulnerability. 570 There are a number of data nodes defined in this YANG module that are 571 writable/creatable/deletable (i.e., config true, which is the 572 default). These data nodes may be considered sensitive or vulnerable 573 in some network environments. Write operations (e.g., edit-config) 574 to these data nodes without proper protection can have a negative 575 effect on network operations. These are the subtrees and data nodes 576 and their sensitivity/vulnerability: 578 579 -- for all YANG modules you must evaluate whether any readable data 580 -- nodes (those are all the "config false" nodes, but also all other 581 -- nodes, because they can also be read via operations like get or 582 -- get-config) are sensitive or vulnerable (for instance, if they 583 -- might reveal customer information or violate personal privacy 584 -- laws such as those of the European Union if exposed to 585 -- unauthorized parties) 587 Some of the readable data nodes in this YANG module may be considered 588 sensitive or vulnerable in some network environments. It is thus 589 important to control read access (e.g., via get, get-config, or 590 notification) to these data nodes. These are the subtrees and data 591 nodes and their sensitivity/vulnerability: 593 595 -- if your YANG module has defined any rpc operations 596 -- describe their specific sensitivity or vulnerability. 598 Some of the RPC operations in this YANG module may be considered 599 sensitive or vulnerable in some network environments. It is thus 600 important to control access to these operations. These are the 601 operations and their sensitivity/vulnerability: 603 605 3.8. IANA Considerations Section 607 In order to comply with IESG policy as set forth in 608 https://www.ietf.org/id-info/checklist.html, every Internet-Draft 609 that is submitted to the IESG for publication MUST contain an IANA 610 Considerations section. The requirements for this section vary 611 depending on what actions are required of the IANA. If there are no 612 IANA considerations applicable to the document, then the IANA 613 Considerations section stating that there are no actions might be 614 removed by the RFC Editor before publication. Refer to the 615 guidelines in [RFC8126] for more details. 617 Each normative YANG module MUST be registered in the XML namespace 618 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 619 This applies to new modules and updated modules. Examples of these 620 registrations for the "ietf-template" module can be found in 621 Section 5. 623 3.8.1. Documents that Create a New Namespace 625 If an Internet-Draft defines a new namespace that is to be 626 administered by the IANA, then the document MUST include an IANA 627 Considerations section that specifies how the namespace is to be 628 administered. 630 Specifically, if any YANG module namespace statement value contained 631 in the document is not already registered with IANA, then a new YANG 632 Namespace registry entry MUST be requested from the IANA. The 633 [RFC7950] specification includes the procedure for this purpose in 634 its IANA Considerations section. 636 3.8.2. Documents that Extend an Existing Namespace 638 It is possible to extend an existing namespace using a YANG submodule 639 that belongs to an existing module already administered by IANA. In 640 this case, the document containing the main module MUST be updated to 641 use the latest revision of the submodule. 643 3.9. Reference Sections 645 For every import or include statement that appears in a module 646 contained in the specification, that identifies a module in a 647 separate document, a corresponding normative reference to that 648 document MUST appear in the Normative References section. The 649 reference MUST correspond to the specific module version actually 650 used within the specification. 652 For every normative reference statement that appears in a module 653 contained in the specification, that identifies a separate document, 654 a corresponding normative reference to that document SHOULD appear in 655 the Normative References section. The reference SHOULD correspond to 656 the specific document version actually used within the specification. 657 If the reference statement identifies an informative reference, that 658 identifies a separate document, a corresponding informative reference 659 to that document MAY appear in the Informative References section. 661 3.10. Validation Tools 663 All modules need to be validated before submission in an Internet 664 Draft. The 'pyang' YANG compiler is freely available from github: 666 https://github.com/mbj4668/pyang 668 If the 'pyang' compiler is used to validate a normative module, then 669 the "--ietf" command line option MUST be used to identify any IETF 670 guideline issues. 672 If the 'pyang' compiler is used to validate an example module, then 673 the "--ietf" command line option MAY be used to identify any IETF 674 guideline issues. 676 The "yanglint" program is also freely available from github. 678 https://github.com/CESNET/libyang 680 This tool can be used to validate XPath statements within YANG 681 modules. 683 3.11. Module Extraction Tools 685 A version of 'rfcstrip' is available which will extract YANG modules 686 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 687 YANG module extraction is freely available: 689 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 691 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 693 can be extracted correctly. 695 The "xym" tool is freely available on github and can be used to 696 extract YANG modules from a document. 698 https://github.com/xym-tool/xym 700 3.12. Module Usage Examples 702 Each specification that defines one or more modules SHOULD contain 703 usage examples, either throughout the document or in an appendix. 704 This includes example instance document snippets in an appropriate 705 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 706 the YANG module(s). Example modules MUST be validated. Refer to 707 Section 3.10 for tools which validate YANG modules. If IP addresses 708 are used, then either a mix of IPv4 and IPv6 addresses or IPv6 709 addresses exclusively SHOULD be used in the examples. 711 4. YANG Usage Guidelines 713 Modules in IETF Standards Track specifications MUST comply with all 714 syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the 715 exception for YANG 1.0 in Section 3.6. The guidelines in this 716 section are intended to supplement the YANG specification, which is 717 intended to define a minimum set of conformance requirements. 719 In order to promote interoperability and establish a set of practices 720 based on previous experience, the following sections establish usage 721 guidelines for specific YANG constructs. 723 Only guidelines that clarify or restrict the minimum conformance 724 requirements are included here. 726 4.1. Module Naming Conventions 728 Normative modules contained in Standards Track documents MUST be 729 named according to the guidelines in the IANA Considerations section 730 of [RFC7950]. 732 A distinctive word or acronym (e.g., protocol name or working group 733 acronym) SHOULD be used in the module name. If new definitions are 734 being defined to extend one or more existing modules, then the same 735 word or acronym should be reused, instead of creating a new one. 737 All published module names MUST be unique. For a YANG module 738 published in an RFC, this uniqueness is guaranteed by IANA. For 739 unpublished modules, the authors need to check that no other work in 740 progress is using the same module name. 742 Example modules are non-normative, and SHOULD be named with the 743 prefix "example-". 745 It is suggested that a stable prefix be selected representing the 746 entire organization. All normative YANG modules published by the 747 IETF MUST begin with the prefix "ietf-". Another standards 748 organization, such as the IEEE, might use the prefix "ieee-" for all 749 YANG modules. 751 Once a module name is published, it MUST NOT be reused, even if the 752 RFC containing the module is reclassified to 'Historic' status. A 753 module name cannot be changed in YANG, and this would be treated as a 754 a new module, not a name change. 756 4.2. Prefixes 758 All YANG definitions are scoped by the module containing the 759 definition being referenced. This allows definitions from multiple 760 modules to be used, even if the names are not unique. In the example 761 below, the identifier "foo" is used in all 3 modules: 763 module example-foo { 764 namespace "tag:example.com,2017:example-foo"; 765 prefix f; 767 container foo; 768 } 770 module example-bar { 771 namespace "tag:example.com,2017:example-bar"; 772 prefix b; 774 typedef foo { type uint32; } 775 } 777 module example-one { 778 namespace "tag:example.com,2017:example-one"; 779 prefix one; 780 import example-foo { prefix f; } 781 import example-bar { prefix b; } 783 augment "/f:foo" { 784 leaf foo { type b:foo; } 785 } 786 } 788 YANG defines the following rules for prefix usage: 790 o Prefixes are never used for built in data types and YANG keywords. 792 o A prefix MUST be used for any external statement (i.e., a 793 statement defined with the YANG "extension" statement) 795 o The proper module prefix MUST be used for all identifiers imported 796 from other modules 798 o The proper module prefix MUST be used for all identifiers included 799 from a submodule. 801 The following guidelines apply to prefix usage of the current (local) 802 module: 804 o The local module prefix SHOULD be used instead of no prefix in all 805 path expressions. 807 o The local module prefix MUST be used instead of no prefix in all 808 "default" statements for an "identityref" or "instance-identifier" 809 data type 811 o The local module prefix MAY be used for references to typedefs, 812 groupings, extensions, features, and identities defined in the 813 module. 815 Prefix values SHOULD be short, but also likely to be unique. Prefix 816 values SHOULD NOT conflict with known modules that have been 817 previously published. 819 4.3. Identifiers 821 Identifiers for all YANG identifiers in published modules MUST be 822 between 1 and 64 characters in length. These include any construct 823 specified as an 'identifier-arg-str' token in the ABNF in Section 13 824 of [RFC7950]. 826 4.3.1. Identifier Naming Conventions 828 Identifiers SHOULD follow a consistent naming pattern throughout the 829 module. Only lower-case letters, numbers, and dashes SHOULD be used 830 in identifier names. Upper-case characters, the period character, 831 and the underscore character MAY be used if the identifier represents 832 a well-known value that uses these characters. YANG does not permit 833 any other characters in YANG identifiers. 835 Identifiers SHOULD include complete words and/or well-known acronyms 836 or abbreviations. Child nodes within a container or list SHOULD NOT 837 replicate the parent identifier. YANG identifiers are hierarchical 838 and are only meant to be unique within the the set of sibling nodes 839 defined in the same module namespace. 841 It is permissible to use common identifiers such as "name" or "id" in 842 data definition statements, especially if these data nodes share a 843 common data type. 845 Identifiers SHOULD NOT carry any special semantics that identify data 846 modelling properties. Only YANG statements and YANG extension 847 statements are designed to convey machine readable data modelling 848 properties. For example, naming an object "config" or "state" does 849 not change whether it is configuration data or state data. Only 850 defined YANG statements or YANG extension statements can be used to 851 assign semantics in a machine readable format in YANG. 853 4.4. Defaults 855 In general, it is suggested that substatements containing very common 856 default values SHOULD NOT be present. The following substatements 857 are commonly used with the default value, which would make the module 858 difficult to read if used everywhere they are allowed. 860 +--------------+---------------+ 861 | Statement | Default Value | 862 +--------------+---------------+ 863 | config | true | 864 | mandatory | false | 865 | max-elements | unbounded | 866 | min-elements | 0 | 867 | ordered-by | system | 868 | status | current | 869 | yin-element | false | 870 +--------------+---------------+ 872 Statement Defaults 874 4.5. Conditional Statements 876 A module may be conceptually partitioned in several ways, using the 877 'if-feature' and/or 'when' statements. 879 Data model designers need to carefully consider all modularity 880 aspects, including the use of YANG conditional statements. 882 If a data definition is optional, depending on server support for a 883 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 884 statement SHOULD be defined. The defined "feature" statement SHOULD 885 then be used in the conditional "if-feature" statement referencing 886 the optional data definition. 888 If any notification data, or any data definition, for a non- 889 configuration data node is not mandatory, then the server may or may 890 not be required to return an instance of this data node. If any 891 conditional requirements exist for returning the data node in a 892 notification payload or retrieval request, they MUST be documented 893 somewhere. For example, a 'when' or 'if-feature' statement could 894 apply to the data node, or the conditional requirements could be 895 explained in a 'description' statement within the data node or one of 896 its ancestors (if any). 898 If any 'if-feature' statements apply to a list node, then the same 899 'if-feature' statements MUST apply to any key leaf nodes for the 900 list. There MUST NOT be any 'if-feature' statements applied to any 901 key leaf that do not also apply to the parent list node. 903 There SHOULD NOT be any 'when' statements applied to a key leaf node. 904 It is possible that a 'when' statement for an ancestor node of a key 905 leaf will have the exact node-set result as the key leaf. In such a 906 case, the 'when' statement for the key leaf is redundant and SHOULD 907 be avoided. 909 4.6. XPath Usage 911 This section describes guidelines for using the XML Path Language 912 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 914 4.6.1. XPath Evaluation Contexts 916 YANG defines 5 separate contexts for evaluation of XPath statements: 918 1) The "running" datastore: collection of all YANG configuration data 919 nodes. The document root is the conceptual container, (e.g., 920 "config" in the "edit-config" operation), which is the parent of all 921 top-level data definition statements with a "config" statement value 922 of "true". 924 2) State data + the "running" datastore: collection of all YANG data 925 nodes. The document root is the conceptual container, parent of all 926 top-level data definition statements. 928 3) Notification: an event notification document. The document root 929 is the notification element. 931 4) RPC Input: The document root is the conceptual "input" node, which 932 is the parent of all RPC input parameter definitions. 934 5) RPC Output: The document root is the conceptual "output" node, 935 which is the parent of all RPC output parameter definitions. 937 Note that these XPath contexts cannot be mixed. For example, a 938 "when" statement in a notification context cannot reference 939 configuration data. 941 notification foo { 942 leaf mtu { 943 // NOT OK because when-stmt context is this notification 944 when "/if:interfaces/if:interface[name='eth0']"; 945 type leafref { 946 // OK because path-stmt has a different context 947 path "/if:interfaces/if:interface/if:mtu"; 948 } 949 } 950 } 952 It is especially important to consider the XPath evaluation context 953 for XPath expressions defined in groupings. An XPath expression 954 defined in a grouping may not be portable, meaning it cannot be used 955 in multiple contexts and produce proper results. 957 If the XPath expressions defined in a grouping are intended for a 958 particular context, then this context SHOULD be identified in the 959 "description" statement for the grouping. 961 4.6.2. Function Library 963 The 'position' and 'last' functions SHOULD NOT be used. This applies 964 to implicit use of the 'position' function as well (e.g., 965 '//chapter[42]'). A server is only required to maintain the relative 966 XML document order of all instances of a particular user-ordered list 967 or leaf-list. The 'position' and 'last' functions MAY be used if 968 they are evaluated in a context where the context node is a user- 969 ordered 'list' or 'leaf-list'. 971 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 972 present in YANG documents so this function has no meaning. The YANG 973 compiler SHOULD return an empty string for this function. 975 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 976 Expanded names in XPath are different than YANG. A specific 977 canonical representation of a YANG expanded name does not exist. 979 The 'lang' function SHOULD NOT be used. This function does not apply 980 to YANG because there is no 'lang' attribute set with the document. 981 The YANG compiler SHOULD return 'false' for this function. 983 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 984 functions SHOULD NOT be used if the argument is a node-set. If so, 985 the function result will be determined by the document order of the 986 node-set. Since this order can be different on each server, the 987 function results can also be different. Any function call that 988 implicitly converts a node-set to a string will also have this issue. 990 The 'local-name' function SHOULD NOT be used to reference local names 991 outside of the YANG module defining the must or when expression 992 containing the 'local-name' function. Example of a local-name 993 function that should not be used: 995 /*[local-name()='foo'] 997 The 'derived-from-or-self' function SHOULD be used instead of an 998 equality expression for identityref values. This allows the 999 identities to be conceptually augmented. 1001 Example: 1003 // do not use 1004 when "md-name-format = 'name-format-null'"; 1006 // this is preferred 1007 when "derived-from-or-self(md-name-format, 'name-format-null')"; 1009 4.6.3. Axes 1011 The 'attribute' and 'namespace' axes are not supported in YANG, and 1012 MAY be empty in a NETCONF or RESTCONF server implementation. 1014 The 'preceding', and 'following' axes SHOULD NOT be used. These 1015 constructs rely on XML document order within a NETCONF or RESTCONF 1016 server configuration database, which may not be supported 1017 consistently or produce reliable results across implementations. 1018 Predicate expressions based on static node properties (e.g., element 1019 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 1020 instead. The 'preceding' and 'following' axes MAY be used if 1021 document order is not relevant to the outcome of the expression 1022 (e.g., check for global uniqueness of a parameter value). 1024 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 1025 however they MAY be used if document order is not relevant to the 1026 outcome of the expression. 1028 A server is only required to maintain the relative XML document order 1029 of all instances of a particular user-ordered list or leaf-list. The 1030 'preceding-sibling' and 'following-sibling' axes MAY be used if they 1031 are evaluated in a context where the context node is a user-ordered 1032 'list' or 'leaf-list'. 1034 4.6.4. Types 1036 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 1037 be used within numeric or boolean expressions. There are boundary 1038 conditions in which the translation from the YANG 64-bit type to an 1039 XPath number can cause incorrect results. Specifically, an XPath 1040 'double' precision floating point number cannot represent very large 1041 positive or negative 64-bit numbers because it only provides a total 1042 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 1043 used in numeric expressions if the value can be represented with no 1044 more than 53 bits of precision. 1046 Data modelers need to be careful not to confuse the YANG value space 1047 and the XPath value space. The data types are not the same in both, 1048 and conversion between YANG and XPath data types SHOULD be considered 1049 carefully. 1051 Explicit XPath data type conversions MAY be used (e.g., 'string', 1052 'boolean', or 'number' functions), instead of implicit XPath data 1053 type conversions. 1055 XPath expressions that contain a literal value representing a YANG 1056 identity SHOULD always include the declared prefix of the module 1057 where the identity is defined. 1059 XPath expressions for 'when' statements SHOULD NOT reference the 1060 context node or any descendant nodes of the context node. They MAY 1061 reference descendant nodes if the 'when' statement is contained 1062 within an 'augment' statement, and the referenced nodes are not 1063 defined within the 'augment' statement. 1065 Example: 1067 augment "/rt:active-route/rt:input/rt:destination-address" { 1068 when "rt:address-family='v4ur:ipv4-unicast'" { 1069 description 1070 "This augment is valid only for IPv4 unicast."; 1071 } 1072 // nodes defined here within the augment-stmt 1073 // cannot be referenced in the when-stmt 1074 } 1076 4.6.5. Wildcards 1078 It is possible to construct XPath expressions that will evaluate 1079 differently when combined with several modules within a server 1080 implementation, then when evaluated within the single module. This 1081 is due to augmenting nodes from other modules. 1083 Wildcard expansion is done within a server against all the nodes from 1084 all namespaces, so it is possible for a 'must' or 'when' expression 1085 that uses the '*' operator will always evaluate to false if processed 1086 within a single YANG module. In such cases, the 'description' 1087 statement SHOULD clarify that augmenting objects are expected to 1088 match the wildcard expansion. 1090 when /foo/services/*/active { 1091 description 1092 "No services directly defined in this module. 1093 Matches objects that have augmented the services container."; 1094 } 1096 4.6.6. Boolean Expressions 1098 The YANG "must" and "when" statements use an XPath boolean expression 1099 to define the test condition for the statement. It is important to 1100 specify these expressions in a way that will not cause inadvertent 1101 changes in the result if the objects referenced in the expression are 1102 updated in future revisions of the module. 1104 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 1105 to "one" or "three": 1107 leaf foo1 { 1108 type enumeration { 1109 enum one; 1110 enum two; 1111 enum three; 1112 } 1113 } 1115 leaf foo2 { 1116 // INCORRECT 1117 must "/f:foo1 != 'two'"; 1118 type string; 1119 } 1121 leaf foo2 { 1122 // CORRECT 1123 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 1124 type string; 1125 } 1127 In the next revision of the module, leaf "foo1" is extended with a 1128 new enum named "four": 1130 leaf foo1 { 1131 type enumeration { 1132 enum one; 1133 enum two; 1134 enum three; 1135 enum four; 1136 } 1137 } 1139 Now the first XPath expression will allow the enum "four" to be 1140 accepted in addition to the "one" and "three" enum values. 1142 4.7. YANG Definition Lifecycle Management 1144 The YANG status statement MUST be present within a definition if its 1145 value is 'deprecated' or 'obsolete'. The status SHOULD NOT be 1146 changed from 'current' directly to 'obsolete'. An object SHOULD be 1147 available for at least one year with 'deprecated' status before it is 1148 changed to 'obsolete'. 1150 The module or submodule name MUST NOT be changed, once the document 1151 containing the module or submodule is published. 1153 The module namespace URI value MUST NOT be changed, once the document 1154 containing the module is published. 1156 The revision-date substatement within the import statement SHOULD be 1157 present if any groupings are used from the external module. 1159 The revision-date substatement within the include statement SHOULD be 1160 present if any groupings are used from the external submodule. 1162 If an import statement is for a module from a stable source (e.g., an 1163 RFC for an IETF module), then a reference-stmt SHOULD be present 1164 within an import statement. 1166 import ietf-yang-types { 1167 prefix yang; 1168 reference "RFC 6991: Common YANG Data Types"; 1169 } 1171 If submodules are used, then the document containing the main module 1172 MUST be updated so that the main module revision date is equal or 1173 more recent than the revision date of any submodule that is (directly 1174 or indirectly) included by the main module. 1176 Definitions for future use SHOULD NOT be specified in a module. Do 1177 not specify placeholder objects like the "reserved" example below: 1179 leaf reserved { 1180 type string; 1181 description 1182 "This object has no purpose at this time, but a future 1183 revision of this module might define a purpose 1184 for this object."; 1185 } 1186 } 1188 4.8. Module Header, Meta, and Revision Statements 1190 For published modules, the namespace MUST be a globally unique URI, 1191 as defined in [RFC3986]. This value is usually assigned by the IANA. 1193 The organization statement MUST be present. If the module is 1194 contained in a document intended for IETF Standards Track status, 1195 then the organization SHOULD be the IETF working group chartered to 1196 write the document. For other standards organizations, a similar 1197 approach is also suggested. 1199 The contact statement MUST be present. If the module is contained in 1200 a document intended for Standards Track status, then the working 1201 group web and mailing information SHOULD be present, and the main 1202 document author or editor contact information SHOULD be present. If 1203 additional authors or editors exist, their contact information MAY be 1204 present. There is no need to include the contact information for 1205 Working Group chairs. 1207 The description statement MUST be present. For modules published 1208 within IETF documents, the appropriate IETF Trust Copyright text MUST 1209 be present, as described in Section 3.1. 1211 If the module relies on information contained in other documents, 1212 which are not the same documents implied by the import statements 1213 present in the module, then these documents MUST be identified in the 1214 reference statement. 1216 A revision statement MUST be present for each published version of 1217 the module. The revision statement MUST have a reference 1218 substatement. It MUST identify the published document that contains 1219 the module. Modules are often extracted from their original 1220 documents, and it is useful for developers and operators to know how 1221 to find the original source document in a consistent manner. The 1222 revision statement MAY have a description substatement. 1224 The following example shows the revision statement for a published 1225 YANG module: 1227 revision "2012-02-22" { 1228 description 1229 "Initial version"; 1230 reference 1231 "RFC 6536: Network Configuration Protocol (NETCONF) 1232 Access Control Model"; 1233 } 1235 For an unpublished module, a complete history of each unpublished 1236 module revision is not required. That is, within a sequence of draft 1237 versions, only the most recent revision need be recorded in the 1238 module. Do not remove or reuse a revision statement for a published 1239 module. A new revision date is not required unless the module 1240 contents have changed. If the module contents have changed, then the 1241 revision date of that new module version MUST be updated to a date 1242 later than that of the previous version. 1244 The following example shows the two revision statements for an 1245 unpublished update to a published YANG module: 1247 revision "2017-12-11" { 1248 description 1249 "Added support for YANG 1.1 actions and notifications tied to 1250 data nodes. Clarify how NACM extensions can be used by other 1251 data models."; 1252 reference 1253 "RFC XXXX: Network Configuration Protocol (NETCONF) 1254 Access Control Model"; 1255 } 1257 revision "2012-02-22" { 1258 description 1259 "Initial version"; 1260 reference 1261 "RFC 6536: Network Configuration Protocol (NETCONF) 1262 Access Control Model"; 1263 } 1265 4.9. Namespace Assignments 1267 It is RECOMMENDED that only valid YANG modules be included in 1268 documents, whether or not the modules are published yet. This 1269 allows: 1271 o the module to compile correctly instead of generating disruptive 1272 fatal errors. 1274 o early implementors to use the modules without picking a random 1275 value for the XML namespace. 1277 o early interoperability testing since independent implementations 1278 will use the same XML namespace value. 1280 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1281 provided for the namespace statement in a YANG module. A value 1282 SHOULD be selected that is not likely to collide with other YANG 1283 namespaces. Standard module names, prefixes, and URI strings already 1284 listed in the YANG Module Registry MUST NOT be used. 1286 A standard namespace statement value SHOULD have the following form: 1288 : 1290 The following URN prefix string SHOULD be used for published and 1291 unpublished YANG modules: 1293 urn:ietf:params:xml:ns:yang: 1295 The following example URNs would be valid namespace statement values 1296 for Standards Track modules: 1298 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1300 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1302 urn:ietf:params:xml:ns:yang:ietf-netconf 1304 Note that a different URN prefix string SHOULD be used for non- 1305 Standards-Track modules. The string SHOULD be selected according to 1306 the guidelines in [RFC7950]. 1308 The following URIs exemplify what might be used by non Standards 1309 Track modules. Note that the domain "example.com" SHOULD be used by 1310 example modules in IETF drafts. These URIs are not intended to be 1311 de-referenced. They are used for module namespace identification 1312 only. 1314 Example URIs using URLs per RFC 3986 [RFC3986]: 1316 https://example.com/ns/example-interfaces 1318 https://example.com/ns/example-system 1320 Example URIs using tags per RFC 4151 [RFC4151]: 1322 tag:example.com,2017:example-interfaces 1324 tag:example.com,2017:example-system 1326 4.10. Top-Level Data Definitions 1328 The top-level data organization SHOULD be considered carefully, in 1329 advance. Data model designers need to consider how the functionality 1330 for a given protocol or protocol family will grow over time. 1332 The separation of configuration data and operational state SHOULD be 1333 considered carefully. It is sometimes useful to define separate top- 1334 level containers for configuration and non-configuration data. For 1335 some existing top-level data nodes, configuration data was not in 1336 scope, so only one container representing operational state was 1337 created. Refer to the Network Management Datastore Architecture 1338 (NMDA) [I-D.ietf-netmod-revised-datastores] for details. 1340 The number of top-level data nodes within a module SHOULD be 1341 minimized. It is often useful to retrieve related information within 1342 a single subtree. If data is too distributed, is becomes difficult 1343 to retrieve all at once. 1345 The names and data organization SHOULD reflect persistent 1346 information, such as the name of a protocol. The name of the working 1347 group SHOULD NOT be used because this may change over time. 1349 A mandatory database data definition is defined as a node that a 1350 client must provide for the database to be valid. The server is not 1351 required to provide a value. 1353 Top-level database data definitions MUST NOT be mandatory. If a 1354 mandatory node appears at the top level, it will immediately cause 1355 the database to be invalid. This can occur when the server boots or 1356 when a module is loaded dynamically at runtime. 1358 4.11. Data Types 1360 Selection of an appropriate data type (i.e., built-in type, existing 1361 derived type, or new derived type) is very subjective, and therefore 1362 few requirements can be specified on that subject. 1364 Data model designers SHOULD use the most appropriate built-in data 1365 type for the particular application. 1367 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1368 'int64') SHOULD NOT be used unless negative values are allowed for 1369 the desired semantics. 1371 4.11.1. Fixed Value Extensibility 1373 If the set of values is fixed and the data type contents are 1374 controlled by a single naming authority, then an enumeration data 1375 type SHOULD be used. 1377 leaf foo { 1378 type enumeration { 1379 enum one; 1380 enum two; 1381 } 1382 } 1384 If extensibility of enumerated values is required, then the 1385 'identityref' data type SHOULD be used instead of an enumeration or 1386 other built-in type. 1388 identity foo-type { 1389 description "Base for the extensible type"; 1390 } 1392 identity one { 1393 base f:foo-type; 1394 } 1395 identity two { 1396 base f:foo-type; 1397 } 1399 leaf foo { 1400 type identityref { 1401 base f:foo-type; 1402 } 1403 } 1405 Note that any module can declare an identity with base "foo-type" 1406 that is valid for the "foo" leaf. Identityref values are considered 1407 to be qualified names. 1409 4.11.2. Patterns and Ranges 1411 For string data types, if a machine-readable pattern can be defined 1412 for the desired semantics, then one or more pattern statements SHOULD 1413 be present. A single quoted string SHOULD be used to specify the 1414 pattern, since a double-quoted string can modify the content. If the 1415 patterns used in a type definition have known limitations such as 1416 false negative or false positive matches, then these limitations 1417 SHOULD be documented within the typedef or data definition. 1419 The following typedef from [RFC6991] demonstrates the proper use of 1420 the "pattern" statement: 1422 typedef ipv4-address-no-zone { 1423 type inet:ipv4-address { 1424 pattern '[0-9\.]*'; 1425 } 1426 ... 1427 } 1429 For string data types, if the length of the string is required to be 1430 bounded in all implementations, then a length statement MUST be 1431 present. 1433 The following typedef from [RFC6991] demonstrates the proper use of 1434 the "length" statement: 1436 typedef yang-identifier { 1437 type string { 1438 length "1..max"; 1439 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1440 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1441 } 1442 ... 1443 } 1445 For numeric data types, if the values allowed by the intended 1446 semantics are different than those allowed by the unbounded intrinsic 1447 data type (e.g., 'int32'), then a range statement SHOULD be present. 1449 The following typedef from [RFC6991] demonstrates the proper use of 1450 the "range" statement: 1452 typedef dscp { 1453 type uint8 { 1454 range "0..63"; 1455 } 1456 ... 1457 } 1459 4.11.3. Enumerations and Bits 1461 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1462 or 'bit' SHOULD be documented. A separate description statement 1463 (within each 'enum' or 'bit' statement) SHOULD be present. 1465 leaf foo { 1466 // INCORRECT 1467 type enumeration { 1468 enum one; 1469 enum two; 1470 } 1471 description 1472 "The foo enum... 1473 one: The first enum 1474 two: The second enum"; 1475 } 1477 leaf foo { 1478 // CORRECT 1479 type enumeration { 1480 enum one { 1481 description "The first enum"; 1482 } 1483 enum two { 1484 description "The second enum"; 1485 } 1486 } 1487 description 1488 "The foo enum... "; 1489 } 1491 4.11.4. Union Types 1493 The YANG "union" type is evaluated by testing a value against each 1494 member type in the union. The first type definition that accepts a 1495 value as valid is the member type used. In general, member types 1496 SHOULD be ordered from most restrictive to least restrictive types. 1498 In the following example, the "enumeration" type will never be 1499 matched because the preceding "string" type will match everything. 1501 Incorrect: 1503 type union { 1504 type string; 1505 type enumeration { 1506 enum up; 1507 enum down; 1508 } 1509 } 1511 Correct: 1513 type union { 1514 type enumeration { 1515 enum up; 1516 enum down; 1517 } 1518 type string; 1519 } 1521 It is possible for different member types to match, depending on the 1522 input encoding format. In XML, all values are passed as string 1523 nodes, but in JSON there are different value types for numbers, 1524 booleans, and strings. 1526 In the following example, a JSON numeric value will always be matched 1527 by the "int32" type but in XML the string value representing a number 1528 will be matched by the "string" type. The second version will match 1529 the "int32" member type no matter how the input is encoded. 1531 Incorrect: 1533 type union { 1534 type string; 1535 type int32; 1536 } 1538 Correct: 1540 type union { 1541 type int32; 1542 type string; 1543 } 1545 4.11.5. Empty and Boolean 1547 YANG provides an "empty" data type, which has one value (i.e., 1548 present). The default is "not present", which is not actually a 1549 value. When used within a list key, only one value can (and must) 1550 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1551 key leaf since it is pointless. 1553 There is really no difference between a leaf of type "empty" and a 1554 leaf-list of type "empty". Both are limited to one instance. The 1555 type "empty" SHOULD NOT be used for a leaf-list. 1557 The advantage of using type "empty" instead of type "boolean" is that 1558 the default (not present) does not take up any bytes in a 1559 representation. The disadvantage is that the client may not be sure 1560 if an empty leaf is missing because it was filtered somehow or not 1561 implemented. The client may not have a complete and accurate schema 1562 for the data returned by the server, and not be aware of the missing 1563 leaf. 1565 The YANG "boolean" data type provides two values ("true" and 1566 "false"). When used within a list key, two entries can exist for 1567 this key leaf. Default values are ignored for key leafs, but a 1568 default statement is often used for plain boolean leafs. The 1569 advantage of the "boolean" type is that the leaf or leaf-list has a 1570 clear representation for both values. The default value is usually 1571 not returned unless explicitly requested by the client, so no bytes 1572 are used in a typical representation. 1574 In general, the "boolean" data type SHOULD be used instead of the 1575 "empty" data type, as shown in the example below: 1577 Incorrect: 1579 leaf flag1 { 1580 type empty; 1581 } 1583 Correct: 1585 leaf flag2 { 1586 type boolean; 1587 default false; 1588 } 1590 4.12. Reusable Type Definitions 1592 If an appropriate derived type exists in any standard module, such as 1593 [RFC6991], then it SHOULD be used instead of defining a new derived 1594 type. 1596 If an appropriate units identifier can be associated with the desired 1597 semantics, then a units statement SHOULD be present. 1599 If an appropriate default value can be associated with the desired 1600 semantics, then a default statement SHOULD be present. 1602 If a significant number of derived types are defined, and it is 1603 anticipated that these data types will be reused by multiple modules, 1604 then these derived types SHOULD be contained in a separate module or 1605 submodule, to allow easier reuse without unnecessary coupling. 1607 The description statement MUST be present. 1609 If the type definition semantics are defined in an external document 1610 (other than another YANG module indicated by an import statement), 1611 then the reference statement MUST be present. 1613 4.13. Reusable Groupings 1615 A reusable grouping is a YANG grouping that can be imported by 1616 another module, and is intended for use by other modules. This is 1617 not the same as a grouping that is used within the module it is 1618 defined, but happens to be exportable to another module because it is 1619 defined at the top-level of the YANG module. 1621 The following guidelines apply to reusable groupings, in order to 1622 make them as robust as possible: 1624 o Clearly identify the purpose of the grouping in the "description" 1625 statement. 1627 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1628 output, notification, config=true data nodes, and all data nodes). 1629 Clearly identify which XPath contexts are applicable or excluded 1630 for the grouping. 1632 o Do not reference data outside the grouping in any "path", "must", 1633 or "when" statements. 1635 o Do not include a "default" sub-statement on a leaf or choice 1636 unless the value applies on all possible contexts. 1638 o Do not include a "config" sub-statement on a data node unless the 1639 value applies on all possible contexts. 1641 o Clearly identify any external dependencies in the grouping 1642 "description" statement, such as nodes referenced by absolute path 1643 from a "path", "must", or "when" statement. 1645 4.14. Data Definitions 1647 The description statement MUST be present in the following YANG 1648 statements: 1650 o anyxml 1652 o augment 1654 o choice 1655 o container 1657 o extension 1659 o feature 1661 o grouping 1663 o identity 1665 o leaf 1667 o leaf-list 1669 o list 1671 o notification 1673 o rpc 1675 o typedef 1677 If the data definition semantics are defined in an external document, 1678 (other than another YANG module indicated by an import statement), 1679 then a reference statement MUST be present. 1681 The 'anyxml' construct may be useful to represent an HTML banner 1682 containing markup elements, such as '<b>' and '</b>', and 1683 MAY be used in such cases. However, this construct SHOULD NOT be 1684 used if other YANG data node types can be used instead to represent 1685 the desired syntax and semantics. 1687 It has been found that the 'anyxml' statement is not implemented 1688 consistently across all servers. It is possible that mixed mode XML 1689 will not be supported, or configuration anyxml nodes will not 1690 supported. 1692 If there are referential integrity constraints associated with the 1693 desired semantics that can be represented with XPath, then one or 1694 more 'must' statements SHOULD be present. 1696 For list and leaf-list data definitions, if the number of possible 1697 instances is required to be bounded for all implementations, then the 1698 max-elements statements SHOULD be present. 1700 If any 'must' or 'when' statements are used within the data 1701 definition, then the data definition description statement SHOULD 1702 describe the purpose of each one. 1704 The "choice" statement is allowed to be directly present within a 1705 "case" statement in YANG 1.1. This needs to be considered carefully. 1706 Consider simply including the nested "choice" as additional "case" 1707 statements within the parent "choice" statement. Note that the 1708 "mandatory" and "default" statements within a nested "choice" 1709 statement only apply if the "case" containing the nested "choice" 1710 statement is first selected. 1712 If a list defines any key leafs, then these leafs SHOULD be defined 1713 in order, as the first child nodes within the list. The key leafs 1714 MAY be in a different order in some cases, e.g., they are defined in 1715 a grouping, not inline in the list statement. 1717 4.14.1. Non-Presence Containers 1719 A non-presence container is used to organize data into specific 1720 subtrees. It is not intended to have semantics within the data model 1721 beyond this purpose, although YANG allows it (e.g., "must" statement 1722 within the non-presence container). 1724 Example using container wrappers: 1726 container top { 1727 container foos { 1728 list foo { ... } 1729 } 1730 container bars { 1731 list bar { ... } 1732 } 1733 } 1735 Example without container wrappers: 1737 container top { 1738 list foo { ... } 1739 list bar { ... } 1740 } 1742 Use of non-presence containers to organize data is a subjective 1743 matter similar to use of sub-directories in a file system. Although 1744 these containers do not have any semantics, they can impact protocol 1745 operations for the descendant data nodes within a non-presence 1746 container, so use of these containers SHOULD be considered carefully. 1748 The NETCONF and RESTCONF protocols do not currently support the 1749 ability to delete all list (or leaf-list) entries at once. This 1750 deficiency is sometimes avoided by use of a parent container (i.e., 1751 deleting the container also removes all child entries). 1753 4.14.2. Top-Level Data Nodes 1755 Use of top-level objects needs to be considered carefully: 1757 o top-level siblings are not ordered 1759 o top-level siblings not are not static, and depends on the modules 1760 that are loaded 1762 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1763 treated as a content-match node for all top-level-siblings 1765 o a top-level list with many instances may impact performance 1767 4.15. Operation Definitions 1769 If the operation semantics are defined in an external document (other 1770 than another YANG module indicated by an import statement), then a 1771 reference statement MUST be present. 1773 If the operation impacts system behavior in some way, it SHOULD be 1774 mentioned in the description statement. 1776 If the operation is potentially harmful to system behavior in some 1777 way, it MUST be mentioned in the Security Considerations section of 1778 the document. 1780 4.16. Notification Definitions 1782 The description statement MUST be present. 1784 If the notification semantics are defined in an external document 1785 (other than another YANG module indicated by an import statement), 1786 then a reference statement MUST be present. 1788 If the notification refers to a specific resource instance, then this 1789 instance SHOULD be identified in the notification data. This is 1790 usually done by including 'leafref' leaf nodes with the key leaf 1791 values for the resource instance. For example: 1793 notification interface-up { 1794 description "Sent when an interface is activated."; 1795 leaf name { 1796 type leafref { 1797 path "/if:interfaces/if:interface/if:name"; 1798 } 1799 } 1800 } 1802 Note that there are no formal YANG statements to identify any data 1803 node resources associated with a notification. The description 1804 statement for the notification SHOULD specify if and how the 1805 notification identifies any data node resources associated with the 1806 specific event. 1808 4.17. Feature Definitions 1810 The YANG "feature" statement is used to define a label for a set of 1811 optional functionality within a module. The "if-feature" statement 1812 is used in the YANG statements associated with a feature. The 1813 description-stmt within a feature-stmt MUST specify any interactions 1814 with other features. 1816 The set of YANG features defined in a module should be considered 1817 carefully. Very fine granular features increase interoperability 1818 complexity and should be avoided. A likely misuse of the feature 1819 mechanism is the tagging of individual leafs (e.g., counters) with 1820 separate features. 1822 If there is a large set of objects associated with a YANG feature, 1823 then consider moving those objects to a separate module, instead of 1824 using a YANG feature. Note that the set of features within a module 1825 is easily discovered by the reader, but the set of related modules 1826 within the entire YANG library is not as easy to identity. Module 1827 names with a common prefix can help readers identity the set of 1828 related modules, but this assumes the reader will have discovered and 1829 installed all the relevant modules. 1831 Another consideration for deciding whether to create a new module or 1832 add a YANG feature is the stability of the module in question. It 1833 may be desirable to have a stable base module that is not changed 1834 frequently. If new functionality is placed in a separate module, 1835 then the base module does not need to be republished. If it is 1836 designed as a YANG feature then the module will need to be 1837 republished. 1839 If one feature requires implementation of another feature, then an 1840 "if-feature" statement SHOULD be used in the dependent "feature" 1841 statement. 1843 For example, feature2 requires implementation of feature1: 1845 feature feature1 { 1846 description "Some protocol feature"; 1847 } 1849 feature feature2 { 1850 if-feature "feature1"; 1851 description "Another protocol feature"; 1852 } 1854 4.18. YANG Data Node Constraints 1856 4.18.1. Controlling Quantity 1858 The "min-elements" and "max-elements" statements can be use to 1859 control how many list or leaf-list instances are required for a 1860 particular data node. YANG constraint statements SHOULD be used to 1861 identify conditions that apply to all implementations of the data 1862 model. If platform-specific limitations (e.g., the "max-elements" 1863 supported for a particular list) are relevant to operations, then a 1864 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1865 used to identify the limit. 1867 4.18.2. must vs. when 1869 The "must" and "when" YANG statements are used to provide cross- 1870 object referential tests. They have very different behavior. The 1871 "when" statement causes data node instances to be silently deleted as 1872 soon as the condition becomes false. A false "when" expression is 1873 not considered to be an error. 1875 The "when" statement SHOULD be used together with the "augment" or 1876 "uses" statements to achieve conditional model composition. The 1877 condition SHOULD be based on static properties of the augmented entry 1878 (e.g., list key leafs). 1880 The "must" statement causes a datastore validation error if the 1881 condition is false. This statement SHOULD be used for enforcing 1882 parameter value restrictions that involve more than one data node 1883 (e.g., end-time parameter must be after the start-time parameter). 1885 4.19. Augment Statements 1887 The YANG "augment" statement is used to define a set of data 1888 definition statements that will be added as child nodes of a target 1889 data node. The module namespace for these data nodes will be the 1890 augmenting module, not the augmented module. 1892 A top-level "augment" statement SHOULD NOT be used if the target data 1893 node is in the same module or submodule as the evaluated "augment" 1894 statement. The data definition statements SHOULD be added inline 1895 instead. 1897 4.19.1. Conditional Augment Statements 1899 The "augment" statement is often used together with the "when" 1900 statement and/or "if-feature" statement to make the augmentation 1901 conditional on some portion of the data model. 1903 The following example from [RFC7223] shows how a conditional 1904 container called "ethernet" is added to the "interface" list only for 1905 entries of the type "ethernetCsmacd". 1907 augment "/if:interfaces/if:interface" { 1908 when "if:type = 'ianaift:ethernetCsmacd'"; 1910 container ethernet { 1911 leaf duplex { 1912 ... 1913 } 1914 } 1915 } 1917 4.19.2. Conditionally Mandatory Data Definition Statements 1919 YANG has very specific rules about how configuration data can be 1920 updated in new releases of a module. These rules allow an "old 1921 client" to continue interoperating with a "new server". 1923 If data nodes are added to an existing entry, the old client MUST NOT 1924 be required to provide any mandatory parameters that were not in the 1925 original module definition. 1927 It is possible to add conditional augment statements such that the 1928 old client would not know about the new condition, and would not 1929 specify the new condition. The conditional augment statement can 1930 contain mandatory objects only if the condition is false unless 1931 explicitly requested by the client. 1933 Only a conditional augment statement that uses the "when" statement 1934 form of condition can be used in this manner. The YANG features 1935 enabled on the server cannot be controlled by the client in any way, 1936 so it is not safe to add mandatory augmenting data nodes based on the 1937 "if-feature" statement. 1939 The XPath "when" statement condition MUST NOT reference data outside 1940 of target data node because the client does not have any control over 1941 this external data. 1943 In the following dummy example, it is OK to augment the "interface" 1944 entry with "mandatory-leaf" because the augmentation depends on 1945 support for "some-new-iftype". The old client does not know about 1946 this type so it would never select this type, and therefore not be 1947 adding a mandatory data node. 1949 module example-module { 1950 namespace "tag:example.com,2017:example-module"; 1951 prefix mymod; 1953 import iana-if-type { prefix iana; } 1954 import ietf-interfaces { prefix if; } 1956 identity some-new-iftype { 1957 base iana:iana-interface-type; 1958 } 1960 augment "/if:interfaces/if:interface" { 1961 when "if:type = 'mymod:some-new-iftype'"; 1963 leaf mandatory-leaf { 1964 mandatory true; 1965 ... 1966 } 1967 } 1968 } 1970 Note that this practice is safe only for creating data resources. It 1971 is not safe for replacing or modifying resources if the client does 1972 not know about the new condition. The YANG data model MUST be 1973 packaged in a way that requires the client to be aware of the 1974 mandatory data nodes if it is aware of the condition for this data. 1975 In the example above, the "some-new-iftype" identity is defined in 1976 the same module as the "mandatory-leaf" data definition statement. 1978 This practice is not safe for identities defined in a common module 1979 such as "iana-if-type" because the client is not required to know 1980 about "my-module" just because it knows about the "iana-if-type" 1981 module. 1983 4.20. Deviation Statements 1985 Per RFC 7950, 7.20.3, the YANG "deviation" statement is not allowed 1986 to appear in IETF YANG modules, but it can be useful for documenting 1987 server capabilities. Deviation statements are not reusable and 1988 typically not shared across all platforms. 1990 There are several reasons that deviations might be needed in an 1991 implementation, e.g., an object cannot be supported on all platforms, 1992 or feature delivery is done in multiple development phases. 1993 Deviation statements can also be used to add annotations to a module, 1994 which does not affect the conformance requirements for the module. 1996 It is suggested that deviation statements be defined in separate 1997 modules from regular YANG definitions. This allows the deviations to 1998 be platform-specific and/or temporary. 2000 The order that deviation statements are evaluated can affect the 2001 result. Therefore multiple deviation statements in the same module, 2002 for the same target object, SHOULD NOT be used. 2004 The "max-elements" statement is intended to describe an architectural 2005 limit to the number of list entries. It is not intended to describe 2006 platform limitations. It is better to use a "deviation" statement 2007 for the platforms that have a hard resource limit. 2009 Example documenting platform resource limits: 2011 Wrong: (max-elements in the list itself) 2013 container backups { 2014 list backup { 2015 ... 2016 max-elements 10; 2017 ... 2018 } 2019 } 2021 Correct: (max-elements in a deviation) 2023 deviation /bk:backups/bk:backup { 2024 deviate add { 2025 max-elements 10; 2026 } 2027 } 2029 4.21. Extension Statements 2031 The YANG "extension" statement is used to specify external 2032 definitions. This appears in the YANG syntax as an 2033 "unknown-statement". Usage of extension statements in a published 2034 module needs to be considered carefully. 2036 The following guidelines apply to the usage of YANG extensions: 2038 o The semantics of the extension MUST NOT contradict any YANG 2039 statements. Extensions can add semantics not covered by the 2040 normal YANG statements. 2042 o The module containing the extension statement MUST clearly 2043 identify the conformance requirements for the extension. It 2044 should be clear whether all implementations of the YANG module 2045 containing the extension need to also implement the extension. If 2046 not, identify what conditions apply that would require 2047 implementation of the extension. 2049 o The extension MUST clearly identify where it can be used within 2050 other YANG statements. 2052 o The extension MUST clearly identify if YANG statements or other 2053 extensions are allowed or required within the extension as sub- 2054 statements. 2056 4.22. Data Correlation 2058 Data can be correlated in various ways, using common data types, 2059 common data naming, and common data organization. There are several 2060 ways to extend the functionality of a module, based on the degree of 2061 coupling between the old and new functionality: 2063 o inline: update the module with new protocol-accessible objects. 2064 The naming and data organization of the original objects is used. 2065 The new objects are in the original module namespace. 2067 o augment: create a new module with new protocol-accessible objects 2068 that augment the original data structure. The naming and data 2069 organization of the original objects is used. The new objects are 2070 in the new module namespace. 2072 o mirror: create new objects in a new module or the original module, 2073 except use new a naming scheme and data location. The naming can 2074 be coupled in different ways. Tight coupling is achieved with a 2075 "leafref" data type, with the "require-instance" sub-statement set 2076 to "true". This method SHOULD be used. 2078 If the new data instances are not limited to the values in use in the 2079 original data structure, then the "require-instance" sub-statement 2080 MUST be set to "false". Loose coupling is achieved by using key 2081 leafs with the same data type as the original data structure. This 2082 has the same semantics as setting the "require-instance" sub- 2083 statement to "false". 2085 The relationship between configuration and operational state has been 2086 clarified in NMDA [I-D.ietf-netmod-revised-datastores]. 2088 4.22.1. Use of Leafref for Key Correlation 2090 Sometimes it is not practical to augment a data structure. For 2091 example, the correlated data could have different keys or contain 2092 mandatory nodes. 2094 The following example shows the use of the "leafref" data type for 2095 data correlation purposes: 2097 Not preferred: 2099 list foo { 2100 key name; 2101 leaf name { 2102 type string; 2103 } 2104 ... 2105 } 2107 list foo-addon { 2108 key name; 2109 config false; 2110 leaf name { 2111 type string; 2112 } 2113 ... 2114 } 2116 Preferred: 2118 list foo { 2119 key name; 2120 leaf name { 2121 type string; 2122 } 2123 ... 2124 } 2126 list foo-addon { 2127 key name; 2128 config false; 2129 leaf name { 2130 type leafref { 2131 path "/foo/name"; 2132 require-instance false; 2133 } 2134 } 2135 leaf addon { 2136 type string; 2137 mandatory true; 2138 } 2139 } 2141 4.23. Operational State 2143 The modeling of operational state with YANG has been refined over 2144 time. At first, only data that has a "config" statement value of 2145 "false" was considered to be operational state. This data was not 2146 considered to be part of any datastore, which made YANG XPath 2147 definition much more complicated. 2149 Operational state is now modeled using YANG according to the new NMDA 2150 [I-D.ietf-netmod-revised-datastores], and is now conceptually 2151 contained in the operational state datastore, which also includes the 2152 operational values of configuration data. There is no longer any 2153 need to duplicate data structures to provide separate configuration 2154 and operational state sections. 2156 This section describes some data modeling issues related to 2157 operational state, and guidelines for transitioning YANG data model 2158 design to be NMDA-compatible. 2160 4.23.1. Combining Operational State and Configuration Data 2162 If possible, operational state SHOULD be combined with its associated 2163 configuration data. This prevents duplication of key leafs and 2164 ancestor nodes. It also prevents race conditions for retrieval of 2165 dynamic entries, and allows configuration and operational state to be 2166 retrieved together with minimal message overhead. 2168 container foo { 2169 ... 2170 // contains config=true and config=false nodes that have 2171 // no corresponding config=true object (e.g., counters) 2172 } 2174 4.23.2. Representing Operational Values of Configuration Data 2176 If possible the same data type SHOULD be used to represent the 2177 configured value and the operational value, for a given leaf or leaf- 2178 list object. 2180 Sometimes the configured value set is different than the operational 2181 value set for that object. For example, the "admin-state" and 2182 "oper-state" leafs in [RFC7223]. In this case a separate object MAY 2183 be used to represent the configured and operational values. 2185 Sometimes the list keys are not identical for configuration data and 2186 the corresponding operational state. In this case separate lists MAY 2187 be used to represent the configured and operational values. 2189 If it is not possible to combine configuration and operational state, 2190 then the keys used to represent list entries SHOULD be the same type. 2191 The "leafref" data type SHOULD be used in operational state for key 2192 leafs that have corresponding configuration instances. The 2193 "require-instance" statement MAY be set to "false" (in YANG 1.1 2194 modules only) to indicate instances are allowed in the operational 2195 state that do not exist in the associated configuration data. 2197 The need to replicate objects or define different operational state 2198 objects depends on the data model. It is not possible to define one 2199 approach that will be optimal for all data models. 2201 Designers SHOULD describe and justify any NMDA exceptions in detail, 2202 such as the use of separate subtrees and/or separate leafs. The 2203 "description" statements for both the configuration and the 2204 operational state SHOULD be used for this purpose. 2206 4.23.3. NMDA Transition Guidelines 2208 YANG modules SHOULD be designed assuming they will be used on servers 2209 supporting the operational state datastore. With this in mind, YANG 2210 modules SHOULD define config "false" wherever they make sense to the 2211 data model. Config "false" nodes SHOULD NOT be defined to provide 2212 the operational value for configuration nodes, except when the value 2213 space of a configured and operational values may differ, in which 2214 case a distinct config "false" node SHOULD be defined to hold the 2215 operational value for the configured node. 2217 The following guidelines are meant to help modelers develop YANG 2218 modules that will maximize the utility of the model with both current 2219 and new implementations. 2221 New modules and modules that are not concerned with the operational 2222 state of configuration information SHOULD immediately be structured 2223 to be NMDA-compatible, as described in Section 4.23.1. This 2224 transition MAY be deferred if the module does not contain any 2225 configuration datastore objects. 2227 The remaining are options that MAY be followed during the time that 2228 NMDA mechanisms are being defined. 2230 (a) Modules that require immediate support for the NMDA features 2231 SHOULD be structured for NMDA. A temporary non-NMDA version of this 2232 type of module MAY exist, either an existing model or a model created 2233 either by hand or with suitable tools that mirror the current 2234 modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 2235 be published in the same document, with NMDA modules in the document 2236 main body and the non-NMDA modules in a non-normative appendix. The 2237 use of the non-NMDA module will allow temporary bridging of the time 2238 period until NMDA implementations are available. 2240 (b) For published models, the model should be republished with an 2241 NMDA-compatible structure, deprecating non-NMDA constructs. For 2242 example, the "ietf-interfaces" model in [RFC7223] has been 2243 restructured as an NMDA-compatible model in 2244 [I-D.ietf-netmod-rfc7223bis]. The "/interfaces-state" hierarchy has 2245 been marked "status deprecated". Models that mark their "/foo-state" 2246 hierarchy with "status deprecated" will allow NMDA-capable 2247 implementations to avoid the cost of duplicating the state nodes, 2248 while enabling non-NMDA-capable implementations to utilize them for 2249 access to the operational values. 2251 (c) For models that augment models which have not been structured 2252 with the NMDA, the modeler will have to consider the structure of the 2253 base model and the guidelines listed above. Where possible, such 2254 models should move to new revisions of the base model that are NMDA- 2255 compatible. When that is not possible, augmenting "state" containers 2256 SHOULD be avoided, with the expectation that the base model will be 2257 re-released with the state containers marked as deprecated. It is 2258 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 2259 Where this recommendation cannot be followed, then any new "state" 2260 elements SHOULD be included in their own module. 2262 4.23.3.1. Temporary non-NMDA Modules 2264 A temporary non-NMDA module allows a non-NMDA aware client to access 2265 operational state from an NMDA-compliant server. It contains the 2266 top-level config=false data nodes that would have been defined in a 2267 legacy YANG module (before NMDA). 2269 A server that needs to support both NMDA and non-NMDA clients can 2270 advertise both the new NMDA module and the temporary non-NMDA module. 2271 A non-NMDA client can use separate "foo" and "foo-state" subtrees, 2272 except the "foo-state" subtree is located in a different (temporary) 2273 module. The NMDA module can be used by a non-NMDA client to access 2274 the conventional configuration datastores, and the deprecated 2275 operation to access nested config=false data nodes. 2277 To create the temporary non-NMDA model from an NMDA model, the 2278 following steps can be taken: 2280 o Change the module name by appending "-state" to the original 2281 module name 2283 o Change the namespace by appending "-state" to the original 2284 namespace value 2286 o Change the prefix by appending "-s" to the original prefix value 2288 o Add an import to the original module (e.g., for typedef 2289 definitions) 2291 o Retain or create only the top-level nodes that have a "config" 2292 statement value "false". These subtrees represent config=false 2293 data nodes that were combined into the configuration subtree, and 2294 therefore not available to non-NMDA aware clients. Set the 2295 "status" statement to "deprecated" for each new node. 2297 o The module description SHOULD clearly identify the module as a 2298 temporary non-NMDA module 2300 4.23.3.2. Example: Create a New NMDA Module 2302 Create an NMDA-compliant module, using combined configuration and 2303 state subtrees, whenever possible. 2305 module example-foo { 2306 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2307 prefix "foo"; 2309 container foo { 2310 // configuration data child nodes 2311 // operational value in operational state datastore only 2312 // may contain config=false nodes as needed 2313 } 2314 } 2316 4.23.3.3. Example: Convert an old Non-NMDA Module 2318 Do not remove non-compliant objects from existing modules. Instead, 2319 change the status to "deprecated". At some point, usually after 1 2320 year, the status MAY be changed to "obsolete". 2322 Old Module: 2324 module example-foo { 2325 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2326 prefix "foo"; 2328 container foo { 2329 // configuration data child nodes 2330 } 2332 container foo-state { 2333 config false; 2334 // operational state child nodes 2335 } 2336 } 2338 Converted NMDA Module: 2340 module example-foo { 2341 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2342 prefix "foo"; 2344 container foo { 2345 // configuration data child nodes 2346 // operational value in operational state datastore only 2347 // may contain config=false nodes as needed 2348 // will contain any data nodes from old foo-state 2349 } 2351 // keep original foo-state but change status to deprecated 2352 container foo-state { 2353 config false; 2354 status deprecated; 2355 // operational state child nodes 2356 } 2357 } 2359 4.23.3.4. Example: Create a Temporary NMDA Module: 2361 Create a new module that contains the top-level operational state 2362 data nodes that would have been available before they were combined 2363 with configuration data nodes (to be NMDA compliant). 2365 module example-foo-state { 2366 namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; 2367 prefix "foo-s"; 2369 // import new or converted module; not used in this example 2370 import example-foo { prefix foo; } 2372 container foo-state { 2373 config false; 2374 status deprecated; 2375 // operational state child nodes 2376 } 2377 } 2379 4.24. Performance Considerations 2381 It is generally likely that certain YANG statements require more 2382 runtime resources than other statements. Although there are no 2383 performance requirements for YANG validation, the following 2384 information MAY be considered when designing YANG data models: 2386 o Lists are generally more expensive than containers 2388 o "when-stmt" evaluation is generally more expensive than 2389 "if-feature" or "choice" statements 2391 o "must" statement is generally more expensive than "min-entries", 2392 "max-entries", "mandatory", or "unique" statements 2394 o "identityref" leafs are generally more expensive than 2395 "enumeration" leafs 2397 o "leafref" and "instance-identifier" types with "require-instance" 2398 set to true are generally more expensive than if 2399 "require-instance" is set to false 2401 4.25. Open Systems Considerations 2403 Only the modules imported by a particular module can be assumed to be 2404 present in an implementation. An open system MAY include any 2405 combination of YANG modules. 2407 4.26. Guidelines for YANG 1.1 Specific Constructs 2409 The set of YANG 1.1 guidelines will grow as operational experience is 2410 gained with the new language features. This section contains an 2411 initial set of guidelines for new YANG 1.1 language features. 2413 4.26.1. Importing Multiple Revisions 2415 Standard modules SHOULD NOT import multiple revisions of the same 2416 module into a module. This MAY be done if independent definitions 2417 (e.g. enumeration typedefs) from specific revisions are needed in the 2418 importing module. 2420 4.26.2. Using Feature Logic 2422 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2423 "description" statement SHOULD describe the "if-feature" logic in 2424 text, to help readers understand the module. 2426 YANG features SHOULD be used instead of the "when" statement, if 2427 possible. Features are advertised by the server and objects 2428 conditional by if-feature are conceptually grouped together. There 2429 is no such commonality supported for "when" statements. 2431 Features generally require less server implementation complexity and 2432 runtime resources than objects that use "when" statements. Features 2433 are generally static (i.e., set when module is loaded and not changed 2434 at runtime). However every client edit might cause a "when" 2435 statement result to change. 2437 4.26.3. anyxml vs. anydata 2439 The "anyxml" statement MUST NOT be used to represent a conceptual 2440 subtree of YANG data nodes. The "anydata" statement MUST be used for 2441 this purpose. 2443 4.26.4. action vs. rpc 2445 The use of "action" statements or "rpc" statements is a subjective 2446 design decision. RPC operations are not associated with any 2447 particular data node. Actions are associated with a specific data 2448 node definition. An "action" statement SHOULD be used if the 2449 protocol operation is specific to a subset of all data nodes instead 2450 of all possible data nodes. 2452 The same action name MAY be used in different definitions within 2453 different data node. For example, a "reset" action defined with a 2454 data node definition for an interface might have different parameters 2455 than for a power supply or a VLAN. The same action name SHOULD be 2456 used to represent similar semantics. 2458 The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis] 2459 does not support parameter-based access control for RPC operations. 2460 The user is given permission (or not) to invoke the RPC operation 2461 with any parameters. For example, if each client is only allowed to 2462 reset their own interface, then NACM cannot be used. 2464 For example, NACM cannot enforce access access control based on the 2465 value of the "interface" parameter, only the "reset" operation 2466 itself: 2468 rpc reset { 2469 input { 2470 leaf interface { 2471 type if:interface-ref; 2472 mandatory true; 2473 description "The interface to reset."; 2474 } 2475 } 2476 } 2478 However, NACM can enforce access access control for individual 2479 interface instances, using a "reset" action, If the user does not 2480 have read access to the specific "interface" instance, then it cannot 2481 invoke the "reset" action for that interface instance: 2483 container interfaces { 2484 list interface { 2485 ... 2486 action reset { } 2487 } 2488 } 2490 4.27. Updating YANG Modules (Published vs. Unpublished) 2492 YANG modules can change over time. Typically, new data model 2493 definitions are needed to support new features. YANG update rules 2494 defined in section 11 of [RFC7950] MUST be followed for published 2495 modules. They MAY be followed for unpublished modules. 2497 The YANG update rules only apply to published module revisions. Each 2498 organization will have their own way to identify published work which 2499 is considered to be stable, and unpublished work which is considered 2500 to be unstable. For example, in the IETF, the RFC document is used 2501 for published work, and the Internet-Draft is used for unpublished 2502 work. 2504 5. IANA Considerations 2506 -- RFC Ed: These registries need to be updated to reference this 2507 RFC instead of RFC 6087 for the ietf-template module, and 2508 remove this note. 2510 This document registers one URI in the IETF XML registry [RFC3688]. 2512 The following registration has been made in [RFC6087] and updated by 2513 this document. 2515 URI: urn:ietf:params:xml:ns:yang:ietf-template 2517 Registrant Contact: The IESG. 2519 XML: N/A, the requested URI is an XML namespace. 2521 The following assignment has been made in [RFC6087] and updated by 2522 this document in the YANG Module Names Registry, or the YANG module 2523 template in Appendix C. 2525 +-----------+-------------------------------------------+ 2526 | Field | Value | 2527 +-----------+-------------------------------------------+ 2528 | Name | ietf-template | 2529 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2530 | Prefix | temp | 2531 | Reference | RFC XXXX | 2532 +-----------+-------------------------------------------+ 2534 YANG Registry Assignment 2536 6. Security Considerations 2538 This document defines documentation guidelines for NETCONF or 2539 RESTCONF content defined with the YANG data modeling language, and 2540 therefore does not introduce any new or increased security risks into 2541 the management system. 2543 7. Acknowledgments 2545 The structure and contents of this document are adapted from 2546 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2548 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2549 Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive 2550 reviews and contributions to this document. 2552 8. References 2554 8.1. Normative References 2556 [I-D.ietf-netmod-revised-datastores] 2557 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2558 and R. Wilton, "Network Management Datastore 2559 Architecture", draft-ietf-netmod-revised-datastores-10 2560 (work in progress), January 2018. 2562 [ID-Guidelines] 2563 Housley, R., Ed., "Guidelines to Authors of Internet- 2564 Drafts", December 2010, 2565 . 2567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2568 Requirement Levels", BCP 14, RFC 2119, March 1997. 2570 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2571 January 2004. 2573 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2574 Resource Identifier (URI): Generic Syntax", STD 66, 2575 RFC 3986, January 2005. 2577 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2578 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 2579 RFC5246, August 2008, 2580 . 2582 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2583 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2585 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2586 Network Configuration Protocol (NETCONF)", RFC 6020, 2587 October 2010. 2589 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2590 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2591 . 2593 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2594 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2595 May 2017, . 2597 [W3C.REC-xpath-19991116] 2598 Clark, J. and S. DeRose, "XML Path Language (XPath) 2599 Version 1.0", World Wide Web Consortium 2600 Recommendation REC-xpath-19991116, November 1999, 2601 . 2603 8.2. Informative References 2605 [I-D.flanagan-7322bis] 2606 Flanagan, H. and R. Editor, "RFC Style Guide", 2607 draft-flanagan-7322bis-02 (work in progress), 2608 September 2017. 2610 [I-D.ietf-netconf-rfc6536bis] 2611 Bierman, A. and M. Bjorklund, "Network Configuration 2612 Access Control Module", draft-ietf-netconf-rfc6536bis-09 2613 (work in progress), December 2017. 2615 [I-D.ietf-netmod-rfc7223bis] 2616 Bjorklund, M., "A YANG Data Model for Interface 2617 Management", draft-ietf-netmod-rfc7223bis-03 (work in 2618 progress), January 2018. 2620 [I-D.ietf-netmod-rfc8022bis] 2621 Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 2622 Routing Management (NMDA Version)", 2623 draft-ietf-netmod-rfc8022bis-11 (work in progress), 2624 January 2018. 2626 [I-D.ietf-netmod-yang-tree-diagrams] 2627 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2628 draft-ietf-netmod-yang-tree-diagrams-06 (work in 2629 progress), February 2018. 2631 [RFC-STYLE] 2632 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2633 Style", September 2009, 2634 . 2636 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2637 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2638 . 2640 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2641 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2642 . 2644 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2645 Documents", BCP 111, RFC 4181, September 2005. 2647 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2648 Data Model Documents", RFC 6087, January 2011. 2650 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2651 and A. Bierman, Ed., "Network Configuration Protocol 2652 (NETCONF)", RFC 6241, June 2011. 2654 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2655 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2656 . 2658 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2659 Protocol (NETCONF) Access Control Model", RFC 6536, 2660 March 2012. 2662 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2663 July 2013. 2665 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2666 Management", RFC 7223, May 2014. 2668 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2669 DOI 10.17487/RFC7322, September 2014, 2670 . 2672 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2673 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2674 DOI 10.17487/RFC7841, May 2016, 2675 . 2677 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2678 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2679 . 2681 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2682 Writing an IANA Considerations Section in RFCs", BCP 26, 2683 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2684 . 2686 Appendix A. Change Log 2688 -- RFC Ed.: remove this section before publication. 2690 A.1. v19 to v20 2692 o fix examples 2694 A.2. v18 to v19 2696 o address IESG ballot comments 2698 A.3. v17 to v18 2700 o address Area Director review comments Part 2 2702 o clarify preferred list key order 2704 A.4. v16 to v17 2706 o address Area Director review comments Part 1 2708 A.5. v15 to v16 2710 o address Area Director review comments posted 2018-01-25 2712 A.6. v15 to v16 2714 o address document shephard comments posted 2018-01-15 2716 o add yang-version to template module 2718 A.7. v14 to v15 2720 o changed Intended status from Informational to BCP 2722 o update tree diagram guidelines section 2724 o Change IANA template to list IESG instead of NETMOD WG as the 2725 Registrant 2727 o Update some references 2729 A.8. v13 to v14 2731 o Replaced sec. 4.23 Operational Data with Operational Data from 2732 NMDA text by Lou Berger and Kent Watsen 2734 o Added NMDA Terms section 2736 o Changed term operational data to operational state 2738 o Clarified that reference-stmt SHOULD be present in import-stmt 2740 A.9. v12 to v13 2742 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2743 YANG file extraction macro. 2745 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2746 module name registries. 2748 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2750 o Update Operation Data section to consider revised datastores. 2752 o Add reference to YANG Tree Diagrams and update 2 sections that use 2753 this reference. 2755 o Add reference to Revised Datastores and guidelines drafts 2757 A.10. v11 to v12 2759 o fix incorrect location of new Module Usage Examples section 2761 A.11. v10 to v11 2763 o updated YANG tree diagram syntax to align with pyang 1.7.1 2765 o added general guideline to include module usage examples 2767 A.12. v09 to v10 2769 o clarified is only for normative modules 2771 o clarified example module namespace URI conventions 2773 o clarified pyang usage for normative and example modules 2775 o updated YANG tree diagrams section with text from RFC 8022 2777 A.13. v08 to v09 2779 o fixed references 2780 o added mention of RESTCONF to abstract and intro 2782 o created separate section for code components 2784 o fixed document status 2786 A.14. v07 to v08 2788 o changed CODE BEGINS guideline for example modules 2790 o updated tree diagram guidelines 2792 o clarified published and unpublished terms 2794 o added section on Empty and Boolean data types 2796 o clarified how to update the revision statement 2798 o updated operational state guidelines 2800 o added 'YANG fragment' to terminology section 2802 A.15. v06 to v07 2804 o update contact statement guideline 2806 o update example modules guidelines 2808 o add guidelines on top-level data nodes 2810 o add guideline on use of NP containers 2812 o added guidelines on union types 2814 o add guideline on deviations 2816 o added section on open systems considerations 2818 o added guideline about definitions reserved for future use 2820 A.16. v05 to v06 2822 o Changed example 'my-module' to 'example-module' 2824 o Added section Updating YANG Modules (Published vs. Unpublished) 2826 o Added Example Modules section 2827 o Added "" convention for full example modules 2829 o Added section on using action vs. rpc 2831 o Changed term "operational state" to "operational data" 2833 o Added section on YANG Data Node Constraints 2835 o Added guidelines on using must vs. when statements 2837 o Made ietf-foo module validate for I-D submission 2839 A.17. v04 to v05 2841 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2842 no YANG 1.1 features needed 2844 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2845 standards track documents only) 2847 o Clarified module naming conventions for normative modules, example 2848 modules, and modules from other SDOs. 2850 o Added prefix value selection guidelines 2852 o Added new section on guidelines for reusable groupings 2854 o Made header guidelines less IETF-specific 2856 o Added new section on guidelines for extension statements 2858 o Added guidelines for nested "choice" statement within a "case" 2859 statement 2861 A.18. v03 ot v04 2863 o Added sections for deviation statements and performance 2864 considerations 2866 o Added YANG 1.1 section 2868 o Updated YANG reference from 1.0 to 1.1 2870 A.19. v02 to v03 2872 o Updated draft based on github data tracker issues added by Benoit 2873 Clause (Issues 12 - 18) 2875 A.20. v01 to v02 2877 o Updated draft based on mailing list comments. 2879 A.21. v00 to v01 2881 All issues from the issue tracker have been addressed. 2883 https://github.com/netmod-wg/rfc6087bis/issues 2885 o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with 2886 YANG modules can use an Informative reference to this RFC for tree 2887 diagrams. Updated guidelines to reference this RFC when tree 2888 diagrams are used 2890 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2891 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2892 functions 2894 o Issue 3: XPath function document order issues: Added paragraph in 2895 XPath usage section about node-set ordering for 'local-name', 2896 'namespace-uri', 'name', 'string' and 'number' functions. Also 2897 any function that implicitly converts a node-set to a string. 2899 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2900 and text in XPath usage section already has proposed text from 2901 Lada. 2903 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2904 exception and example in XPath Usage section for augmented nodes. 2906 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2907 to 'numeric and boolean expressions' 2909 o Issue 7: XPath module containment: Added sub-section on XPath 2910 wildcards 2912 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2913 section about transitioning from active to deprecated and then to 2914 obsolete. 2916 o Issue 9: resource identification in notifications: Add text to 2917 Notifications section about identifying resources and using the 2918 leafref data type. 2920 o Issue 10: single quoted strings: Added text to Data Types section 2921 about using a single-quoted string for patterns. 2923 Appendix B. Module Review Checklist 2925 This section is adapted from RFC 4181. 2927 The purpose of a YANG module review is to review the YANG module both 2928 for technical correctness and for adherence to IETF documentation 2929 requirements. The following checklist may be helpful when reviewing 2930 an Internet-Draft: 2932 o I-D Boilerplate -- verify that the draft contains the required 2933 Internet-Draft boilerplate (see 2934 https://www.ietf.org/id-info/guidelines.html), including the 2935 appropriate statement to permit publication as an RFC, and that 2936 I-D boilerplate does not contain references or section numbers. 2938 o Abstract -- verify that the abstract does not contain references, 2939 that it does not have a section number, and that its content 2940 follows the guidelines in 2941 https://www.ietf.org/id-info/guidelines.html. 2943 o Copyright Notice -- verify that the draft has the appropriate text 2944 regarding the rights that document contributers provide to the 2945 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2946 copyright notice at the beginning of the document. The IETF Trust 2947 Legal Provisions (TLP) can be found at: 2949 https://trustee.ietf.org/license-info/ 2951 o Security Considerations section -- verify that the draft uses the 2952 latest approved template from the OPS area website (https:// 2953 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2954 and that the guidelines therein have been followed. 2956 o IANA Considerations section -- this section must always be 2957 present. For each module within the document, ensure that the 2958 IANA Considerations section contains entries for the following 2959 IANA registries: 2961 XML Namespace Registry: Register the YANG module namespace. 2963 YANG Module Registry: Register the YANG module name, prefix, 2964 namespace, and RFC number, according to the rules specified 2965 in [RFC6020]. 2967 o References -- verify that the references are properly divided 2968 between normative and informative references, that RFC 2119 and 2969 RFC 8174 are included as normative references if the terminology 2970 defined therein is used in the document, that all references 2971 required by the boilerplate are present, that all YANG modules 2972 containing imported items are cited as normative references, and 2973 that all citations point to the most current RFCs unless there is 2974 a valid reason to do otherwise (for example, it is OK to include 2975 an informative reference to a previous version of a specification 2976 to help explain a feature included for backward compatibility). 2977 Be sure citations for all imported modules are present somewhere 2978 in the document text (outside the YANG module). If a YANG module 2979 contains reference or description statements that refer to an 2980 Internet Draft (I-D), then the I-D is included as an Informative 2981 Reference. 2983 o License -- verify that the draft contains the Simplified BSD 2984 License in each YANG module or submodule. Some guidelines related 2985 to this requirement are described in Section 3.1. Make sure that 2986 the correct year is used in all copyright dates. Use the approved 2987 text from the latest Trust Legal Provisions (TLP) document, which 2988 can be found at: 2990 https://trustee.ietf.org/license-info/ 2992 o Other Issues -- check for any issues mentioned in 2993 https://www.ietf.org/id-info/checklist.html that are not covered 2994 elsewhere. 2996 o Technical Content -- review the actual technical content for 2997 compliance with the guidelines in this document. The use of a 2998 YANG module compiler is recommended when checking for syntax 2999 errors. A list of freely available tools and other information 3000 can be found at: 3002 https://trac.tools.ietf.org/wg/netconf/trac/wiki 3004 Checking for correct syntax, however, is only part of the job. 3005 It is just as important to actually read the YANG module document 3006 from the point of view of a potential implementor. It is 3007 particularly important to check that description statements are 3008 sufficiently clear and unambiguous to allow interoperable 3009 implementations to be created. 3011 Appendix C. YANG Module Template 3013 file "ietf-template@2016-03-20.yang" 3015 module ietf-template { 3017 yang-version 1.1; 3019 // replace this string with a unique namespace URN value 3020 namespace 3021 "urn:ietf:params:xml:ns:yang:ietf-template"; 3023 // replace this string, and try to pick a unique prefix 3024 prefix "temp"; 3026 // import statements here: e.g., 3027 // import ietf-yang-types { prefix yang; } 3028 // import ietf-inet-types { prefix inet; } 3030 // identify the IETF working group if applicable 3031 organization 3032 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 3034 // update this contact statement with your info 3035 contact 3036 "WG Web: 3037 WG List: 3039 Editor: your-name 3040 "; 3042 // replace the first sentence in this description statement. 3043 // replace the copyright notice with the most recent 3044 // version, if it has been updated since the publication 3045 // of this document 3046 description 3047 "This module defines a template for other YANG modules. 3049 Copyright (c) IETF Trust and the persons 3050 identified as authors of the code. All rights reserved. 3052 Redistribution and use in source and binary forms, with or 3053 without modification, is permitted pursuant to, and subject 3054 to the license terms contained in, the Simplified BSD License 3055 set forth in Section 4.c of the IETF Trust's Legal Provisions 3056 Relating to IETF Documents 3057 (http://trustee.ietf.org/license-info). 3058 This version of this YANG module is part of RFC XXXX; see 3059 the RFC itself for full legal notices."; 3061 // RFC Ed.: replace XXXX with actual RFC number and remove 3062 // this note 3064 reference "RFC XXXX: "; 3066 // RFC Ed.: remove this note 3067 // Note: extracted from RFC XXXX 3069 // replace '2016-03-20' with the module publication date 3070 // The format is (year-month-day) 3071 revision "2016-03-20" { 3072 description "what changed in this revision"; 3073 reference "document containing this module"; 3074 } 3076 // extension statements 3078 // feature statements 3080 // identity statements 3082 // typedef statements 3084 // grouping statements 3086 // data definition statements 3088 // augment statements 3090 // rpc statements 3092 // notification statements 3094 // DO NOT put deviation statements in a published module 3096 } 3098 3100 Author's Address 3102 Andy Bierman 3103 YumaWorks 3105 Email: andy@yumaworks.com