idnits 2.17.1 draft-ietf-netmod-rfc6087bis-18.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 (February 20, 2018) is 2257 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 2521, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- 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 (~~), 3 warnings (==), 5 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) February 20, 2018 5 Intended status: BCP 6 Expires: August 24, 2018 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-18 11 Abstract 13 This memo provides guidelines for authors and reviewers of Standards 14 Track specifications containing YANG data model modules. Applicable 15 portions may be used as a basis for reviews of other YANG data model 16 documents. Recommendations and procedures are defined, which are 17 intended to increase interoperability and usability of Network 18 Configuration Protocol (NETCONF) and RESTCONF protocol 19 implementations that utilize YANG data model modules. This document 20 obsoletes RFC 6087. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 24, 2018. 39 Copyright Notice 41 Copyright (c) 2018 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8 60 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8 61 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 63 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 3. General Documentation Guidelines . . . . . . . . . . . . . . . 10 65 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10 66 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 10 67 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11 68 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11 69 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 70 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 71 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 72 3.7. Security Considerations Section . . . . . . . . . . . . . 13 73 3.7.1. Security Considerations Section Template . . . . . . . 13 74 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 15 75 3.8.1. Documents that Create a New Namespace . . . . . . . . 15 76 3.8.2. Documents that Extend an Existing Namespace . . . . . 15 77 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15 78 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 79 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16 80 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 17 81 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 18 82 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 18 83 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 19 84 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 20 86 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 21 87 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 21 88 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 22 89 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 22 90 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 23 91 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 24 93 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 25 94 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 26 95 4.7. YANG Definition Lifecycle Management . . . . . . . . . . . 27 96 4.8. Module Header, Meta, and Revision Statements . . . . . . . 28 97 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 29 98 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 30 99 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 31 100 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 31 101 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 32 102 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 33 103 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 33 104 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 34 105 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 35 106 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 36 107 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 37 108 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 38 109 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 39 110 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 39 111 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 39 112 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 40 113 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 41 114 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 41 115 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 41 116 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 41 117 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 42 118 4.19.2. Conditionally Mandatory Data Definition Statements . . 42 119 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 44 120 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45 121 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 45 122 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 46 123 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47 124 4.23.1. Combining Operational State and Configuration Data . . 47 125 4.23.2. Representing Operational Values of Configuration 126 Data . . . . . . . . . . . . . . . . . . . . . . . . . 48 127 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 48 128 4.24. Performance Considerations . . . . . . . . . . . . . . . . 52 129 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 53 130 4.26. Guidelines for YANG 1.1 Specific Constructs . . . . . . . 53 131 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 53 132 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 53 133 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 54 134 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 54 135 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 55 136 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 137 6. Security Considerations . . . . . . . . . . . . . . . . . . . 57 138 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58 139 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 140 8.1. Normative References . . . . . . . . . . . . . . . . . . . 59 141 8.2. Informative References . . . . . . . . . . . . . . . . . . 59 142 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 62 143 A.1. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 62 144 A.2. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 62 145 A.3. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 146 A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 147 A.5. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 62 148 A.6. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 62 149 A.7. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 63 150 A.8. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 63 151 A.9. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 63 152 A.10. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 63 153 A.11. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 63 154 A.12. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 64 155 A.13. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 64 156 A.14. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 64 157 A.15. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 65 158 A.16. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 65 159 A.17. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 65 160 A.18. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 65 161 A.19. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 66 162 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 67 163 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 69 164 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71 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 Standards Track 175 documents containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data 176 models. YANG is used to define the data structures, protocol 177 operations, and notification content used within a NETCONF and/or 178 RESTCONF server. A NETCONF or RESTCONF server that supports a 179 particular YANG module will support client NETCONF and/or RESTCONF 180 operation requests, as indicated by the specific content defined in 181 the YANG module. 183 Many YANG constructs are defined as optional to use, such as the 184 description statement. However, in order to make YANG modules more 185 useful, it is desirable to define a set of usage guidelines that 186 entails a higher level of compliance than the minimum level defined 187 in the YANG specification. 189 In addition, YANG allows constructs such as infinite length 190 identifiers and string values, or top-level mandatory nodes, that a 191 compliant server is not required to support. Only constructs that 192 all servers are required to support can be used in IETF YANG modules. 194 This document defines usage guidelines related to the NETCONF 195 operations layer and NETCONF content layer, as defined in [RFC6241], 196 and the RESTCONF methods and RESTCONF resources, as defined in 197 [RFC8040], 199 These guidelines are intended to be used by authors and reviewers to 200 improve the readability and interoperability of published YANG data 201 models. 203 Note that this document is not a YANG tutorial and the reader is 204 expected to know the YANG data modeling language before using this 205 document. 207 1.1. Changes Since RFC 6087 209 The following changes have been made to the guidelines published in 210 [RFC6087]: 212 o Updated NETCONF reference from RFC 4741 to RFC 6241 214 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 216 o Updated YANG Types reference from RFC 6021 to RFC 6991 218 o Updated obsolete URLs for IETF resources 220 o Changed top-level data node guideline 222 o Clarified XPath usage for a literal value representing a YANG 223 identity 225 o Clarified XPath usage for a when-stmt 227 o Clarified XPath usage for 'proceeding-sibling' and 228 'following-sibling' axes 230 o Added terminology guidelines 232 o Added YANG tree diagram guidelines 234 o Updated XPath guidelines for type conversions and function library 235 usage. 237 o Updated data types section 239 o Updated notifications section 241 o Clarified conditional key leaf nodes 243 o Clarify usage of 'uint64' and 'int64' data types 245 o Added text on YANG feature usage 247 o Added Identifier Naming Conventions 249 o Clarified use of mandatory nodes with conditional augmentations 251 o Clarified namespace and domain conventions for example modules 253 o Clarified conventions for identifying code components 255 o Added YANG 1.1 guidelines 257 o Added Data Model Constraints section 258 o Added mention of RESTCONF protocol 260 o Added guidelines for NMDA Revised Datastores 262 2. Terminology 264 2.1. Requirements Notation 266 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 267 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 268 document are to be interpreted as described in BCP 14 [RFC2119] 269 [RFC8174] when, and only when, they appear in all capitals, as shown 270 here. 272 RFC 2119 language is used here to express the views of the NETMOD 273 working group regarding content for YANG modules. YANG modules 274 complying with this document will treat the RFC 2119 terminology as 275 if it were describing best current practices. 277 2.2. NETCONF Terms 279 The following terms are defined in [RFC6241] and are not redefined 280 here: 282 o capabilities 284 o client 286 o operation 288 o server 290 2.3. YANG Terms 292 The following terms are defined in [RFC7950] and are not redefined 293 here: 295 o data node 297 o module 299 o namespace 301 o submodule 303 o version 305 o YANG 307 o YIN 309 Note that the term 'module' may be used as a generic term for a YANG 310 module or submodule. When describing properties that are specific to 311 submodules, the term 'submodule' is used instead. 313 2.4. NMDA Terms 315 The following terms are defined in the Network Management Datastore 316 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not 317 redefined here: 319 o configuration 321 o conventional configuration datastore 323 o datastore 325 o operational state 327 o operational state datastore 329 2.5. Terms 331 The following terms are used throughout this document: 333 o published: A stable release of a module or submodule. For example 334 the "Request for Comments" described in section 2.1 of [RFC2026] 335 is considered a stable publication. 337 o unpublished: An unstable release of a module or submodule. For 338 example the "Internet-Draft" described in section 2.2 of [RFC2026] 339 is considered an unstable publication that is a work-in-progress, 340 subject to change at any time. 342 o YANG fragment: A set of YANG statements that are not intended to 343 represent a complete YANG module or submodule. These statements 344 are not intended for actual use, except to provide an example of 345 YANG statement usage. The invalid syntax "..." is sometimes used 346 to indicate that additional YANG statements would be present in a 347 real YANG module. 349 o YANG tree diagram: a diagram representing the contents of a YANG 350 module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also 351 called a "tree diagram". 353 3. General Documentation Guidelines 355 YANG data model modules under review are likely to be contained in 356 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 357 followed. The RFC Editor provides guidelines for authors of RFCs, 358 which are first published as Internet-Drafts. These guidelines 359 should be followed and are defined in [RFC7322] and updated in 360 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 362 The following sections MUST be present in an Internet-Draft 363 containing a module: 365 o Narrative sections 367 o Definitions section 369 o Security Considerations section 371 o IANA Considerations section 373 o References section 375 There are three usage scenarios for YANG that can appear in an 376 Internet-Draft or RFC: 378 o normative module or submodule 380 o example module or submodule 382 o example YANG fragment not part of any module or submodule 384 The guidelines in this document refer mainly to a normative module or 385 submodule, but may be applicable to example modules and YANG 386 fragments as well. 388 3.1. Module Copyright 390 The module description statement MUST contain a reference to the 391 latest approved IETF Trust Copyright statement, which is available 392 online at: 394 http://trustee.ietf.org/license-info/ 396 3.2. Code Components 398 Each normative YANG module or submodule contained within an Internet- 399 Draft or RFC is considered to be a code component. The strings 400 "" and "" MUST be used to identify each code 401 component. 403 The "" tag SHOULD be followed by a string identifying 404 the file name specified in Section 5.2 of [RFC7950]. The name string 405 form that includes the revision-date SHOULD be used. The revision 406 date MUST match the date used in the most recent revision of the 407 module. 409 The following example is for the '2010-01-18' revision of the 410 'ietf-foo' module: 412 file "ietf-foo@2016-03-20.yang" 414 module ietf-foo { 415 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 416 prefix "foo"; 417 organization "..."; 418 contact "..."; 419 description "..."; 420 revision 2016-03-20 { 421 description "Latest revision"; 422 reference "RFC XXXX"; 423 } 424 // ... more statements 425 } 427 429 3.2.1. Example Modules 431 Example modules are not code components. The 432 convention MUST NOT be used for example modules. 434 An example module SHOULD be named using the term "example", followed 435 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 436 See Section 4.9 regarding the namespace guidelines for example 437 modules. 439 3.3. Terminology Section 441 A terminology section MUST be present if any terms are defined in the 442 document or if any terms are imported from other documents. 444 3.4. Tree Diagrams 446 YANG tree diagrams provide a concise representation of a YANG module, 447 and SHOULD be included to help readers understand YANG module 448 structure. Guidelines on tree diagrams can be found in Section 3 of 450 [I-D.ietf-netmod-yang-tree-diagrams]. 452 If YANG tree diagrams are used, then an informative reference to the 453 YANG tree diagrams specification MUST be included in the document. 454 Refer to Section 2.2 of [I-D.ietf-netmod-rfc8022bis] for an example 455 of such a reference. 457 3.5. Narrative Sections 459 The narrative part MUST include an overview section that describes 460 the scope and field of application of the module(s) defined by the 461 specification and that specifies the relationship (if any) of these 462 modules to other standards, particularly to standards containing 463 other YANG modules. The narrative part SHOULD include one or more 464 sections to briefly describe the structure of the modules defined in 465 the specification. 467 If the module(s) defined by the specification imports definitions 468 from other modules (except for those defined in the [RFC7950] or 469 [RFC6991] documents), or are always implemented in conjunction with 470 other modules, then those facts MUST be noted in the overview 471 section, as MUST be noted any special interpretations of definitions 472 in other modules. Refer to section 2.3 of 473 [I-D.ietf-netmod-rfc8022bis] for an example of this overview section. 475 If the documents contains YANG module(s) that are compliant with the 476 Network Management Datastore Architecture (NMDA) 477 [I-D.ietf-netmod-revised-datastores], then the Abstract and 478 Introduction sections should mention this fact. 480 Example: 482 The YANG model in this document conforms to the Network Management 483 Datastore Architecture defined in I-D.ietf-netmod-revised-datastores. 485 3.6. Definitions Section 487 This section contains the module(s) defined by the specification. 488 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 489 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 490 semantics are needed in the module. If any of the imported YANG 491 modules are written using YANG 1.1, then the module MUST be written 492 using YANG 1.1. 494 A YIN syntax version of the module MAY also be present in the 495 document. There MAY also be other types of modules present in the 496 document, such as SMIv2, which are not affected by these guidelines. 498 Note that all YANG statements within a YANG module are considered 499 normative, if the module itself is considered normative, and not an 500 example module or example YANG fragment. The use of keywords defined 501 in [RFC2119] apply to YANG description statements in normative 502 modules exactly as they would in any other normative section. 504 Example YANG modules and example YANG fragments MUST NOT contain any 505 normative text, including any reserved words from [RFC2119]. 507 See Section 4 for guidelines on YANG usage. 509 3.7. Security Considerations Section 511 Each specification that defines one or more modules MUST contain a 512 section that discusses security considerations relevant to those 513 modules. 515 This section MUST be patterned after the latest approved template 516 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 517 yang-security-guidelines). Section 3.7.1 contains the security 518 considerations template dated 2013-05-08 and last updated 2017-12-21. 519 Authors MUST check the WEB page at the URL listed above in case there 520 is a more recent version available. 522 In particular: 524 o Writable data nodes that could be especially disruptive if abused 525 MUST be explicitly listed by name and the associated security 526 risks MUST be explained. 528 o Readable data nodes that contain especially sensitive information 529 or that raise significant privacy concerns MUST be explicitly 530 listed by name and the reasons for the sensitivity/privacy 531 concerns MUST be explained. 533 o Operations (i.e., YANG 'rpc' statements) that are potentially 534 harmful to system behavior or that raise significant privacy 535 concerns MUST be explicitly listed by name and the reasons for the 536 sensitivity/privacy concerns MUST be explained. 538 3.7.1. Security Considerations Section Template 540 X. Security Considerations 542 The YANG module specified in this document defines a schema for data 543 that is designed to be accessed via network management protocols such 544 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 545 is the secure transport layer, and the mandatory-to-implement secure 546 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 547 is HTTPS, and the mandatory-to-implement secure transport is TLS 548 [RFC5246]. 550 The NETCONF access control model [RFC6536] provides the means to 551 restrict access for particular NETCONF or RESTCONF users to a 552 preconfigured subset of all available NETCONF or RESTCONF protocol 553 operations and content. 555 -- if you have any writeable data nodes (those are all the 556 -- "config true" nodes, and remember, that is the default) 557 -- describe their specific sensitivity or vulnerability. 559 There are a number of data nodes defined in this YANG module that are 560 writable/creatable/deletable (i.e., config true, which is the 561 default). These data nodes may be considered sensitive or vulnerable 562 in some network environments. Write operations (e.g., edit-config) 563 to these data nodes without proper protection can have a negative 564 effect on network operations. These are the subtrees and data nodes 565 and their sensitivity/vulnerability: 567 569 -- for all YANG modules you must evaluate whether any readable data 570 -- nodes (those are all the "config false" nodes, but also all other 571 -- nodes, because they can also be read via operations like get or 572 -- get-config) are sensitive or vulnerable (for instance, if they 573 -- might reveal customer information or violate personal privacy 574 -- laws such as those of the European Union if exposed to 575 -- unauthorized parties) 577 Some of the readable data nodes in this YANG module may be considered 578 sensitive or vulnerable in some network environments. It is thus 579 important to control read access (e.g., via get, get-config, or 580 notification) to these data nodes. These are the subtrees and data 581 nodes and their sensitivity/vulnerability: 583 585 -- if your YANG module has defined any rpc operations 586 -- describe their specific sensitivity or vulnerability. 588 Some of the RPC operations in this YANG module may be considered 589 sensitive or vulnerable in some network environments. It is thus 590 important to control access to these operations. These are the 591 operations and their sensitivity/vulnerability: 593 595 3.8. IANA Considerations Section 597 In order to comply with IESG policy as set forth in 598 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 599 is submitted to the IESG for publication MUST contain an IANA 600 Considerations section. The requirements for this section vary 601 depending on what actions are required of the IANA. If there are no 602 IANA considerations applicable to the document, then the IANA 603 Considerations section stating that there are no actions is removed 604 by the RFC Editor before publication. Refer to the guidelines in 605 [RFC8126] for more details. 607 Each normative YANG module MUST be registered in the XML namespace 608 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 609 This applies to new modules and updated modules. Examples of these 610 registrations for the "ietf-template" module can be found in 611 Section 5. 613 3.8.1. Documents that Create a New Namespace 615 If an Internet-Draft defines a new namespace that is to be 616 administered by the IANA, then the document MUST include an IANA 617 Considerations section that specifies how the namespace is to be 618 administered. 620 Specifically, if any YANG module namespace statement value contained 621 in the document is not already registered with IANA, then a new YANG 622 Namespace registry entry MUST be requested from the IANA. The 623 [RFC7950] specification includes the procedure for this purpose in 624 its IANA Considerations section. 626 3.8.2. Documents that Extend an Existing Namespace 628 It is possible to extend an existing namespace using a YANG submodule 629 that belongs to an existing module already administered by IANA. In 630 this case, the document containing the main module MUST be updated to 631 use the latest revision of the submodule. 633 3.9. Reference Sections 635 For every import or include statement that appears in a module 636 contained in the specification, which identifies a module in a 637 separate document, a corresponding normative reference to that 638 document MUST appear in the Normative References section. The 639 reference MUST correspond to the specific module version actually 640 used within the specification. 642 For every normative reference statement that appears in a module 643 contained in the specification, which identifies a separate document, 644 a corresponding normative reference to that document SHOULD appear in 645 the Normative References section. The reference SHOULD correspond to 646 the specific document version actually used within the specification. 647 If the reference statement identifies an informative reference, which 648 identifies a separate document, a corresponding informative reference 649 to that document MAY appear in the Informative References section. 651 3.10. Validation Tools 653 All modules need to be validated before submission in an Internet 654 Draft. The 'pyang' YANG compiler is freely available from github: 656 https://github.com/mbj4668/pyang 658 If the 'pyang' compiler is used to validate a normative module, then 659 the "--ietf" command line option MUST be used to identify any IETF 660 guideline issues. 662 If the 'pyang' compiler is used to validate an example module, then 663 the "--ietf" command line option MAY be used to identify any IETF 664 guideline issues. 666 The "yanglint" program is also freely available from github. 668 https://github.com/CESNET/libyang 670 This tool can be used to validate XPath statements within YANG 671 modules. 673 3.11. Module Extraction Tools 675 A version of 'rfcstrip' is available which will extract YANG modules 676 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 677 YANG module extraction is freely available: 679 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 681 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 683 can be extracted correctly. 685 The "xym" tool is freely available on github and can be used to 686 extract YANG modules from a document. 688 https://github.com/xym-tool/xym 690 3.12. Module Usage Examples 692 Each specification that defines one or more modules SHOULD contain 693 usage examples, either throughout the document or in an appendix. 694 This includes example instance document snippets in an appropriate 695 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 696 the YANG module(s). Example modules MUST be validated. Refer to 697 Section 3.10 for tools which validate YANG modules. 699 4. YANG Usage Guidelines 701 Modules in IETF Standards Track specifications MUST comply with all 702 syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the 703 exception for YANG 1.0 in Section 3.6. The guidelines in this 704 section are intended to supplement the YANG specification, which is 705 intended to define a minimum set of conformance requirements. 707 In order to promote interoperability and establish a set of practices 708 based on previous experience, the following sections establish usage 709 guidelines for specific YANG constructs. 711 Only guidelines that clarify or restrict the minimum conformance 712 requirements are included here. 714 4.1. Module Naming Conventions 716 Normative modules contained in Standards Track documents MUST be 717 named according to the guidelines in the IANA Considerations section 718 of [RFC7950]. 720 A distinctive word or acronym (e.g., protocol name or working group 721 acronym) SHOULD be used in the module name. If new definitions are 722 being defined to extend one or more existing modules, then the same 723 word or acronym should be reused, instead of creating a new one. 725 All published module names MUST be unique. For a YANG module 726 published in an RFC, this uniqueness is guaranteed by IANA. For 727 unpublished modules, the authors need to check that no other work in 728 progress is using the same module name. 730 Example modules are non-normative, and SHOULD be named with the 731 prefix "example-". 733 It is suggested that a stable prefix be selected representing the 734 entire organization. All normative YANG modules published by the 735 IETF MUST begin with the prefix "ietf-". Another standards 736 organization, such as the IEEE, might use the prefix "ieee-" for all 737 YANG modules. 739 Once a module name is published, it MUST NOT be reused, even if the 740 RFC containing the module is reclassified to 'Historic' status. A 741 module name cannot be changed in YANG, and this would be treated as a 742 a new module, not a name change. 744 4.2. Prefixes 746 All YANG definitions are scoped by the module containing the 747 definition being referenced. This allows definitions from multiple 748 modules to be used, even if the names are not unique. In the example 749 below, the identifier "foo" is used in all 3 modules: 751 module example-foo { 752 namespace "http://example.com/ns/foo"; 753 prefix f; 755 container foo; 756 } 758 module example-bar { 759 namespace "http://example.com/ns/bar"; 760 prefix b; 762 typedef foo { type uint32; } 763 } 765 module example-one { 766 namespace "http://example.com/ns/one"; 767 prefix one; 768 import example-foo { prefix f; } 769 import example-bar { prefix b; } 771 augment "/f:foo" { 772 leaf foo { type b:foo; } 773 } 774 } 776 YANG defines the following rules for prefix usage: 778 o Prefixes are never allowed for built in data types and YANG 779 keywords. 781 o A prefix MUST be used for any external statement (i.e., a 782 statement defined with the YANG "extension" statement) 784 o The proper module prefix MUST be used for all identifiers imported 785 from other modules 787 o The proper module prefix MUST be used for all identifiers included 788 from a submodule. 790 The following guidelines apply to prefix usage of the current (local) 791 module: 793 o The local module prefix SHOULD be used instead of no prefix in all 794 path expressions. 796 o The local module prefix MUST be used instead of no prefix in all 797 "default" statements for an "identityref" or "instance-identifier" 798 data type 800 o The local module prefix MAY be used for references to typedefs, 801 groupings, extensions, features, and identities defined in the 802 module. 804 Prefix values SHOULD be short, but also likely to be unique. Prefix 805 values SHOULD NOT conflict with known modules that have been 806 previously published. 808 4.3. Identifiers 810 Identifiers for all YANG identifiers in published modules MUST be 811 between 1 and 64 characters in length. These include any construct 812 specified as an 'identifier-arg-str' token in the ABNF in Section 13 813 of [RFC7950]. 815 4.3.1. Identifier Naming Conventions 817 Identifiers SHOULD follow a consistent naming pattern throughout the 818 module. Only lower-case letters, numbers, and dashes SHOULD be used 819 in identifier names. Upper-case characters and the underscore 820 character MAY be used if the identifier represents a well-known value 821 that uses these characters. 823 Identifiers SHOULD include complete words and/or well-known acronyms 824 or abbreviations. Child nodes within a container or list SHOULD NOT 825 replicate the parent identifier. YANG identifiers are hierarchical 826 and are only meant to be unique within the the set of sibling nodes 827 defined in the same module namespace. 829 It is permissible to use common identifiers such as "name" or "id" in 830 data definition statements, especially if these data nodes share a 831 common data type. 833 Identifiers SHOULD NOT carry any special semantics that identify data 834 modelling properties. Only YANG statements and YANG extension 835 statements are designed to convey machine readable data modelling 836 properties. For example, naming an object "config" or "state" does 837 not change whether it is configuration data or state data. Only 838 defined YANG statements or YANG extension statements can be used to 839 assign semantics in a machine readable format in YANG. 841 4.4. Defaults 843 In general, it is suggested that substatements containing very common 844 default values SHOULD NOT be present. The following substatements 845 are commonly used with the default value, which would make the module 846 difficult to read if used everywhere they are allowed. 848 +--------------+---------------+ 849 | Statement | Default Value | 850 +--------------+---------------+ 851 | config | true | 852 | mandatory | false | 853 | max-elements | unbounded | 854 | min-elements | 0 | 855 | ordered-by | system | 856 | status | current | 857 | yin-element | false | 858 +--------------+---------------+ 860 Statement Defaults 862 4.5. Conditional Statements 864 A module may be conceptually partitioned in several ways, using the 865 'if-feature' and/or 'when' statements. 867 Data model designers need to carefully consider all modularity 868 aspects, including the use of YANG conditional statements. 870 If a data definition is optional, depending on server support for a 871 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 872 statement SHOULD be defined. The defined "feature" statement SHOULD 873 then be used in the conditional "if-feature" statement referencing 874 the optional data definition. 876 If any notification data, or any data definition, for a non- 877 configuration data node is not mandatory, then the server may or may 878 not be required to return an instance of this data node. If any 879 conditional requirements exist for returning the data node in a 880 notification payload or retrieval request, they MUST be documented 881 somewhere. For example, a 'when' or 'if-feature' statement could 882 apply to the data node, or the conditional requirements could be 883 explained in a 'description' statement within the data node or one of 884 its ancestors (if any). 886 If any 'if-feature' statements apply to a list node, then the same 887 'if-feature' statements MUST apply to any key leaf nodes for the 888 list. There MUST NOT be any 'if-feature' statements applied to any 889 key leaf that do not also apply to the parent list node. 891 There SHOULD NOT be any 'when' statements applied to a key leaf node. 892 It is possible that a 'when' statement for an ancestor node of a key 893 leaf will have the exact node-set result as the key leaf. In such a 894 case, the 'when' statement for the key leaf is redundant and SHOULD 895 be avoided. 897 4.6. XPath Usage 899 This section describes guidelines for using the XML Path Language 900 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 902 4.6.1. XPath Evaluation Contexts 904 YANG defines 5 separate contexts for evaluation of XPath statements: 906 1) The "running" datastore: collection of all YANG configuration data 907 nodes. The document root is the conceptual container, (e.g., 908 "config" in the "edit-config" operation), which is the parent of all 909 top-level data definition statements with a "config" statement value 910 of "true". 912 2) State data + the "running" datastore: collection of all YANG data 913 nodes. The document root is the conceptual container, parent of all 914 top-level data definition statements. 916 3) Notification: an event notification document. The document root 917 is the notification element. 919 4) RPC Input: The document root is the conceptual "input" node, which 920 is the parent of all RPC input parameter definitions. 922 5) RPC Output: The document root is the conceptual "output" node, 923 which is the parent of all RPC output parameter definitions. 925 Note that these XPath contexts cannot be mixed. For example, a 926 "when" statement in a notification context cannot reference 927 configuration data. 929 notification foo { 930 leaf mtu { 931 // NOT OK because when-stmt context is this notification 932 when "/if:interfaces/if:interface[name='eth0']"; 933 type leafref { 934 // OK because path-stmt has a different context 935 path "/if:interfaces/if:interface/if:mtu"; 936 } 937 } 938 } 940 It is especially important to consider the XPath evaluation context 941 for XPath expressions defined in groupings. An XPath expression 942 defined in a grouping may not be portable, meaning it cannot be used 943 in multiple contexts and produce proper results. 945 If the XPath expressions defined in a grouping are intended for a 946 particular context, then this context SHOULD be identified in the 947 "description" statement for the grouping. 949 4.6.2. Function Library 951 The 'position' and 'last' functions SHOULD NOT be used. This applies 952 to implicit use of the 'position' function as well (e.g., 953 '//chapter[42]'). A server is only required to maintain the relative 954 XML document order of all instances of a particular user-ordered list 955 or leaf-list. The 'position' and 'last' functions MAY be used if 956 they are evaluated in a context where the context node is a user- 957 ordered 'list' or 'leaf-list'. 959 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 960 present in YANG documents so this function has no meaning. The YANG 961 compiler SHOULD return an empty string for this function. 963 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 964 Expanded names in XPath are different than YANG. A specific 965 canonical representation of a YANG expanded name does not exist. 967 The 'lang' function SHOULD NOT be used. This function does not apply 968 to YANG because there is no 'lang' attribute set with the document. 969 The YANG compiler SHOULD return 'false' for this function. 971 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 972 functions SHOULD NOT be used if the argument is a node-set. If so, 973 the function result will be determined by the document order of the 974 node-set. Since this order can be different on each server, the 975 function results can also be different. Any function call that 976 implicitly converts a node-set to a string will also have this issue. 978 The 'local-name' function SHOULD NOT be used to reference local names 979 outside of the YANG module defining the must or when expression 980 containing the 'local-name' function. Example of a local-name 981 function that should not be used: 983 /*[local-name()='foo'] 985 The 'derived-from-or-self' function SHOULD be used instead of an 986 equality expression for identityref values. This allows the 987 identities to be conceptually augmented. 989 Example: 991 // do not use 992 when "md-name-format = 'name-format-null'"; 994 // this is preferred 995 when "derived-from-or-self(md-name-format, 'name-format-null')"; 997 4.6.3. Axes 999 The 'attribute' and 'namespace' axes are not supported in YANG, and 1000 MAY be empty in a NETCONF or RESTCONF server implementation. 1002 The 'preceding', and 'following' axes SHOULD NOT be used. These 1003 constructs rely on XML document order within a NETCONF or RESTCONF 1004 server configuration database, which may not be supported 1005 consistently or produce reliable results across implementations. 1006 Predicate expressions based on static node properties (e.g., element 1007 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 1008 instead. The 'preceding' and 'following' axes MAY be used if 1009 document order is not relevant to the outcome of the expression 1010 (e.g., check for global uniqueness of a parameter value). 1012 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 1013 however they MAY be used if document order is not relevant to the 1014 outcome of the expression. 1016 A server is only required to maintain the relative XML document order 1017 of all instances of a particular user-ordered list or leaf-list. The 1018 'preceding-sibling' and 'following-sibling' axes MAY be used if they 1019 are evaluated in a context where the context node is a user-ordered 1020 'list' or 'leaf-list'. 1022 4.6.4. Types 1024 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 1025 be used within numeric or boolean expressions. There are boundary 1026 conditions in which the translation from the YANG 64-bit type to an 1027 XPath number can cause incorrect results. Specifically, an XPath 1028 'double' precision floating point number cannot represent very large 1029 positive or negative 64-bit numbers because it only provides a total 1030 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 1031 used in numeric expressions if the value can be represented with no 1032 more than 53 bits of precision. 1034 Data modelers need to be careful not to confuse the YANG value space 1035 and the XPath value space. The data types are not the same in both, 1036 and conversion between YANG and XPath data types SHOULD be considered 1037 carefully. 1039 Explicit XPath data type conversions MAY be used (e.g., 'string', 1040 'boolean', or 'number' functions), instead of implicit XPath data 1041 type conversions. 1043 XPath expressions that contain a literal value representing a YANG 1044 identity SHOULD always include the declared prefix of the module 1045 where the identity is defined. 1047 XPath expressions for 'when' statements SHOULD NOT reference the 1048 context node or any descendant nodes of the context node. They MAY 1049 reference descendant nodes if the 'when' statement is contained 1050 within an 'augment' statement, and the referenced nodes are not 1051 defined within the 'augment' statement. 1053 Example: 1055 augment "/rt:active-route/rt:input/rt:destination-address" { 1056 when "rt:address-family='v4ur:ipv4-unicast'" { 1057 description 1058 "This augment is valid only for IPv4 unicast."; 1059 } 1060 // nodes defined here within the augment-stmt 1061 // cannot be referenced in the when-stmt 1062 } 1064 4.6.5. Wildcards 1066 It is possible to construct XPath expressions that will evaluate 1067 differently when combined with several modules within a server 1068 implementation, then when evaluated within the single module. This 1069 is due to augmenting nodes from other modules. 1071 Wildcard expansion is done within a server against all the nodes from 1072 all namespaces, so it is possible for a 'must' or 'when' expression 1073 that uses the '*' operator will always evaluate to false if processed 1074 within a single YANG module. In such cases, the 'description' 1075 statement SHOULD clarify that augmenting objects are expected to 1076 match the wildcard expansion. 1078 when /foo/services/*/active { 1079 description 1080 "No services directly defined in this module. 1081 Matches objects that have augmented the services container."; 1082 } 1084 4.6.6. Boolean Expressions 1086 The YANG "must" and "when" statements use an XPath boolean expression 1087 to define the test condition for the statement. It is important to 1088 specify these expressions in a way that will not cause inadvertent 1089 changes in the result if the objects referenced in the expression are 1090 updated in future revisions of the module. 1092 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 1093 to "one" or "three": 1095 leaf foo1 { 1096 type enumeration { 1097 enum one; 1098 enum two; 1099 enum three; 1100 } 1101 } 1103 leaf foo2 { 1104 // INCORRECT 1105 must "/f:foo1 != 'two'"; 1106 type string; 1107 } 1109 leaf foo2 { 1110 // CORRECT 1111 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 1112 type string; 1113 } 1115 In the next revision of the module, leaf "foo1" is extended with a 1116 new enum named "four": 1118 leaf foo1 { 1119 type enumeration { 1120 enum one; 1121 enum two; 1122 enum three; 1123 enum four; 1124 } 1125 } 1127 Now the first XPath expression will allow the enum "four" to be 1128 accepted in addition to the "one" and "three" enum values. 1130 4.7. YANG Definition Lifecycle Management 1132 The YANG status statement MUST be present within a definition if its 1133 value is 'deprecated' or 'obsolete'. The status SHOULD NOT be 1134 changed from 'current' directly to 'obsolete'. An object SHOULD be 1135 available for at least one year with 'deprecated' status before it is 1136 changed to 'obsolete'. 1138 The module or submodule name MUST NOT be changed, once the document 1139 containing the module or submodule is published. 1141 The module namespace URI value MUST NOT be changed, once the document 1142 containing the module is published. 1144 The revision-date substatement within the import statement SHOULD be 1145 present if any groupings are used from the external module. 1147 The revision-date substatement within the include statement SHOULD be 1148 present if any groupings are used from the external submodule. 1150 If an import statement is for a module from a stable source (e.g., an 1151 RFC for an IETF module), then a reference-stmt SHOULD be present 1152 within an import statement. 1154 import ietf-yang-types { 1155 prefix yang; 1156 reference "RFC 6991"; 1157 } 1159 If submodules are used, then the document containing the main module 1160 MUST be updated so that the main module revision date is equal or 1161 more recent than the revision date of any submodule that is (directly 1162 or indirectly) included by the main module. 1164 Definitions for future use SHOULD NOT be specified in a module. Do 1165 not specify placeholder objects like the "reserved" example below: 1167 leaf reserved { 1168 type string; 1169 description 1170 "This object has no purpose at this time, but a future 1171 revision of this module might define a purpose 1172 for this object."; 1173 } 1174 } 1176 4.8. Module Header, Meta, and Revision Statements 1178 For published modules, the namespace MUST be a globally unique URI, 1179 as defined in [RFC3986]. This value is usually assigned by the IANA. 1181 The organization statement MUST be present. If the module is 1182 contained in a document intended for IETF Standards Track status, 1183 then the organization SHOULD be the IETF working group chartered to 1184 write the document. For other standards organizations, a similar 1185 approach is also suggested. 1187 The contact statement MUST be present. If the module is contained in 1188 a document intended for Standards Track status, then the working 1189 group web and mailing information MUST be present, and the main 1190 document author or editor contact information SHOULD be present. If 1191 additional authors or editors exist, their contact information MAY be 1192 present. There is no need to include the contact information for 1193 Working Group chairs. 1195 The description statement MUST be present. For modules published 1196 within IETF documents, the appropriate IETF Trust Copyright text MUST 1197 be present, as described in Section 3.1. 1199 If the module relies on information contained in other documents, 1200 which are not the same documents implied by the import statements 1201 present in the module, then these documents MUST be identified in the 1202 reference statement. 1204 A revision statement MUST be present for each published version of 1205 the module. The revision statement MUST have a reference 1206 substatement. It MUST identify the published document that contains 1207 the module. Modules are often extracted from their original 1208 documents, and it is useful for developers and operators to know how 1209 to find the original source document in a consistent manner. The 1210 revision statement MAY have a description substatement. 1212 It is not required to keep the full revision history of draft 1213 versions (e.g., modules contained within Internet-Drafts). That is, 1214 within a sequence of draft versions, only the most recent revision 1215 need be recorded in the module. However, whenever a new (i.e. 1216 changed) version is made available (e.g., via a new version of an 1217 Internet-Draft), the revision date of that new version MUST be 1218 updated to a date later than that of the previous version. 1220 4.9. Namespace Assignments 1222 It is RECOMMENDED that only valid YANG modules be included in 1223 documents, whether or not they are published yet. This allows: 1225 o the module to compile correctly instead of generating disruptive 1226 fatal errors. 1228 o early implementors to use the modules without picking a random 1229 value for the XML namespace. 1231 o early interoperability testing since independent implementations 1232 will use the same XML namespace value. 1234 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1235 provided for the namespace statement in a YANG module. A value 1236 SHOULD be selected that is not likely to collide with other YANG 1237 namespaces. Standard module names, prefixes, and URI strings already 1238 listed in the YANG Module Registry MUST NOT be used. 1240 A standard namespace statement value SHOULD have the following form: 1242 : 1244 The following URN prefix string SHOULD be used for published and 1245 unpublished YANG modules: 1247 urn:ietf:params:xml:ns:yang: 1249 The following example URNs would be valid namespace statement values 1250 for Standards Track modules: 1252 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1254 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1256 urn:ietf:params:xml:ns:yang:ietf-netconf 1258 Note that a different URN prefix string SHOULD be used for non- 1259 Standards-Track modules. The string SHOULD be selected according to 1260 the guidelines in [RFC7950]. 1262 The following URIs exemplify what might be used by non Standards 1263 Track modules. Note that the domain "example.com" SHOULD be used by 1264 example modules in IETF drafts. 1266 Example URIs using URLs per RFC 3986 [RFC3986]: 1268 http://example.com/ns/example-interfaces 1270 http://example.com/ns/example-system 1272 Example URIs using tags per RFC 4151 [RFC4151]: 1274 tag:example.com,2017:example-interfaces 1276 tag:example.com,2017:example-system 1278 4.10. Top-Level Data Definitions 1280 The top-level data organization SHOULD be considered carefully, in 1281 advance. Data model designers need to consider how the functionality 1282 for a given protocol or protocol family will grow over time. 1284 The separation of configuration data and operational state SHOULD be 1285 considered carefully. It is sometimes useful to define separate top- 1286 level containers for configuration and non-configuration data. For 1287 some existing top-level data nodes, configuration data was not in 1288 scope, so only one container representing operational state was 1289 created. Refer to the Network Management Datastore Architecture 1290 (NMDA) [I-D.ietf-netmod-revised-datastores]. for details. 1292 The number of top-level data nodes within a module SHOULD be 1293 minimized. It is often useful to retrieve related information within 1294 a single subtree. If data is too distributed, is becomes difficult 1295 to retrieve all at once. 1297 The names and data organization SHOULD reflect persistent 1298 information, such as the name of a protocol. The name of the working 1299 group SHOULD NOT be used because this may change over time. 1301 A mandatory database data definition is defined as a node that a 1302 client must provide for the database to be valid. The server is not 1303 required to provide a value. 1305 Top-level database data definitions MUST NOT be mandatory. If a 1306 mandatory node appears at the top level, it will immediately cause 1307 the database to be invalid. This can occur when the server boots or 1308 when a module is loaded dynamically at runtime. 1310 4.11. Data Types 1312 Selection of an appropriate data type (i.e., built-in type, existing 1313 derived type, or new derived type) is very subjective, and therefore 1314 few requirements can be specified on that subject. 1316 Data model designers SHOULD use the most appropriate built-in data 1317 type for the particular application. 1319 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1320 'int64') SHOULD NOT be used unless negative values are allowed for 1321 the desired semantics. 1323 4.11.1. Fixed Value Extensibility 1325 If the set of values is fixed and the data type contents are 1326 controlled by a single naming authority, then an enumeration data 1327 type SHOULD be used. 1329 leaf foo { 1330 type enumeration { 1331 enum one; 1332 enum two; 1333 } 1334 } 1336 If extensibility of enumerated values is required, then the 1337 'identityref' data type SHOULD be used instead of an enumeration or 1338 other built-in type. 1340 identity foo-type { 1341 description "Base for the extensible type"; 1342 } 1344 identity one { 1345 base f:foo-type; 1346 } 1347 identity two { 1348 base f:foo-type; 1349 } 1351 leaf foo { 1352 type identityref { 1353 base f:foo-type; 1354 } 1355 } 1357 Note that any module can declare an identity with base "foo-type" 1358 that is valid for the "foo" leaf. Identityref values are considered 1359 to be qualified names. 1361 4.11.2. Patterns and Ranges 1363 For string data types, if a machine-readable pattern can be defined 1364 for the desired semantics, then one or more pattern statements SHOULD 1365 be present. A single quoted string SHOULD be used to specify the 1366 pattern, since a double-quoted string can modify the content. 1368 The following typedef from [RFC6991] demonstrates the proper use of 1369 the "pattern" statement: 1371 typedef ipv4-address-no-zone { 1372 type inet:ipv4-address { 1373 pattern '[0-9\.]*'; 1374 } 1375 ... 1376 } 1378 For string data types, if the length of the string is required to be 1379 bounded in all implementations, then a length statement MUST be 1380 present. 1382 The following typedef from [RFC6991] demonstrates the proper use of 1383 the "length" statement: 1385 typedef yang-identifier { 1386 type string { 1387 length "1..max"; 1388 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1389 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1390 } 1391 ... 1392 } 1394 For numeric data types, if the values allowed by the intended 1395 semantics are different than those allowed by the unbounded intrinsic 1396 data type (e.g., 'int32'), then a range statement SHOULD be present. 1398 The following typedef from [RFC6991] demonstrates the proper use of 1399 the "range" statement: 1401 typedef dscp { 1402 type uint8 { 1403 range "0..63"; 1404 } 1405 ... 1407 } 1409 4.11.3. Enumerations and Bits 1411 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1412 or 'bit' SHOULD be documented. A separate description statement 1413 (within each 'enum' or 'bit' statement) SHOULD be present. 1415 leaf foo { 1416 // INCORRECT 1417 type enumeration { 1418 enum one; 1419 enum two; 1420 } 1421 description 1422 "The foo enum... 1423 one: The first enum 1424 two: The second enum"; 1425 } 1427 leaf foo { 1428 // CORRECT 1429 type enumeration { 1430 enum one { 1431 description "The first enum"; 1432 } 1433 enum two { 1434 description "The second enum"; 1435 } 1436 } 1437 description 1438 "The foo enum... "; 1439 } 1441 4.11.4. Union Types 1443 The YANG "union" type is evaluated by testing a value against each 1444 member type in the union. The first type definition that accepts a 1445 value as valid is the member type used. In general, member types 1446 SHOULD be ordered from most restrictive to least restrictive types. 1448 In the following example, the "enumeration" type will never be 1449 matched because the preceding "string" type will match everything. 1451 Incorrect: 1453 type union { 1454 type string; 1455 type enumeration { 1456 enum up; 1457 enum down; 1458 } 1459 } 1461 Correct: 1463 type union { 1464 type enumeration { 1465 enum up; 1466 enum down; 1467 } 1468 type string; 1469 } 1471 It is possible for different member types to match, depending on the 1472 input encoding format. In XML, all values are passed as string 1473 nodes, but in JSON there are different value types for numbers, 1474 booleans, and strings. 1476 In the following example, a JSON numeric value will always be matched 1477 by the "int32" type but in XML the string value representing a number 1478 will be matched by the "string" type. The second version will match 1479 the "int32" member type no matter how the input is encoded. 1481 Incorrect: 1483 type union { 1484 type string; 1485 type int32; 1486 } 1488 Correct: 1490 type union { 1491 type int32; 1492 type string; 1493 } 1495 4.11.5. Empty and Boolean 1497 YANG provides an "empty" data type, which has one value (i.e., 1498 present). The default is "not present", which is not actually a 1499 value. When used within a list key, only one value can (and must) 1500 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1501 key leaf since it is pointless. 1503 There is really no difference between a leaf of type "empty" and a 1504 leaf-list of type "empty". Both are limited to one instance. The 1505 type "empty" SHOULD NOT be used for a leaf-list. 1507 The advantage of using type "empty" instead of type "boolean" is that 1508 the default (not present) does not take up any bytes in a 1509 representation. The disadvantage is that the client may not be sure 1510 if an empty leaf is missing because it was filtered somehow or not 1511 implemented. The client may not have a complete and accurate schema 1512 for the data returned by the server, and not be aware of the missing 1513 leaf. 1515 The YANG "boolean" data type provides two values ("true" and 1516 "false"). When used within a list key, two entries can exist for 1517 this key leaf. Default values are ignored for key leafs, but a 1518 default statement is often used for plain boolean leafs. The 1519 advantage of the "boolean" type is that the leaf or leaf-list has a 1520 clear representation for both values. The default value is usually 1521 not returned unless explicitly requested by the client, so no bytes 1522 are used in a typical representation. 1524 In general, the "boolean" data type SHOULD be used instead of the 1525 "empty" data type, as shown in the example below: 1527 Incorrect: 1529 leaf flag1 { 1530 type empty; 1531 } 1533 Correct: 1535 leaf flag2 { 1536 type boolean; 1537 default false; 1538 } 1540 4.12. Reusable Type Definitions 1542 If an appropriate derived type exists in any standard module, such as 1543 [RFC6991], then it SHOULD be used instead of defining a new derived 1544 type. 1546 If an appropriate units identifier can be associated with the desired 1547 semantics, then a units statement SHOULD be present. 1549 If an appropriate default value can be associated with the desired 1550 semantics, then a default statement SHOULD be present. 1552 If a significant number of derived types are defined, and it is 1553 anticipated that these data types will be reused by multiple modules, 1554 then these derived types SHOULD be contained in a separate module or 1555 submodule, to allow easier reuse without unnecessary coupling. 1557 The description statement MUST be present. 1559 If the type definition semantics are defined in an external document 1560 (other than another YANG module indicated by an import statement), 1561 then the reference statement MUST be present. 1563 4.13. Reusable Groupings 1565 A reusable grouping is a YANG grouping that can be imported by 1566 another module, and is intended for use by other modules. This is 1567 not the same as a grouping that is used within the module it is 1568 defined, but happens to be exportable to another module because it is 1569 defined at the top-level of the YANG module. 1571 The following guidelines apply to reusable groupings, in order to 1572 make them as robust as possible: 1574 o Clearly identify the purpose of the grouping in the "description" 1575 statement. 1577 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1578 output, notification, config=true data nodes, and all data nodes). 1579 Clearly identify which XPath contexts are applicable or excluded 1580 for the grouping. 1582 o Do not reference data outside the grouping in any "path", "must", 1583 or "when" statements. 1585 o Do not include a "default" sub-statement on a leaf or choice 1586 unless the value applies on all possible contexts. 1588 o Do not include a "config" sub-statement on a data node unless the 1589 value applies on all possible contexts. 1591 o Clearly identify any external dependencies in the grouping 1592 "description" statement, such as nodes referenced by absolute path 1593 from a "path", "must", or "when" statement. 1595 4.14. Data Definitions 1597 The description statement MUST be present in the following YANG 1598 statements: 1600 o anyxml 1602 o augment 1604 o choice 1606 o container 1608 o extension 1610 o feature 1612 o grouping 1614 o identity 1616 o leaf 1618 o leaf-list 1620 o list 1622 o notification 1624 o rpc 1626 o typedef 1628 If the data definition semantics are defined in an external document, 1629 (other than another YANG module indicated by an import statement), 1630 then a reference statement MUST be present. 1632 The 'anyxml' construct may be useful to represent an HTML banner 1633 containing markup elements, such as '<b>' and '</b>', and 1634 MAY be used in such cases. However, this construct SHOULD NOT be 1635 used if other YANG data node types can be used instead to represent 1636 the desired syntax and semantics. 1638 It has been found that the 'anyxml' statement is not implemented 1639 consistently across all servers. It is possible that mixed mode XML 1640 will not be supported, or configuration anyxml nodes will not 1641 supported. 1643 If there are referential integrity constraints associated with the 1644 desired semantics that can be represented with XPath, then one or 1645 more 'must' statements SHOULD be present. 1647 For list and leaf-list data definitions, if the number of possible 1648 instances is required to be bounded for all implementations, then the 1649 max-elements statements SHOULD be present. 1651 If any 'must' or 'when' statements are used within the data 1652 definition, then the data definition description statement SHOULD 1653 describe the purpose of each one. 1655 The "choice" statement is allowed to be directly present within a 1656 "case" statement in YANG 1.1. This needs to be considered carefully. 1657 Consider simply including the nested "choice" as additional "case" 1658 statements within the parent "choice" statement. Note that the 1659 "mandatory" and "default" statements within a nested "choice" 1660 statement only apply if the "case" containing the nested "choice" 1661 statement is first selected. 1663 If a list defines any key leafs, then these leafs SHOULD be defined 1664 in order, as the first child nodes within the list. The key leafs 1665 MAY be in a different order in some cases, e.g., they are defined in 1666 a grouping, not inline in the list statement. 1668 4.14.1. Non-Presence Containers 1670 A non-presence container is used to organize data into specific 1671 subtrees. It is not intended to have semantics within the data model 1672 beyond this purpose, although YANG allows it (e.g., "must" statement 1673 within the non-presence container). 1675 Example using container wrappers: 1677 container top { 1678 container foos { 1679 list foo { ... } 1680 } 1681 container bars { 1682 list bar { ... } 1683 } 1684 } 1686 Example without container wrappers: 1688 container top { 1689 list foo { ... } 1690 list bar { ... } 1692 } 1694 Use of non-presence containers to organize data is a subjective 1695 matter similar to use of sub-directories in a file system. The 1696 NETCONF and RESTCONF protocols do not currently support the ability 1697 to delete all list (or leaf-list) entries at once. This deficiency 1698 is sometimes avoided by use of a parent container (i.e., deleting the 1699 container also removes all child entries). 1701 4.14.2. Top-Level Data Nodes 1703 Use of top-level objects needs to be considered carefully: 1705 o top-level siblings are not ordered 1707 o top-level siblings not are not static, and depends on the modules 1708 that are loaded 1710 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1711 treated as a content-match node for all top-level-siblings 1713 o a top-level list with many instances may impact performance 1715 4.15. Operation Definitions 1717 If the operation semantics are defined in an external document (other 1718 than another YANG module indicated by an import statement), then a 1719 reference statement MUST be present. 1721 If the operation impacts system behavior in some way, it SHOULD be 1722 mentioned in the description statement. 1724 If the operation is potentially harmful to system behavior in some 1725 way, it MUST be mentioned in the Security Considerations section of 1726 the document. 1728 4.16. Notification Definitions 1730 The description statement MUST be present. 1732 If the notification semantics are defined in an external document 1733 (other than another YANG module indicated by an import statement), 1734 then a reference statement MUST be present. 1736 If the notification refers to a specific resource instance, then this 1737 instance SHOULD be identified in the notification data. This is 1738 usually done by including 'leafref' leaf nodes with the key leaf 1739 values for the resource instance. For example: 1741 notification interface-up { 1742 description "Sent when an interface is activated."; 1743 leaf name { 1744 type leafref { 1745 path "/if:interfaces/if:interface/if:name"; 1746 } 1747 } 1748 } 1750 Note that there are no formal YANG statements to identify any data 1751 node resources associated with a notification. The description 1752 statement for the notification SHOULD specify if and how the 1753 notification identifies any data node resources associated with the 1754 specific event. 1756 4.17. Feature Definitions 1758 The YANG "feature" statement is used to define a label for a set of 1759 optional functionality within a module. The "if-feature" statement 1760 is used in the YANG statements associated with a feature. The 1761 description-stmt within a feature-stmt MUST specify any interactions 1762 with other features. 1764 The set of YANG features defined in a module should be considered 1765 carefully. Very fine granular features increase interoperability 1766 complexity and should be avoided. A likely misuse of the feature 1767 mechanism is the tagging of individual leafs (e.g., counters) with 1768 separate features. 1770 If there is a large set of objects associated with a YANG feature, 1771 then consider moving those objects to a separate module, instead of 1772 using a YANG feature. Note that the set of features within a module 1773 is easily discovered by the reader, but the set of related modules 1774 within the entire YANG library is not as easy to identity. Module 1775 names with a common prefix can help readers identity the set of 1776 related modules, but this assumes the reader will have discovered and 1777 installed all the relevant modules. 1779 Another consideration for deciding whether to create a new module or 1780 add a YANG feature is the stability of the module in question. It 1781 may be desirable to have a stable base module that is not changed 1782 frequently. If new functionality is placed in a separate module, 1783 then the base module does not need to be republished. If it is 1784 designed as a YANG feature then the module will need to be 1785 republished. 1787 If one feature requires implementation of another feature, then an 1788 "if-feature" statement SHOULD be used in the dependent "feature" 1789 statement. 1791 For example, feature2 requires implementation of feature1: 1793 feature feature1 { 1794 description "Some protocol feature"; 1795 } 1797 feature feature2 { 1798 if-feature "feature1"; 1799 description "Another protocol feature"; 1800 } 1802 4.18. YANG Data Node Constraints 1804 4.18.1. Controlling Quantity 1806 The "min-elements" and "max-elements" statements can be use to 1807 control how many list or leaf-list instances are required for a 1808 particular data node. YANG constraint statements SHOULD be used to 1809 identify conditions that apply to all implementations of the data 1810 model. If platform-specific limitations (e.g., the "max-elements" 1811 supported for a particular list) are relevant to operations, then a 1812 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1813 used to identify the limit. 1815 4.18.2. must vs. when 1817 The "must" and "when" YANG statements are used to provide cross- 1818 object referential tests. They have very different behavior. The 1819 "when" statement causes data node instances to be silently deleted as 1820 soon as the condition becomes false. A false "when" expression is 1821 not considered to be an error. 1823 The "when" statement SHOULD be used together with the "augment" or 1824 "uses" statements to achieve conditional model composition. The 1825 condition SHOULD be based on static properties of the augmented entry 1826 (e.g., list key leafs). 1828 The "must" statement causes a datastore validation error if the 1829 condition is false. This statement SHOULD be used for enforcing 1830 parameter value restrictions that involve more than one data node 1831 (e.g., end-time parameter must be after the start-time parameter). 1833 4.19. Augment Statements 1835 The YANG "augment" statement is used to define a set of data 1836 definition statements that will be added as child nodes of a target 1837 data node. The module namespace for these data nodes will be the 1838 augmenting module, not the augmented module. 1840 A top-level "augment" statement SHOULD NOT be used if the target data 1841 node is in the same module or submodule as the evaluated "augment" 1842 statement. The data definition statements SHOULD be added inline 1843 instead. 1845 4.19.1. Conditional Augment Statements 1847 The "augment" statement is often used together with the "when" 1848 statement and/or "if-feature" statement to make the augmentation 1849 conditional on some portion of the data model. 1851 The following example from [RFC7223] shows how a conditional 1852 container called "ethernet" is added to the "interface" list only for 1853 entries of the type "ethernetCsmacd". 1855 augment "/if:interfaces/if:interface" { 1856 when "if:type = 'ianaift:ethernetCsmacd'"; 1858 container ethernet { 1859 leaf duplex { 1860 ... 1861 } 1862 } 1863 } 1865 4.19.2. Conditionally Mandatory Data Definition Statements 1867 YANG has very specific rules about how configuration data can be 1868 updated in new releases of a module. These rules allow an "old 1869 client" to continue interoperating with a "new server". 1871 If data nodes are added to an existing entry, the old client MUST NOT 1872 be required to provide any mandatory parameters that were not in the 1873 original module definition. 1875 It is possible to add conditional augment statements such that the 1876 old client would not know about the new condition, and would not 1877 specify the new condition. The conditional augment statement can 1878 contain mandatory objects only if the condition is false unless 1879 explicitly requested by the client. 1881 Only a conditional augment statement that uses the "when" statement 1882 form of condition can be used in this manner. The YANG features 1883 enabled on the server cannot be controlled by the client in any way, 1884 so it is not safe to add mandatory augmenting data nodes based on the 1885 "if-feature" statement. 1887 The XPath "when" statement condition MUST NOT reference data outside 1888 of target data node because the client does not have any control over 1889 this external data. 1891 In the following dummy example, it is OK to augment the "interface" 1892 entry with "mandatory-leaf" because the augmentation depends on 1893 support for "some-new-iftype". The old client does not know about 1894 this type so it would never select this type, and therefore not be 1895 adding a mandatory data node. 1897 module example-module { 1898 namespace "http://example.com/ns/example-module"; 1899 prefix mymod; 1901 import iana-if-type { prefix iana; } 1902 import ietf-interfaces { prefix if; } 1904 identity some-new-iftype { 1905 base iana:iana-interface-type; 1906 } 1908 augment "/if:interfaces/if:interface" { 1909 when "if:type = 'mymod:some-new-iftype'"; 1911 leaf mandatory-leaf { 1912 mandatory true; 1913 ... 1914 } 1915 } 1916 } 1918 Note that this practice is safe only for creating data resources. It 1919 is not safe for replacing or modifying resources if the client does 1920 not know about the new condition. The YANG data model MUST be 1921 packaged in a way that requires the client to be aware of the 1922 mandatory data nodes if it is aware of the condition for this data. 1923 In the example above, the "some-new-iftype" identity is defined in 1924 the same module as the "mandatory-leaf" data definition statement. 1926 This practice is not safe for identities defined in a common module 1927 such as "iana-if-type" because the client is not required to know 1928 about "my-module" just because it knows about the "iana-if-type" 1929 module. 1931 4.20. Deviation Statements 1933 The YANG "deviation" statement cannot appear in IETF YANG modules, 1934 but it can be useful for documenting server capabilities. Deviation 1935 statements are not reusable and typically not shared across all 1936 platforms. 1938 There are several reasons that deviations might be needed in an 1939 implementation, e.g., an object cannot be supported on all platforms, 1940 or feature delivery is done in multiple development phases. 1941 Deviation statements can also be used to add annotations to a module, 1942 which does not affect the conformance requirements for the module. 1944 It is suggested that deviation statements be defined in separate 1945 modules from regular YANG definitions. This allows the deviations to 1946 be platform-specific and/or temporary. 1948 The order that deviation statements are evaluated can affect the 1949 result. Therefore multiple deviation statements in the same module, 1950 for the same target object, SHOULD NOT be used. 1952 The "max-elements" statement is intended to describe an architectural 1953 limit to the number of list entries. It is not intended to describe 1954 platform limitations. It is better to use a "deviation" statement 1955 for the platforms that have a hard resource limit. 1957 Example documenting platform resource limits: 1959 Wrong: (max-elements in the list itself) 1961 container backups { 1962 list backup { 1963 ... 1964 max-elements 10; 1965 ... 1966 } 1967 } 1969 Correct: (max-elements in a deviation) 1971 deviation /bk:backups/bk:backup { 1972 deviate add { 1973 max-elements 10; 1974 } 1975 } 1977 4.21. Extension Statements 1979 The YANG "extension" statement is used to specify external 1980 definitions. This appears in the YANG syntax as an 1981 "unknown-statement". Usage of extension statements in a published 1982 module needs to be considered carefully. 1984 The following guidelines apply to the usage of YANG extensions: 1986 o The semantics of the extension MUST NOT contradict any YANG 1987 statements. Extensions can add semantics not covered by the 1988 normal YANG statements. 1990 o The module containing the extension statement MUST clearly 1991 identify the conformance requirements for the extension. It 1992 should be clear whether all implementations of the YANG module 1993 containing the extension need to also implement the extension. If 1994 not, identify what conditions apply that would require 1995 implementation of the extension. 1997 o The extension MUST clearly identify where it can be used within 1998 other YANG statements. 2000 o The extension MUST clearly identify if YANG statements or other 2001 extensions are allowed or required within the extension as sub- 2002 statements. 2004 4.22. Data Correlation 2006 Data can be correlated in various ways, using common data types, 2007 common data naming, and common data organization. There are several 2008 ways to extend the functionality of a module, based on the degree of 2009 coupling between the old and new functionality: 2011 o inline: update the module with new protocol-accessible objects. 2012 The naming and data organization of the original objects is used. 2013 The new objects are in the original module namespace. 2015 o augment: create a new module with new protocol-accessible objects 2016 that augment the original data structure. The naming and data 2017 organization of the original objects is used. The new objects are 2018 in the new module namespace. 2020 o mirror: create new objects in a new module or the original module, 2021 except use new a naming scheme and data location. The naming can 2022 be coupled in different ways. Tight coupling is achieved with a 2023 "leafref" data type, with the "require-instance" sub-statement set 2024 to "true". This method SHOULD be used. 2026 If the new data instances are not limited to the values in use in the 2027 original data structure, then the "require-instance" sub-statement 2028 MUST be set to "false". Loose coupling is achieved by using key 2029 leafs with the same data type as the original data structure. This 2030 has the same semantics as setting the "require-instance" sub- 2031 statement to "false". 2033 The relationship between configuration and operational state has been 2034 clarified in NMDA [I-D.ietf-netmod-revised-datastores]. 2036 4.22.1. Use of Leafref for Key Correlation 2038 Sometimes it is not practical to augment a data structure. For 2039 example, the correlated data could have different keys or contain 2040 mandatory nodes. 2042 The following example shows the use of the "leafref" data type for 2043 data correlation purposes: 2045 Not preferred: 2047 list foo { 2048 key name; 2049 leaf name { 2050 type string; 2051 } 2052 ... 2053 } 2055 list foo-addon { 2056 key name; 2057 config false; 2058 leaf name { 2059 type string; 2060 } 2061 ... 2062 } 2064 Preferred: 2066 list foo { 2067 key name; 2068 leaf name { 2069 type string; 2070 } 2071 ... 2072 } 2074 list foo-addon { 2075 key name; 2076 config false; 2077 leaf name { 2078 type leafref { 2079 path "/foo/name"; 2080 require-instance false; 2081 } 2082 } 2083 leaf addon { 2084 type string; 2085 mandatory true; 2086 } 2087 } 2089 4.23. Operational State 2091 The modeling of operational state with YANG has been refined over 2092 time. At first, only data that has a "config" statement value of 2093 "false" was considered to be operational state. This data was not 2094 considered to be part of any datastore, which made YANG XPath 2095 definition much more complicated. 2097 Operational state is now modeled using YANG according to the new NMDA 2098 [I-D.ietf-netmod-revised-datastores], and is now conceptually 2099 contained in the operational state datastore, which also includes the 2100 operational values of configuration data. There is no longer any 2101 need to duplicate data structures to provide separate configuration 2102 and operational state sections. 2104 This section describes some data modeling issues related to 2105 operational state, and guidelines for transitioning YANG data model 2106 design to be NMDA-compatible. 2108 4.23.1. Combining Operational State and Configuration Data 2110 If possible, operational state SHOULD be combined with its associated 2111 configuration data. This prevents duplication of key leafs and 2112 ancestor nodes. It also prevents race conditions for retrieval of 2113 dynamic entries, and allows configuration and operational state to be 2114 retrieved together with minimal message overhead. 2116 container foo { 2117 ... 2118 // contains config=true and config=false nodes that have 2119 // no corresponding config=true object (e.g., counters) 2120 } 2122 4.23.2. Representing Operational Values of Configuration Data 2124 If possible the same data type SHOULD be used to represent the 2125 configured value and the operational value, for a given leaf or leaf- 2126 list object. 2128 Sometimes the configured value set is different than the operational 2129 value set for that object. For example, the "admin-state" and 2130 "oper-state" leafs in [RFC7223]. In this case a separate object MAY 2131 be used to represent the configured and operational values. 2133 Sometimes the list keys are not identical for configuration data and 2134 the corresponding operational state. In this case separate lists MAY 2135 be used to represent the configured and operational values. 2137 If it is not possible to combine configuration and operational state, 2138 then the keys used to represent list entries SHOULD be the same type. 2139 The "leafref" data type SHOULD be used in operational state for key 2140 leafs that have corresponding configuration instances. The 2141 "require-instance" statement MAY be set to "false" (in YANG 1.1 2142 modules only) to indicate instances are allowed in the operational 2143 state that do not exist in the associated configuration data. 2145 The need to replicate objects or define different operational state 2146 objects depends on the data model. It is not possible to define one 2147 approach that will be optimal for all data models. 2149 Designers SHOULD describe and justify any NMDA exceptions in detail, 2150 such as the use of separate subtrees and/or separate leafs. The 2151 "description" statements for both the configuration and the 2152 operational state SHOULD be used for this purpose. 2154 4.23.3. NMDA Transition Guidelines 2156 YANG modules SHOULD be designed assuming they will be used on servers 2157 supporting the operational state datastore. With this in mind, YANG 2158 modules SHOULD define config "false" wherever they make sense to the 2159 data model. Config "false" nodes SHOULD NOT be defined to provide 2160 the operational value for configuration nodes, except when the value 2161 space of a configured and operational values may differ, in which 2162 case a distinct config "false" node SHOULD be defined to hold the 2163 operational value for the configured node. 2165 The following guidelines are meant to help modelers develop YANG 2166 modules that will maximize the utility of the model with both current 2167 and new implementations. 2169 New modules and modules that are not concerned with the operational 2170 state of configuration information SHOULD immediately be structured 2171 to be NMDA-compatible, as described in Section 4.23.1. This 2172 transition MAY be deferred if the module does not contain any 2173 configuration datastore objects. 2175 The remaining are options that MAY be followed during the time that 2176 NMDA mechanisms are being defined. 2178 (a) Modules that require immediate support for the NMDA features 2179 SHOULD be structured for NMDA. A temporary non-NMDA version of this 2180 type of module MAY exist, either an existing model or a model created 2181 either by hand or with suitable tools that mirror the current 2182 modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 2183 be published in the same document, with NMDA modules in the document 2184 main body and the non-NMDA modules in a non-normative appendix. The 2185 use of the non-NMDA module will allow temporary bridging of the time 2186 period until NMDA implementations are available. 2188 (b) For published models, the model should be republished with an 2189 NMDA-compatible structure, deprecating non-NMDA constructs. For 2190 example, the "ietf-interfaces" model in [RFC7223] has been 2191 restructured as an NMDA-compatible model in 2192 [I-D.ietf-netmod-rfc7223bis]. The "/interfaces-state" hierarchy has 2193 been marked "status deprecated". Models that mark their "/foo-state" 2194 hierarchy with "status deprecated" will allow NMDA-capable 2195 implementations to avoid the cost of duplicating the state nodes, 2196 while enabling non-NMDA-capable implementations to utilize them for 2197 access to the operational values. 2199 (c) For models that augment models which have not been structured 2200 with the NMDA, the modeler will have to consider the structure of the 2201 base model and the guidelines listed above. Where possible, such 2202 models should move to new revisions of the base model that are NMDA- 2203 compatible. When that is not possible, augmenting "state" containers 2204 SHOULD be avoided, with the expectation that the base model will be 2205 re-released with the state containers marked as deprecated. It is 2206 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 2207 Where this recommendation cannot be followed, then any new "state" 2208 elements SHOULD be included in their own module. 2210 4.23.3.1. Temporary non-NMDA Modules 2212 A temporary non-NMDA module allows a non-NMDA aware client to access 2213 operational state from an NMDA-compliant server. It contains the 2214 top-level config=false data nodes that would have been defined in a 2215 legacy YANG module (before NMDA). 2217 A server that needs to support both NMDA and non-NMDA clients can 2218 advertise both the new NMDA module and the temporary non-NMDA module. 2219 A non-NMDA client can use separate "foo" and "foo-state" subtrees, 2220 except the "foo-state" subtree is located in a different (temporary) 2221 module. The NMDA module can be used by a non-NMDA client to access 2222 the conventional configuration datastores, and the deprecated 2223 operation to access nested config=false data nodes. 2225 To create the temporary non-NMDA model from an NMDA model, the 2226 following steps can be taken: 2228 o Change the module name by appending "-state" to the original 2229 module name 2231 o Change the namespace by appending "-state" to the original 2232 namespace value 2234 o Change the prefix by appending "-s" to the original prefix value 2236 o Add an import to the original module (e.g., for typedef 2237 definitions) 2239 o Retain or create only the top-level nodes that have a "config" 2240 statement value "false". These subtrees represent config=false 2241 data nodes that were combined into the configuration subtree, and 2242 therefore not available to non-NMDA aware clients. Set the 2243 "status" statement to "deprecated" for each new node. 2245 o The module description SHOULD clearly identify the module as a 2246 temporary non-NMDA module 2248 4.23.3.2. Example: Create a New NMDA Module 2250 Create an NMDA-compliant module, using combined configuration and 2251 state subtrees, whenever possible. 2253 module example-foo { 2254 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2255 prefix "foo"; 2257 container foo { 2258 // configuration data child nodes 2259 // operational value in operational state datastore only 2260 // may contain config=false nodes as needed 2261 } 2262 } 2264 4.23.3.3. Example: Convert an old Non-NMDA Module 2266 Do not remove non-compliant objects from existing modules. Instead, 2267 change the status to "deprecated". At some point, usually after 1 2268 year, the status MAY be changed to "obsolete". 2270 Old Module: 2272 module example-foo { 2273 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2274 prefix "foo"; 2276 container foo { 2277 // configuration data child nodes 2278 } 2280 container foo-state { 2281 config false; 2282 // operational state child nodes 2283 } 2284 } 2286 Converted NMDA Module: 2288 module example-foo { 2289 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2290 prefix "foo"; 2292 container foo { 2293 // configuration data child nodes 2294 // operational value in operational state datastore only 2295 // may contain config=false nodes as needed 2296 // will contain any data nodes from old foo-state 2297 } 2299 // keep original foo-state but change status to deprecated 2300 container foo-state { 2301 config false; 2302 status deprecated; 2303 // operational state child nodes 2304 } 2305 } 2307 4.23.3.4. Example: Create a Temporary NMDA Module: 2309 Create a new module that contains the top-level operational state 2310 data nodes that would have been available before they were combined 2311 with configuration data nodes (to be NMDA compliant). 2313 module example-foo-state { 2314 namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; 2315 prefix "foo-s"; 2317 // import new or converted module; not used in this example 2318 import example-foo { prefix foo; } 2320 container foo-state { 2321 config false; 2322 status deprecated; 2323 // operational state child nodes 2324 } 2325 } 2327 4.24. Performance Considerations 2329 It is generally likely that certain YANG statements require more 2330 runtime resources than other statements. Although there are no 2331 performance requirements for YANG validation, the following 2332 information MAY be considered when designing YANG data models: 2334 o Lists are generally more expensive than containers 2336 o "when-stmt" evaluation is generally more expensive than 2337 "if-feature" or "choice" statements 2339 o "must" statement is generally more expensive than "min-entries", 2340 "max-entries", "mandatory", or "unique" statements 2342 o "identityref" leafs are generally more expensive than 2343 "enumeration" leafs 2345 o "leafref" and "instance-identifier" types with "require-instance" 2346 set to true are generally more expensive than if 2347 "require-instance" is set to false 2349 4.25. Open Systems Considerations 2351 A YANG module MUST NOT be designed such that the set of modules found 2352 on a server implementation can be predetermined in advance. Only the 2353 modules imported by a particular module can be assumed to be present 2354 in an implementation. An open system MAY include any combination of 2355 YANG modules. 2357 4.26. Guidelines for YANG 1.1 Specific Constructs 2359 The set of YANG 1.1 guidelines will grow as operational experience is 2360 gained with the new language features. This section contains an 2361 initial set of guidelines for new YANG 1.1 language features. 2363 4.26.1. Importing Multiple Revisions 2365 Standard modules SHOULD NOT import multiple revisions of the same 2366 module into a module. This MAY be done if independent definitions 2367 (e.g. enumeration typedefs) from specific revisions are needed in the 2368 importing module. 2370 4.26.2. Using Feature Logic 2372 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2373 "description" statement SHOULD describe the "if-feature" logic in 2374 text, to help readers understand the module. 2376 YANG features SHOULD be used instead of the "when" statement, if 2377 possible. Features are advertised by the server and objects 2378 conditional by if-feature are conceptually grouped together. There 2379 is no such commonality supported for "when" statements. 2381 Features generally require less server implementation complexity and 2382 runtime resources than objects that use "when" statements. Features 2383 are generally static (i.e., set when module is loaded and not changed 2384 at runtime). However every client edit might cause a "when" 2385 statement result to change. 2387 4.26.3. anyxml vs. anydata 2389 The "anyxml" statement MUST NOT be used to represent a conceptual 2390 subtree of YANG data nodes. The "anydata" statement MUST be used for 2391 this purpose. 2393 4.26.4. action vs. rpc 2395 The use of "action" statements or "rpc" statements is a subjective 2396 design decision. RPC operations are not associated with any 2397 particular data node. Actions are associated with a specific data 2398 node definition. An "action" statement SHOULD be used if the 2399 protocol operation is specific to a subset of all data nodes instead 2400 of all possible data nodes. 2402 The same action name MAY be used in different definitions within 2403 different data node. For example, a "reset" action defined with a 2404 data node definition for an interface might have different parameters 2405 than for a power supply or a VLAN. The same action name SHOULD be 2406 used to represent similar semantics. 2408 The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis] 2409 does not support parameter access control for RPC operations. The 2410 user is given permission (or not) to invoke the RPC operation with 2411 any parameters. For example, if each client is only allowed to reset 2412 their own interface, then NACM cannot be used. 2414 For example, NACM cannot enforce access access control based on the 2415 value of the "interface" parameter, only the "reset" operation 2416 itself: 2418 rpc reset { 2419 input { 2420 leaf interface { 2421 type if:interface-ref; 2422 mandatory true; 2423 description "The interface to reset."; 2424 } 2425 } 2426 } 2428 However, NACM can enforce access access control for individual 2429 interface instances, using a "reset" action, If the user does not 2430 have read access to the specific "interface" instance, then it cannot 2431 invoke the "reset" action for that interface instance: 2433 container interfaces { 2434 list interface { 2435 ... 2436 action reset { } 2437 } 2438 } 2440 4.27. Updating YANG Modules (Published vs. Unpublished) 2442 YANG modules can change over time. Typically, new data model 2443 definitions are needed to support new features. YANG update rules 2444 defined in section 11 of [RFC7950] MUST be followed for published 2445 modules. They MAY be followed for unpublished modules. 2447 The YANG update rules only apply to published module revisions. Each 2448 organization will have their own way to identify published work which 2449 is considered to be stable, and unpublished work which is considered 2450 to be unstable. For example, in the IETF, the RFC document is used 2451 for published work, and the Internet-Draft is used for unpublished 2452 work. 2454 5. IANA Considerations 2456 -- RFC Ed: These registries need to be updated to reference this 2457 RFC instead of RFC 6087 for the ietf-template module, and 2458 remove this note. 2460 This document registers one URI in the IETF XML registry [RFC3688]. 2462 The following registration has been made in [RFC6087] and updated by 2463 this document. 2465 URI: urn:ietf:params:xml:ns:yang:ietf-template 2467 Registrant Contact: The IESG. 2469 XML: N/A, the requested URI is an XML namespace. 2471 The following assignment has been made in [RFC6087] and updated by 2472 this document in the YANG Module Names Registry, or the YANG module 2473 template in Appendix C. 2475 +-----------+-------------------------------------------+ 2476 | Field | Value | 2477 +-----------+-------------------------------------------+ 2478 | Name | ietf-template | 2479 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2480 | Prefix | temp | 2481 | Reference | RFC XXXX | 2482 +-----------+-------------------------------------------+ 2484 YANG Registry Assignment 2486 6. Security Considerations 2488 This document defines documentation guidelines for NETCONF or 2489 RESTCONF content defined with the YANG data modeling language, and 2490 therefore does not introduce any new or increased security risks into 2491 the management system. 2493 7. Acknowledgments 2495 The structure and contents of this document are adapted from 2496 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2498 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2499 Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive 2500 reviews and contributions to this document. 2502 8. References 2504 8.1. Normative References 2506 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2507 Requirement Levels", BCP 14, RFC 2119, March 1997. 2509 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2510 January 2004. 2512 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2513 Resource Identifier (URI): Generic Syntax", STD 66, 2514 RFC 3986, January 2005. 2516 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2517 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 2518 RFC5246, August 2008, 2519 . 2521 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2522 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2524 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2525 Network Configuration Protocol (NETCONF)", RFC 6020, 2526 October 2010. 2528 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2529 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2530 . 2532 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2533 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2534 May 2017, . 2536 [W3C.REC-xpath-19991116] 2537 Clark, J. and S. DeRose, "XML Path Language (XPath) 2538 Version 1.0", World Wide Web Consortium 2539 Recommendation REC-xpath-19991116, November 1999, 2540 . 2542 8.2. Informative References 2544 [I-D.ietf-netconf-rfc6536bis] 2545 Bierman, A. and M. Bjorklund, "Network Configuration 2546 Access Control Module", draft-ietf-netconf-rfc6536bis-09 2547 (work in progress), December 2017. 2549 [I-D.ietf-netmod-revised-datastores] 2550 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2551 and R. Wilton, "Network Management Datastore 2552 Architecture", draft-ietf-netmod-revised-datastores-10 2553 (work in progress), January 2018. 2555 [I-D.ietf-netmod-rfc7223bis] 2556 Bjorklund, M., "A YANG Data Model for Interface 2557 Management", draft-ietf-netmod-rfc7223bis-03 (work in 2558 progress), January 2018. 2560 [I-D.ietf-netmod-rfc8022bis] 2561 Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 2562 Routing Management (NMDA Version)", 2563 draft-ietf-netmod-rfc8022bis-11 (work in progress), 2564 January 2018. 2566 [I-D.ietf-netmod-yang-tree-diagrams] 2567 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2568 draft-ietf-netmod-yang-tree-diagrams-06 (work in 2569 progress), February 2018. 2571 [RFC-STYLE] 2572 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2573 Style", September 2009, 2574 . 2576 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2577 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2578 . 2580 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2581 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2582 . 2584 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2585 Documents", BCP 111, RFC 4181, September 2005. 2587 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2588 Data Model Documents", RFC 6087, January 2011. 2590 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2591 and A. Bierman, Ed., "Network Configuration Protocol 2592 (NETCONF)", RFC 6241, June 2011. 2594 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2595 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2596 . 2598 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2599 Protocol (NETCONF) Access Control Model", RFC 6536, 2600 March 2012. 2602 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2603 July 2013. 2605 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2606 Management", RFC 7223, May 2014. 2608 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2609 DOI 10.17487/RFC7322, September 2014, 2610 . 2612 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2613 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2614 DOI 10.17487/RFC7841, May 2016, 2615 . 2617 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2618 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2619 . 2621 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2622 Writing an IANA Considerations Section in RFCs", BCP 26, 2623 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2624 . 2626 Appendix A. Change Log 2628 -- RFC Ed.: remove this section before publication. 2630 A.1. v17 to v18 2632 o address Area Director review comments Part 2 2634 o clarify preferred list key order 2636 A.2. v16 to v17 2638 o address Area Director review comments Part 1 2640 A.3. v15 to v16 2642 o address Area Director review comments posted 2018-01-25 2644 A.4. v15 to v16 2646 o address document shephard comments posted 2018-01-15 2648 o add yang-version to template module 2650 A.5. v14 to v15 2652 o changed Intended status from Informational to BCP 2654 o update tree diagram guidelines section 2656 o Change IANA template to list IESG instead of NETMOD WG as the 2657 Registrant 2659 o Update some references 2661 A.6. v13 to v14 2663 o Replaced sec. 4.23 Operational Data with Operational Data from 2664 NMDA text by Lou Berger and Kent Watsen 2666 o Added NMDA Terms section 2668 o Changed term operational data to operational state 2670 o Clarified that reference-stmt SHOULD be present in import-stmt 2672 A.7. v12 to v13 2674 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2675 YANG file extraction macro. 2677 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2678 module name registries. 2680 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2682 o Update Operation Data section to consider revised datastores. 2684 o Add reference to YANG Tree Diagrams and update 2 sections that use 2685 this reference. 2687 o Add reference to Revised Datastores and guidelines drafts 2689 A.8. v11 to v12 2691 o fix incorrect location of new Module Usage Examples section 2693 A.9. v10 to v11 2695 o updated YANG tree diagram syntax to align with pyang 1.7.1 2697 o added general guideline to include module usage examples 2699 A.10. v09 to v10 2701 o clarified is only for normative modules 2703 o clarified example module namespace URI conventions 2705 o clarified pyang usage for normative and example modules 2707 o updated YANG tree diagrams section with text from RFC 8022 2709 A.11. v08 to v09 2711 o fixed references 2713 o added mention of RESTCONF to abstract and intro 2715 o created separate section for code components 2717 o fixed document status 2719 A.12. v07 to v08 2721 o changed CODE BEGINS guideline for example modules 2723 o updated tree diagram guidelines 2725 o clarified published and unpublished terms 2727 o added section on Empty and Boolean data types 2729 o clarified how to update the revision statement 2731 o updated operational state guidelines 2733 o added 'YANG fragment' to terminology section 2735 A.13. v06 to v07 2737 o update contact statement guideline 2739 o update example modules guidelines 2741 o add guidelines on top-level data nodes 2743 o add guideline on use of NP containers 2745 o added guidelines on union types 2747 o add guideline on deviations 2749 o added section on open systems considerations 2751 o added guideline about definitions reserved for future use 2753 A.14. v05 to v06 2755 o Changed example 'my-module' to 'example-module' 2757 o Added section Updating YANG Modules (Published vs. Unpublished) 2759 o Added Example Modules section 2761 o Added "" convention for full example modules 2763 o Added section on using action vs. rpc 2765 o Changed term "operational state" to "operational data" 2766 o Added section on YANG Data Node Constraints 2768 o Added guidelines on using must vs. when statements 2770 o Made ietf-foo module validate for I-D submission 2772 A.15. v04 to v05 2774 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2775 no YANG 1.1 features needed 2777 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2778 standards track documents only) 2780 o Clarified module naming conventions for normative modules, example 2781 modules, and modules from other SDOs. 2783 o Added prefix value selection guidelines 2785 o Added new section on guidelines for reusable groupings 2787 o Made header guidelines less IETF-specific 2789 o Added new section on guidelines for extension statements 2791 o Added guidelines for nested "choice" statement within a "case" 2792 statement 2794 A.16. v03 ot v04 2796 o Added sections for deviation statements and performance 2797 considerations 2799 o Added YANG 1.1 section 2801 o Updated YANG reference from 1.0 to 1.1 2803 A.17. v02 to v03 2805 o Updated draft based on github data tracker issues added by Benoit 2806 Clause (Issues 12 - 18) 2808 A.18. v01 to v02 2810 o Updated draft based on mailing list comments. 2812 A.19. v00 to v01 2814 All issues from the issue tracker have been addressed. 2816 https://github.com/netmod-wg/rfc6087bis/issues 2818 o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with 2819 YANG modules can use an Informative reference to this RFC for tree 2820 diagrams. Updated guidelines to reference this RFC when tree 2821 diagrams are used 2823 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2824 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2825 functions 2827 o Issue 3: XPath function document order issues: Added paragraph in 2828 XPath usage section about node-set ordering for 'local-name', 2829 'namespace-uri', 'name', 'string' and 'number' functions. Also 2830 any function that implicitly converts a node-set to a string. 2832 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2833 and text in XPath usage section already has proposed text from 2834 Lada. 2836 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2837 exception and example in XPath Usage section for augmented nodes. 2839 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2840 to 'numeric and boolean expressions' 2842 o Issue 7: XPath module containment: Added sub-section on XPath 2843 wildcards 2845 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2846 section about transitioning from active to deprecated and then to 2847 obsolete. 2849 o Issue 9: resource identification in notifications: Add text to 2850 Notifications section about identifying resources and using the 2851 leafref data type. 2853 o Issue 10: single quoted strings: Added text to Data Types section 2854 about using a single-quoted string for patterns. 2856 Appendix B. Module Review Checklist 2858 This section is adapted from RFC 4181. 2860 The purpose of a YANG module review is to review the YANG module both 2861 for technical correctness and for adherence to IETF documentation 2862 requirements. The following checklist may be helpful when reviewing 2863 an Internet-Draft: 2865 o I-D Boilerplate -- verify that the draft contains the required 2866 Internet-Draft boilerplate (see 2867 http://www.ietf.org/id-info/guidelines.html), including the 2868 appropriate statement to permit publication as an RFC, and that 2869 I-D boilerplate does not contain references or section numbers. 2871 o Abstract -- verify that the abstract does not contain references, 2872 that it does not have a section number, and that its content 2873 follows the guidelines in 2874 http://www.ietf.org/id-info/guidelines.html. 2876 o Copyright Notice -- verify that the draft has the appropriate text 2877 regarding the rights that document contributers provide to the 2878 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2879 copyright notice at the beginning of the document. The IETF Trust 2880 Legal Provisions (TLP) can be found at: 2882 http://trustee.ietf.org/license-info/ 2884 o Security Considerations section -- verify that the draft uses the 2885 latest approved template from the OPS area website (http:// 2886 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2887 and that the guidelines therein have been followed. 2889 o IANA Considerations section -- this section must always be 2890 present. For each module within the document, ensure that the 2891 IANA Considerations section contains entries for the following 2892 IANA registries: 2894 XML Namespace Registry: Register the YANG module namespace. 2896 YANG Module Registry: Register the YANG module name, prefix, 2897 namespace, and RFC number, according to the rules specified 2898 in [RFC6020]. 2900 o References -- verify that the references are properly divided 2901 between normative and informative references, that RFC 2119 and 2902 RFC 8174 are included as normative references if the terminology 2903 defined therein is used in the document, that all references 2904 required by the boilerplate are present, that all YANG modules 2905 containing imported items are cited as normative references, and 2906 that all citations point to the most current RFCs unless there is 2907 a valid reason to do otherwise (for example, it is OK to include 2908 an informative reference to a previous version of a specification 2909 to help explain a feature included for backward compatibility). 2910 Be sure citations for all imported modules are present somewhere 2911 in the document text (outside the YANG module). If a YANG module 2912 contains reference or description statements that refer to an 2913 Internet Draft (I-D), then the I-D is included as an Informative 2914 Reference. 2916 o License -- verify that the draft contains the Simplified BSD 2917 License in each YANG module or submodule. Some guidelines related 2918 to this requirement are described in Section 3.1. Make sure that 2919 the correct year is used in all copyright dates. Use the approved 2920 text from the latest Trust Legal Provisions (TLP) document, which 2921 can be found at: 2923 http://trustee.ietf.org/license-info/ 2925 o Other Issues -- check for any issues mentioned in 2926 http://www.ietf.org/id-info/checklist.html that are not covered 2927 elsewhere. 2929 o Technical Content -- review the actual technical content for 2930 compliance with the guidelines in this document. The use of a 2931 YANG module compiler is recommended when checking for syntax 2932 errors. A list of freely available tools and other information 2933 can be found at: 2935 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2937 Checking for correct syntax, however, is only part of the job. 2938 It is just as important to actually read the YANG module document 2939 from the point of view of a potential implementor. It is 2940 particularly important to check that description statements are 2941 sufficiently clear and unambiguous to allow interoperable 2942 implementations to be created. 2944 Appendix C. YANG Module Template 2946 file "ietf-template@2016-03-20.yang" 2948 module ietf-template { 2950 yang-version 1.1; 2952 // replace this string with a unique namespace URN value 2953 namespace 2954 "urn:ietf:params:xml:ns:yang:ietf-template"; 2956 // replace this string, and try to pick a unique prefix 2957 prefix "temp"; 2959 // import statements here: e.g., 2960 // import ietf-yang-types { prefix yang; } 2961 // import ietf-inet-types { prefix inet; } 2963 // identify the IETF working group if applicable 2964 organization 2965 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2967 // update this contact statement with your info 2968 contact 2969 "WG Web: 2970 WG List: 2972 Editor: your-name 2973 "; 2975 // replace the first sentence in this description statement. 2976 // replace the copyright notice with the most recent 2977 // version, if it has been updated since the publication 2978 // of this document 2979 description 2980 "This module defines a template for other YANG modules. 2982 Copyright (c) IETF Trust and the persons 2983 identified as authors of the code. All rights reserved. 2985 Redistribution and use in source and binary forms, with or 2986 without modification, is permitted pursuant to, and subject 2987 to the license terms contained in, the Simplified BSD License 2988 set forth in Section 4.c of the IETF Trust's Legal Provisions 2989 Relating to IETF Documents 2990 (http://trustee.ietf.org/license-info). 2991 This version of this YANG module is part of RFC XXXX; see 2992 the RFC itself for full legal notices."; 2994 // RFC Ed.: replace XXXX with actual RFC number and remove 2995 // this note 2997 reference "RFC XXXX"; 2999 // RFC Ed.: remove this note 3000 // Note: extracted from RFC XXXX 3002 // replace '2016-03-20' with the module publication date 3003 // The format is (year-month-day) 3004 revision "2016-03-20" { 3005 description "what changed in this revision"; 3006 reference "document containing this module"; 3007 } 3009 // extension statements 3011 // feature statements 3013 // identity statements 3015 // typedef statements 3017 // grouping statements 3019 // data definition statements 3021 // augment statements 3023 // rpc statements 3025 // notification statements 3027 // DO NOT put deviation statements in a published module 3029 } 3031 3033 Author's Address 3035 Andy Bierman 3036 YumaWorks 3038 Email: andy@yumaworks.com