idnits 2.17.1 draft-ietf-netmod-rfc6087bis-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 7, 2016) is 2850 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 358, but not defined == Missing Reference: 'RFC6242' is mentioned on line 2089, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-07 ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track July 7, 2016 5 Expires: January 8, 2017 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-07 10 Abstract 12 This memo provides guidelines for authors and reviewers of Standards 13 Track specifications containing YANG data model modules. Applicable 14 portions may be used as a basis for reviews of other YANG data model 15 documents. Recommendations and procedures are defined, which are 16 intended to increase interoperability and usability of Network 17 Configuration Protocol (NETCONF) implementations that utilize YANG 18 data model modules. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 8, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 57 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 58 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 61 4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 62 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 63 4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 64 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 65 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 66 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 67 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 68 4.6. Security Considerations Section . . . . . . . . . . . . . 11 69 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 70 4.7.1. Documents that Create a New Namespace . . . . . . . . 12 71 4.7.2. Documents that Extend an Existing Namespace . . . . . 12 72 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 73 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 74 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 75 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 76 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 77 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 79 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 80 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 81 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 82 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 83 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 84 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 85 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 86 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 87 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 88 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 89 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 90 5.8. Module Header, Meta, and Revision Statements . . . . . . . 23 91 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 92 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 93 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26 94 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 95 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27 96 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28 97 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 28 98 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 30 99 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 30 100 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 31 101 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 32 102 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 33 103 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 33 104 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 33 105 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 34 106 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 35 107 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 35 108 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 35 109 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 35 110 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 36 111 5.19.2. Conditionally Mandatory Data Definition Statements . . 36 112 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 37 113 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 38 114 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 39 115 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 40 116 5.24. Performance Considerations . . . . . . . . . . . . . . . . 42 117 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 43 118 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 43 119 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 43 120 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 43 121 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 44 122 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 44 123 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 45 124 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 125 7. Security Considerations . . . . . . . . . . . . . . . . . . . 47 126 7.1. Security Considerations Section Template . . . . . . . . . 47 127 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 128 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 50 129 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 130 10.1. Normative References . . . . . . . . . . . . . . . . . . . 52 131 10.2. Informative References . . . . . . . . . . . . . . . . . . 53 132 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 54 133 A.1. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 54 134 A.2. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 54 135 A.3. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 54 136 A.4. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 55 137 A.5. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 55 138 A.6. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 55 139 A.7. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 55 140 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 57 141 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 59 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 61 144 1. Introduction 146 The standardization of network configuration interfaces for use with 147 the Network Configuration Protocol [RFC6241] requires a modular set 148 of data models, which can be reused and extended over time. 150 This document defines a set of usage guidelines for Standards Track 151 documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG 152 is used to define the data structures, protocol operations, and 153 notification content used within a NETCONF server. A server that 154 supports a particular YANG module will support client NETCONF 155 operation requests, as indicated by the specific content defined in 156 the YANG module. 158 This document is similar to the Structure of Management Information 159 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 160 and structure. However, since that document was written a decade 161 after SMIv2 modules had been in use, it was published as a 'Best 162 Current Practice' (BCP). This document is not a BCP, but rather an 163 informational reference, intended to promote consistency in documents 164 containing YANG modules. 166 Many YANG constructs are defined as optional to use, such as the 167 description statement. However, in order to maximize 168 interoperability of NETCONF implementations utilizing YANG data 169 models, it is desirable to define a set of usage guidelines that may 170 require a higher level of compliance than the minimum level defined 171 in the YANG specification. 173 In addition, YANG allows constructs such as infinite length 174 identifiers and string values, or top-level mandatory nodes, that a 175 compliant server is not required to support. Only constructs that 176 all servers are required to support can be used in IETF YANG modules. 178 This document defines usage guidelines related to the NETCONF 179 operations layer and NETCONF content layer, as defined in [RFC6241]. 180 These guidelines are intended to be used by authors and reviewers to 181 improve the readability and interoperability of published YANG data 182 models. 184 Note that this document is not a YANG tutorial and the reader is 185 expected to know the YANG data modeling language before using this 186 document. 188 2. Terminology 190 2.1. Requirements Notation 192 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 193 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 194 document are to be interpreted as described in [RFC2119]. 196 RFC 2119 language is used here to express the views of the NETMOD 197 working group regarding content for YANG modules. YANG modules 198 complying with this document will treat the RFC 2119 terminology as 199 if it were describing best current practices. 201 2.2. NETCONF Terms 203 The following terms are defined in [RFC6241] and are not redefined 204 here: 206 o capabilities 208 o client 210 o operation 212 o server 214 2.3. YANG Terms 216 The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and 217 are not redefined here: 219 o data node 221 o module 223 o namespace 225 o submodule 227 o version 229 o YANG 231 o YIN 233 Note that the term 'module' may be used as a generic term for a YANG 234 module or submodule. When describing properties that are specific to 235 submodules, the term 'submodule' is used instead. 237 2.4. Terms 239 The following terms are used throughout this document: 241 o published: A stable release of a module or submodule, usually 242 contained in an RFC. 244 o unpublished: An unstable release of a module or submodule, usually 245 contained in an Internet-Draft. 247 3. YANG Tree Diagrams 249 YANG tree diagrams provide a concise representation of a YANG module 250 to help readers understand the module structure. 252 The meaning of the symbols in YANG tree diagrams is as follows: 254 o Brackets "[" and "]" enclose list keys. 256 o Abbreviations before data node names: "rw" means configuration 257 (read-write) and "ro" state data (read-only). 259 o Symbols after data node names: "?" means an optional node, "!" 260 means a presence container, and "*" denotes a list and leaf-list. 262 o Parentheses enclose choice and case nodes, and case nodes are also 263 marked with a colon (":"). 265 o Ellipsis ("...") stands for contents of subtrees that are not 266 shown. 268 4. General Documentation Guidelines 270 YANG data model modules under review are likely to be contained in 271 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 272 followed. The RFC Editor provides guidelines for authors of RFCs, 273 which are first published as Internet-Drafts. These guidelines 274 should be followed and are defined in [RFC2223] and updated in 275 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 277 The following sections MUST be present in an Internet-Draft 278 containing a module: 280 o Narrative sections 282 o Definitions section 284 o Security Considerations section 286 o IANA Considerations section 288 o References section 290 There are three usage scenarios for YANG that can appear in an 291 Internet-Draft or RFC: 293 o normative module or submodule 295 o example module or submodule 297 o example YANG fragment not part of any module or submodule 299 The guidelines in this document refer mainly to a normative complete 300 module or submodule, but may be applicable to example modules and 301 YANG fragments as well. 303 4.1. Module Copyright 305 The module description statement MUST contain a reference to the 306 latest approved IETF Trust Copyright statement, which is available 307 online at: 309 http://trustee.ietf.org/license-info/ 311 Each YANG module or submodule contained within an Internet-Draft or 312 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 314 component. 316 The "" tag SHOULD be followed by a string identifying 317 the file name specified in Section 5.2 of 318 [I-D.ietf-netmod-rfc6020bis]. The following example is for the 319 '2010-01-18' revision of the 'ietf-foo' module: 321 file "ietf-foo@2016-03-20.yang" 323 module ietf-foo { 324 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 325 prefix "foo"; 326 organization "..."; 327 contact "..."; 328 description "..."; 329 revision 2016-03-20 { 330 description "Latest revision"; 331 reference "RFC XXXX"; 332 } 333 // ... more statements 334 } 336 338 4.1.1. Example Modules 340 The convention SHOULD NOT be used for example modules 341 or YANG fragments, in order to make sure module extraction tools will 342 ignore them. 344 An example module SHOULD be named using the term "example", followed 345 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 347 4.2. Terminology Section 349 A terminology section MUST be present if any terms are defined in the 350 document or if any terms are imported from other documents. 352 If YANG tree diagrams are used, then a sub-section explaining the 353 YANG tree diagram syntax MUST be present, containing the following 354 text: 356 A simplified graphical representation of the data model is used in 357 this document. The meaning of the symbols in these diagrams is 358 defined in [RFCXXXX]. 360 -- RFC Editor: Replace XXXX with RFC number and remove note 362 4.3. Tree Diagrams 364 YANG tree diagrams provide a concise representation of a YANG module, 365 and SHOULD be included to help readers understand YANG module 366 structure. Tree diagrams MAY be split into sections to correspond to 367 document structure. 369 The following example shows a simple YANG tree diagram: 371 +--rw top-level-config-container 372 | +--rw config-list* [key-name] 373 | +--rw key-name string 374 | +--rw optional-parm? string 375 | +--rw mandatory-parm identityref 376 | +--ro read-only-leaf string 377 +--ro top-level-nonconfig-container 378 +--ro nonconfig-list* [name] 379 +--ro name string 380 +--ro type string 382 4.4. Narrative Sections 384 The narrative part MUST include an overview section that describes 385 the scope and field of application of the module(s) defined by the 386 specification and that specifies the relationship (if any) of these 387 modules to other standards, particularly to standards containing 388 other YANG modules. The narrative part SHOULD include one or more 389 sections to briefly describe the structure of the modules defined in 390 the specification. 392 If the module(s) defined by the specification imports definitions 393 from other modules (except for those defined in the 394 [I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always 395 implemented in conjunction with other modules, then those facts MUST 396 be noted in the overview section, as MUST be noted any special 397 interpretations of definitions in other modules. 399 4.5. Definitions Section 401 This section contains the module(s) defined by the specification. 402 These modules SHOULD be written using the YANG syntax defined in 403 [I-D.ietf-netmod-rfc6020bis]. YANG 1.0 [RFC6020] MAY be used if no 404 YANG 1.1 constructs or semantics are needed in the module. 406 A YIN syntax version of the module MAY also be present in the 407 document. There MAY also be other types of modules present in the 408 document, such as SMIv2, which are not affected by these guidelines. 410 Note that all YANG statements within a YANG module are considered 411 normative, if the module itself is considered normative, and not an 412 example module. The use of keywords defined in [RFC2119] apply to 413 YANG description statements in normative modules exactly as they 414 would in any other normative section. 416 Example YANG modules MUST NOT contain any normative text, including 417 any reserved words from [RFC2119]. 419 See Section 5 for guidelines on YANG usage. 421 4.6. Security Considerations Section 423 Each specification that defines one or more modules MUST contain a 424 section that discusses security considerations relevant to those 425 modules. 427 This section MUST be patterned after the latest approved template 428 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 429 yang-security-guidelines). Section 7.1 contains the security 430 considerations template dated 2013-05-08. Authors MUST check the 431 webpage at the URL listed above in case there is a more recent 432 version available. 434 In particular: 436 o Writable data nodes that could be especially disruptive if abused 437 MUST be explicitly listed by name and the associated security 438 risks MUST be explained. 440 o Readable data nodes that contain especially sensitive information 441 or that raise significant privacy concerns MUST be explicitly 442 listed by name and the reasons for the sensitivity/privacy 443 concerns MUST be explained. 445 o Operations (i.e., YANG 'rpc' statements) that are potentially 446 harmful to system behavior or that raise significant privacy 447 concerns MUST be explicitly listed by name and the reasons for the 448 sensitivity/privacy concerns MUST be explained. 450 4.7. IANA Considerations Section 452 In order to comply with IESG policy as set forth in 453 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 454 is submitted to the IESG for publication MUST contain an IANA 455 Considerations section. The requirements for this section vary 456 depending on what actions are required of the IANA. If there are no 457 IANA considerations applicable to the document, then the IANA 458 Considerations section stating that there are no actions is removed 459 by the RFC Editor before publication. Refer to the guidelines in 460 [RFC5226] for more details. 462 4.7.1. Documents that Create a New Namespace 464 If an Internet-Draft defines a new namespace that is to be 465 administered by the IANA, then the document MUST include an IANA 466 Considerations section that specifies how the namespace is to be 467 administered. 469 Specifically, if any YANG module namespace statement value contained 470 in the document is not already registered with IANA, then a new YANG 471 Namespace registry entry MUST be requested from the IANA. The 472 [I-D.ietf-netmod-rfc6020bis] specification includes the procedure for 473 this purpose in its IANA Considerations section. 475 4.7.2. Documents that Extend an Existing Namespace 477 It is possible to extend an existing namespace using a YANG submodule 478 that belongs to an existing module already administered by IANA. In 479 this case, the document containing the main module MUST be updated to 480 use the latest revision of the submodule. 482 4.8. Reference Sections 484 For every import or include statement that appears in a module 485 contained in the specification, which identifies a module in a 486 separate document, a corresponding normative reference to that 487 document MUST appear in the Normative References section. The 488 reference MUST correspond to the specific module version actually 489 used within the specification. 491 For every normative reference statement that appears in a module 492 contained in the specification, which identifies a separate document, 493 a corresponding normative reference to that document SHOULD appear in 494 the Normative References section. The reference SHOULD correspond to 495 the specific document version actually used within the specification. 496 If the reference statement identifies an informative reference, which 497 identifies a separate document, a corresponding informative reference 498 to that document MAY appear in the Informative References section. 500 4.9. Validation Tools 502 All modules need to be validated before submission in an Internet 503 Draft. The 'pyang' YANG compiler is freely available from github: 505 https://github.com/mbj4668/pyang 507 If the 'pyang' compiler is used, then the "--ietf" command line 508 option SHOULD be used to identify any IETF guideline issues. 510 4.10. Module Extraction Tools 512 A version of 'rfcstrip' is available which will extract YANG modules 513 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 514 YANG module extraction is freely available: 516 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 518 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 520 can be extracted correctly. 522 5. YANG Usage Guidelines 524 In general, modules in IETF Standards Track specifications MUST 525 comply with all syntactic and semantic requirements of YANG 526 [I-D.ietf-netmod-rfc6020bis]. The guidelines in this section are 527 intended to supplement the YANG specification, which is intended to 528 define a minimum set of conformance requirements. 530 In order to promote interoperability and establish a set of practices 531 based on previous experience, the following sections establish usage 532 guidelines for specific YANG constructs. 534 Only guidelines that clarify or restrict the minimum conformance 535 requirements are included here. 537 5.1. Module Naming Conventions 539 Normative modules contained in Standards Track documents MUST be 540 named according to the guidelines in the IANA Considerations section 541 of [I-D.ietf-netmod-rfc6020bis]. 543 A distinctive word or acronym (e.g., protocol name or working group 544 acronym) SHOULD be used in the module name. If new definitions are 545 being defined to extend one or more existing modules, then the same 546 word or acronym should be reused, instead of creating a new one. 548 All published module names MUST be unique. For a YANG module 549 published in an RFC, this uniqueness is guaranteed by IANA. For 550 unpublished modules, the authors need to check that no other work in 551 progress is using the same module name. 553 Example modules are non-normative, and SHOULD be named with the 554 prefix "example-". 556 It is suggested that a stable prefix be selected representing the 557 entire organization. All normative YANG modules published by the 558 IETF MUST begin with the prefix "ietf-". Another standards 559 organization, such as the IEEE, might use the prefix "ieee-" for all 560 YANG modules. 562 Once a module name is published, it MUST NOT be reused, even if the 563 RFC containing the module is reclassified to 'Historic' status. A 564 module name cannot be changed in YANG, and this would be treated as a 565 a new module, not a name change. 567 5.2. Prefixes 569 All YANG definitions are scoped by the module containing the 570 definition being referenced. This allows definitions from multiple 571 modules to be used, even if the names are not unique. In the example 572 below, the identifier "foo" is used in all 3 modules: 574 module example-foo { 575 namespace "http://example.com/ns/foo"; 576 prefix f; 578 container foo; 579 } 581 module example-bar { 582 namespace "http://example.com/ns/bar"; 583 prefix b; 585 typedef foo { type uint32; } 586 } 588 module example-one { 589 namespace "http://example.com/ns/one"; 590 prefix one; 591 import example-foo { prefix f; } 592 import example-bar { prefix b; } 594 augment "/f:foo" { 595 leaf foo { type b:foo; } 596 } 597 } 599 YANG defines the following rules for prefix usage: 601 o Prefixes are never allowed for built in data types and YANG 602 keywords. 604 o A prefix MUST be used for any external statement (i.e., a 605 statement defined with the YANG "extension" statement) 607 o The proper module prefix MUST be used for all identifiers imported 608 from other modules 610 o The proper module prefix MUST be used for all identifiers included 611 from a submodule. 613 The following guidelines apply to prefix usage of the current (local) 614 module: 616 o The local module prefix SHOULD be used instead of no prefix in all 617 path expressions. 619 o The local module prefix MUST be used instead of no prefix in all 620 "default" statements for an "identityref" or "instance-identifier" 621 data type 623 o The local module prefix MAY be used for references to typedefs, 624 groupings, extensions, features, and identities defined in the 625 module. 627 Prefix values SHOULD be short, but also likely to be unique. Prefix 628 values SHOULD NOT conflict with known modules that have been 629 previously published. 631 5.3. Identifiers 633 Identifiers for all YANG identifiers in published modules MUST be 634 between 1 and 64 characters in length. These include any construct 635 specified as an 'identifier-arg-str' token in the ABNF in Section 13 636 of [I-D.ietf-netmod-rfc6020bis]. 638 5.3.1. Identifier Naming Conventions 640 Identifiers SHOULD follow a consistent naming pattern throughout the 641 module. Only lower-case letters, numbers, and dashes SHOULD be used 642 in identifier names. Upper-case characters and the underscore 643 character MAY be used if the identifier represents a well-known value 644 that uses these characters. 646 Identifiers SHOULD include complete words and/or well-known acronyms 647 or abbreviations. Child nodes within a container or list SHOULD NOT 648 replicate the parent identifier. YANG identifiers are hierarchical 649 and are only meant to be unique within the the set of sibling nodes 650 defined in the same module namespace. 652 It is permissible to use common identifiers such as "name" or "id" in 653 data definition statements, especially if these data nodes share a 654 common data type. 656 Identifiers SHOULD NOT carry any special semantics that identify data 657 modelling properties. Only YANG statements and YANG extension 658 statements are designed to convey machine readable data modelling 659 properties. For example, naming an object "config" or "state" does 660 not change whether it is configuration data or state data. Only 661 defined YANG statements or YANG extension statements can be used to 662 assign semantics in a machine readable format in YANG. 664 5.4. Defaults 666 In general, it is suggested that substatements containing very common 667 default values SHOULD NOT be present. The following substatements 668 are commonly used with the default value, which would make the module 669 difficult to read if used everywhere they are allowed. 671 +--------------+---------------+ 672 | Statement | Default Value | 673 +--------------+---------------+ 674 | config | true | 675 | mandatory | false | 676 | max-elements | unbounded | 677 | min-elements | 0 | 678 | ordered-by | system | 679 | status | current | 680 | yin-element | false | 681 +--------------+---------------+ 683 Statement Defaults 685 5.5. Conditional Statements 687 A module may be conceptually partitioned in several ways, using the 688 'if-feature' and/or 'when' statements. 690 Data model designers need to carefully consider all modularity 691 aspects, including the use of YANG conditional statements. 693 If a data definition is optional, depending on server support for a 694 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 695 be defined to indicate that the NETCONF capability is supported 696 within the data model. 698 If any notification data, or any data definition, for a non- 699 configuration data node is not mandatory, then the server may or may 700 not be required to return an instance of this data node. If any 701 conditional requirements exist for returning the data node in a 702 notification payload or retrieval request, they MUST be documented 703 somewhere. For example, a 'when' or 'if-feature' statement could 704 apply to the data node, or the conditional requirements could be 705 explained in a 'description' statement within the data node or one of 706 its ancestors (if any). 708 If any 'if-feature' statements apply to a list node, then the same 709 'if-feature' statements MUST apply to any key leaf nodes for the 710 list. There MUST NOT be any 'if-feature' statements applied to any 711 key leaf that do not also apply to the parent list node. 713 There SHOULD NOT be any 'when' statements applied to a key leaf node. 714 It is possible that a 'when' statement for an ancestor node of a key 715 leaf will have the exact node-set result as the key leaf. In such a 716 case, the 'when' statement for the key leaf is redundant and SHOULD 717 be avoided. 719 5.6. XPath Usage 721 This section describes guidelines for using the XML Path Language 722 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 724 5.6.1. XPath Evaluation Contexts 726 YANG defines 5 separate contexts for evaluation of XPath statements: 728 1) The "running" datastore: collection of all YANG configuration data 729 nodes. The document root is the conceptual container, (e.g., 730 "config" in the "edit-config" operation), which is the parent of all 731 top-level data definition statements with a "config" statement value 732 of "true". 734 2) State data + the "running" datastore: collection of all YANG data 735 nodes. The document root is the conceptual container, parent of all 736 top-level data definition statements. 738 3) Notification: an event notification document. The document root 739 is the notification element. 741 4) RPC Input: The document root is the conceptual "input" node, which 742 is the parent of all RPC input parameter definitions. 744 5) RPC Output: The document root is the conceptual "output" node, 745 which is the parent of all RPC output parameter definitions. 747 Note that these XPath contexts cannot be mixed. For example, a 748 "when" statement in a notification context cannot reference 749 configuration data. 751 notification foo { 752 leaf mtu { 753 // NOT OK because when-stmt context is this notification 754 when "/if:interfaces/if:interface[name='eth0']"; 755 type leafref { 756 // OK because path-stmt has a different context 757 path "/if:interfaces/if:interface/if:mtu"; 758 } 759 } 760 } 762 It is especially important to consider the XPath evaluation context 763 for XPath expressions defined in groupings. An XPath expression 764 defined in a grouping may not be portable, meaning it cannot be used 765 in multiple contexts and produce proper results. 767 If the XPath expressions defined in a grouping are intended for a 768 particular context, then this context SHOULD be identified in the 769 "description" statement for the grouping. 771 5.6.2. Function Library 773 The 'position' and 'last' functions SHOULD NOT be used. This applies 774 to implicit use of the 'position' function as well (e.g., 775 '//chapter[42]'). A server is only required to maintain the relative 776 XML document order of all instances of a particular user-ordered list 777 or leaf-list. The 'position' and 'last' functions MAY be used if 778 they are evaluated in a context where the context node is a user- 779 ordered 'list' or 'leaf-list'. 781 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 782 present in YANG documents so this function has no meaning. The YANG 783 compiler SHOULD return an empty string for this function. 785 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 786 Expanded names in XPath are different than YANG. A specific 787 canonical representation of a YANG expanded name does not exist. 789 The 'lang' function SHOULD NOT be used. This function does not apply 790 to YANG because there is no 'lang' attribute set with the document. 791 The YANG compiler SHOULD return 'false' for this function. 793 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 794 functions SHOULD NOT be used if the argument is a node-set. If so, 795 the function result will be determined by the document order of the 796 node-set. Since this order can be different on each server, the 797 function results can also be different. Any function call that 798 implicitly converts a node-set to a string will also have this issue. 800 The 'local-name' function SHOULD NOT be used to reference local names 801 outside of the YANG module defining the must or when expression 802 containing the 'local-name' function. Example of a local-name 803 function that should not be used: 805 /*[local-name()='foo'] 807 5.6.3. Axes 809 The 'attribute' and 'namespace' axes are not supported in YANG, and 810 MAY be empty in a NETCONF server implementation. 812 The 'preceding', and 'following' axes SHOULD NOT be used. These 813 constructs rely on XML document order within a NETCONF server 814 configuration database, which may not be supported consistently or 815 produce reliable results across implementations. Predicate 816 expressions based on static node properties (e.g., element name or 817 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 818 'preceding' and 'following' axes MAY be used if document order is not 819 relevant to the outcome of the expression (e.g., check for global 820 uniqueness of a parameter value). 822 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 823 however they MAY be used if document order is not relevant to the 824 outcome of the expression. 826 A server is only required to maintain the relative XML document order 827 of all instances of a particular user-ordered list or leaf-list. The 828 'preceding-sibling' and 'following-sibling' axes MAY be used if they 829 are evaluated in a context where the context node is a user-ordered 830 'list' or 'leaf-list'. 832 5.6.4. Types 834 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 835 be used within numeric or boolean expressions. There are boundary 836 conditions in which the translation from the YANG 64-bit type to an 837 XPath number can cause incorrect results. Specifically, an XPath 838 'double' precision floating point number cannot represent very large 839 positive or negative 64-bit numbers because it only provides a total 840 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 841 used in numeric expressions if the value can be represented with no 842 more than 53 bits of precision. 844 Data modelers need to be careful not to confuse the YANG value space 845 and the XPath value space. The data types are not the same in both, 846 and conversion between YANG and XPath data types SHOULD be considered 847 carefully. 849 Explicit XPath data type conversions MAY be used (e.g., 'string', 850 'boolean', or 'number' functions), instead of implicit XPath data 851 type conversions. 853 XPath expressions that contain a literal value representing a YANG 854 identity SHOULD always include the declared prefix of the module 855 where the identity is defined. 857 XPath expressions for 'when' statements SHOULD NOT reference the 858 context node or any descendant nodes of the context node. They MAY 859 reference descendant nodes if the 'when' statement is contained 860 within an 'augment' statement, and the referenced nodes are not 861 defined within the 'augment' statement. 863 Example: 865 augment "/rt:active-route/rt:input/rt:destination-address" { 866 when "rt:address-family='v4ur:ipv4-unicast'" { 867 description 868 "This augment is valid only for IPv4 unicast."; 869 } 870 // nodes defined here within the augment-stmt 871 // cannot be referenced in the when-stmt 872 } 874 5.6.5. Wildcards 876 It is possible to construct XPath expressions that will evaluate 877 differently when combined with several modules within a server 878 implementation, then when evaluated within the single module. This 879 is due to augmenting nodes from other modules. 881 Wildcard expansion is done within a server against all the nodes from 882 all namespaces, so it is possible for a 'must' or 'when' expression 883 that uses the '*' operator will always evaluate to false if processed 884 within a single YANG module. In such cases, the 'description' 885 statement SHOULD clarify that augmenting objects are expected to 886 match the wildcard expansion. 888 when /foo/services/*/active { 889 description 890 "No services directly defined in this module. 891 Matches objects that have augmented the services container."; 892 } 894 5.6.6. Boolean Expressions 896 The YANG "must" and "when" statements use an XPath boolean expression 897 to define the test condition for the statement. It is important to 898 specify these expressions in a way that will not cause inadvertent 899 changes in the result if the objects referenced in the expression are 900 updated in future revisions of the module. 902 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 903 to "one" or "three": 905 leaf foo1 { 906 type enumeration { 907 enum one; 908 enum two; 909 enum three; 910 } 911 } 913 leaf foo2 { 914 // INCORRECT 915 must "/f:foo1 != 'two'"; 916 type string; 917 } 919 leaf foo2 { 920 // CORRECT 921 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 922 type string; 923 } 925 In the next revision of the module, leaf "foo1" is extended with a 926 nem enum named "four": 928 leaf foo1 { 929 type enumeration { 930 enum one; 931 enum two; 932 enum three; 933 enum four; 934 } 935 } 937 Now the first XPath expression will allow the enum "four" to be 938 accepted in addition to the "one" and "three" enum values. 940 5.7. Lifecycle Management 942 The status statement MUST be present if its value is 'deprecated' or 943 'obsolete'. The status SHOULD NOT be changed from 'current' directly 944 to 'obsolete'. An object SHOULD be available for at least one year 945 with 'deprecated' status before it is changed to 'obsolete'. 947 The module or submodule name MUST NOT be changed, once the document 948 containing the module or submodule is published. 950 The module namespace URI value MUST NOT be changed, once the document 951 containing the module is published. 953 The revision-date substatement within the import statement SHOULD be 954 present if any groupings are used from the external module. 956 The revision-date substatement within the include statement SHOULD be 957 present if any groupings are used from the external submodule. 959 If submodules are used, then the document containing the main module 960 MUST be updated so that the main module revision date is equal or 961 more recent than the revision date of any submodule that is (directly 962 or indirectly) included by the main module. 964 Definitions for future use SHOULD NOT be specified in a module. Do 965 not specify placeholder objects like the "reserved" example below: 967 leaf reserved { 968 type string; 969 description 970 "This object has no purpose at this time, but a future 971 revision of this module might define a purpose 972 for this object."; 973 } 974 } 976 5.8. Module Header, Meta, and Revision Statements 978 For published modules, the namespace MUST be a globally unique URI, 979 as defined in [RFC3986]. This value is usually assigned by the IANA. 981 The organization statement MUST be present. If the module is 982 contained in a document intended for IETF Standards Track status, 983 then the organization SHOULD be the IETF working group chartered to 984 write the document. For other standards organizations, a similar 985 approach is also suggested. 987 The contact statement MUST be present. If the module is contained in 988 a document intended for Standards Track status, then the working 989 group web and mailing information MUST be present, and the main 990 document author or editor contact information SHOULD be present. If 991 additional authors or editors exist, their contact information MAY be 992 present. 994 The description statement MUST be present. For modules published 995 within IETF documents, the appropriate IETF Trust Copyright text MUST 996 be present, as described in Section 4.1. 998 If the module relies on information contained in other documents, 999 which are not the same documents implied by the import statements 1000 present in the module, then these documents MUST be identified in the 1001 reference statement. 1003 A revision statement MUST be present for each published version of 1004 the module. The revision statement MUST have a reference 1005 substatement. It MUST identify the published document that contains 1006 the module. Modules are often extracted from their original 1007 documents, and it is useful for developers and operators to know how 1008 to find the original source document in a consistent manner. The 1009 revision statement MAY have a description substatement. 1011 Each new revision MUST include a revision date that is higher than 1012 any other revision date in the module. The revision date does not 1013 need to be updated if the module contents do not change in the new 1014 document revision. 1016 It is acceptable to reuse the same revision statement within 1017 unpublished versions (i.e., Internet-Drafts), but the revision date 1018 MUST be updated to a higher value each time the Internet-Draft is re- 1019 posted. 1021 5.9. Namespace Assignments 1023 It is RECOMMENDED that only valid YANG modules be included in 1024 documents, whether or not they are published yet. This allows: 1026 o the module to compile correctly instead of generating disruptive 1027 fatal errors. 1029 o early implementors to use the modules without picking a random 1030 value for the XML namespace. 1032 o early interoperability testing since independent implementations 1033 will use the same XML namespace value. 1035 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1036 provided for the namespace statement in a YANG module. A value 1037 SHOULD be selected that is not likely to collide with other YANG 1038 namespaces. Standard module names, prefixes, and URI strings already 1039 listed in the YANG Module Registry MUST NOT be used. 1041 A standard namespace statement value SHOULD have the following form: 1043 : 1045 The following URN prefix string SHOULD be used for published and 1046 unpublished YANG modules: 1048 urn:ietf:params:xml:ns:yang: 1050 The following example URNs would be valid namespace statement values 1051 for Standards Track modules: 1053 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1055 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1057 urn:ietf:params:xml:ns:yang:ietf-netconf 1059 Note that a different URN prefix string SHOULD be used for non- 1060 Standards-Track modules. The string SHOULD be selected according to 1061 the guidelines in [I-D.ietf-netmod-rfc6020bis]. 1063 The following examples are for non-Standards-Track modules. The 1064 domain "example.com" SHOULD be used in all namespace URIs for example 1065 modules. 1067 http://example.com/ns/example-interfaces 1069 http://example.com/ns/example-system 1071 5.10. Top-Level Data Definitions 1073 The top-level data organization SHOULD be considered carefully, in 1074 advance. Data model designers need to consider how the functionality 1075 for a given protocol or protocol family will grow over time. 1077 The separation of configuration data and operational data SHOULD be 1078 considered carefully. It is often useful to define separate top- 1079 level containers for configuration and non-configuration data. 1081 The number of top-level data nodes within a module SHOULD be 1082 minimized. It is often useful to retrieve related information within 1083 a single subtree. If data is too distributed, is becomes difficult 1084 to retrieve all at once. 1086 The names and data organization SHOULD reflect persistent 1087 information, such as the name of a protocol. The name of the working 1088 group SHOULD NOT be used because this may change over time. 1090 A mandatory database data definition is defined as a node that a 1091 client must provide for the database to be valid. The server is not 1092 required to provide a value. 1094 Top-level database data definitions MUST NOT be mandatory. If a 1095 mandatory node appears at the top level, it will immediately cause 1096 the database to be invalid. This can occur when the server boots or 1097 when a module is loaded dynamically at runtime. 1099 5.11. Data Types 1101 Selection of an appropriate data type (i.e., built-in type, existing 1102 derived type, or new derived type) is very subjective, and therefore 1103 few requirements can be specified on that subject. 1105 Data model designers SHOULD use the most appropriate built-in data 1106 type for the particular application. 1108 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1109 'int64') SHOULD NOT be used unless negative values are allowed for 1110 the desired semantics. 1112 5.11.1. Fixed Value Extensibility 1114 If the set of values is fixed and the data type contents are 1115 controlled by a single naming authority, then an enumeration data 1116 type SHOULD be used. 1118 leaf foo { 1119 type enumeration { 1120 enum one; 1121 enum two; 1122 } 1123 } 1125 If extensibility of enumerated values is required, then the 1126 'identityref' data type SHOULD be used instead of an enumeration or 1127 other built-in type. 1129 identity foo-type { 1130 description "Base for the extensible type"; 1131 } 1133 identity one { 1134 base f:foo-type; 1135 } 1136 identity two { 1137 base f:foo-type; 1138 } 1140 leaf foo { 1141 type identityref { 1142 base f:foo-type; 1143 } 1145 } 1147 Note that any module can declare an identity with base "foo-type" 1148 that is valid for the "foo" leaf. Identityref values are considered 1149 to be qualified names. 1151 5.11.2. Patterns and Ranges 1153 For string data types, if a machine-readable pattern can be defined 1154 for the desired semantics, then one or more pattern statements SHOULD 1155 be present. A single quoted string SHOULD be used to specify the 1156 pattern, since a double-quoted string can modify the content. 1158 The following typedef from [RFC6991] demonstrates the proper use of 1159 the "pattern" statement: 1161 typedef ipv4-address-no-zone { 1162 type inet:ipv4-address { 1163 pattern '[0-9\.]*'; 1164 } 1165 ... 1166 } 1168 For string data types, if the length of the string is required to be 1169 bounded in all implementations, then a length statement MUST be 1170 present. 1172 The following typedef from [RFC6991] demonstrates the proper use of 1173 the "length" statement: 1175 typedef yang-identifier { 1176 type string { 1177 length "1..max"; 1178 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1179 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1180 } 1181 ... 1182 } 1184 For numeric data types, if the values allowed by the intended 1185 semantics are different than those allowed by the unbounded intrinsic 1186 data type (e.g., 'int32'), then a range statement SHOULD be present. 1188 The following typedef from [RFC6991] demonstrates the proper use of 1189 the "range" statement: 1191 typedef dscp { 1192 type uint8 { 1193 range "0..63"; 1194 } 1195 ... 1196 } 1198 5.11.3. Enumerations and Bits 1200 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1201 or 'bit' SHOULD be documented. A separate description statement 1202 (within each 'enum' or 'bit' statement) SHOULD be present. 1204 leaf foo { 1205 // INCORRECT 1206 type enumeration { 1207 enum one; 1208 enum two; 1209 } 1210 description 1211 "The foo enum... 1212 one: The first enum 1213 two: The second enum"; 1214 } 1216 leaf foo { 1217 // CORRECT 1218 type enumeration { 1219 enum one { 1220 description "The first enum"; 1221 } 1222 enum two { 1223 description "The second enum"; 1224 } 1225 } 1226 description 1227 "The foo enum... "; 1228 } 1230 5.11.4. Union Types 1232 The YANG "union" type is evaluated by testing a value against each 1233 member type in the union. The first type definition that accepts a 1234 value as valid is the member type used. In general, member types 1235 SHOULD be ordered from most restrictive to least restrictive types. 1237 In the following example, the "enumeration" type will never be 1238 matched because the preceding "string" type will match everything. 1240 Incorrect: 1242 type union { 1243 type string; 1244 type enumeration { 1245 enum up; 1246 enum down; 1247 } 1248 } 1250 Correct: 1252 type union { 1253 type enumeration { 1254 enum up; 1255 enum down; 1256 } 1257 type string; 1258 } 1260 It is possible for different member types to match, depending on the 1261 input encoding format. In XML, all values are passed as string 1262 nodes, but in JSON there are different value types for numbers, 1263 booleans, and strings. 1265 In the following example, a JSON numeric value will always be matched 1266 by the "int32" type but in XML the string value representing a number 1267 will be matched by the "string" type. The second version will match 1268 the "int32" member type no matter how the input is encoded. 1270 Incorrect: 1272 type union { 1273 type string; 1274 type int32; 1275 } 1277 Correct: 1279 type union { 1280 type int32; 1281 type string; 1282 } 1284 5.12. Reusable Type Definitions 1286 If an appropriate derived type exists in any standard module, such as 1287 [RFC6991], then it SHOULD be used instead of defining a new derived 1288 type. 1290 If an appropriate units identifier can be associated with the desired 1291 semantics, then a units statement SHOULD be present. 1293 If an appropriate default value can be associated with the desired 1294 semantics, then a default statement SHOULD be present. 1296 If a significant number of derived types are defined, and it is 1297 anticipated that these data types will be reused by multiple modules, 1298 then these derived types SHOULD be contained in a separate module or 1299 submodule, to allow easier reuse without unnecessary coupling. 1301 The description statement MUST be present. 1303 If the type definition semantics are defined in an external document 1304 (other than another YANG module indicated by an import statement), 1305 then the reference statement MUST be present. 1307 5.13. Reusable Groupings 1309 A reusable grouping is a YANG grouping that can be imported by 1310 another module, and is intended for use by other modules. This is 1311 not the same as a grouping that is used within the module it is 1312 defined, but happens to be exportable to another module because it is 1313 defined at the top-level of the YANG module. 1315 The following guidelines apply to reusable groupings, in order to 1316 make them as robust as possible: 1318 o Clearly identify the purpose of the grouping in the "description" 1319 statement. 1321 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1322 output, notification, config=true data nodes, and all data nodes). 1323 Clearly identify which XPath contexts are applicable or excluded 1324 for the grouping. 1326 o Do not reference data outside the grouping in any "path", "must", 1327 or "when" statements. 1329 o Do not include a "default" sub-statement on a leaf or choice 1330 unless the value applies on all possible contexts. 1332 o Do not include a "config" sub-statement on a data node unless the 1333 value applies on all possible contexts. 1335 o Clearly identify any external dependencies in the grouping 1336 "description" statement, such as nodes referenced by absolute path 1337 from a "path", "must", or "when" statement. 1339 5.14. Data Definitions 1341 The description statement MUST be present in the following YANG 1342 statements: 1344 o anyxml 1346 o augment 1348 o choice 1350 o container 1352 o extension 1354 o feature 1356 o grouping 1358 o identity 1360 o leaf 1362 o leaf-list 1364 o list 1366 o notification 1368 o rpc 1370 o typedef 1372 If the data definition semantics are defined in an external document, 1373 (other than another YANG module indicated by an import statement), 1374 then a reference statement MUST be present. 1376 The 'anyxml' construct may be useful to represent an HTML banner 1377 containing markup elements, such as '<b>' and '</b>', and 1378 MAY be used in such cases. However, this construct SHOULD NOT be 1379 used if other YANG data node types can be used instead to represent 1380 the desired syntax and semantics. 1382 It has been found that the 'anyxml' statement is not implemented 1383 consistently across all servers. It is possible that mixed mode XML 1384 will not be supported, or configuration anyxml nodes will not 1385 supported. 1387 If there are referential integrity constraints associated with the 1388 desired semantics that can be represented with XPath, then one or 1389 more 'must' statements SHOULD be present. 1391 For list and leaf-list data definitions, if the number of possible 1392 instances is required to be bounded for all implementations, then the 1393 max-elements statements SHOULD be present. 1395 If any 'must' or 'when' statements are used within the data 1396 definition, then the data definition description statement SHOULD 1397 describe the purpose of each one. 1399 The "choice" statement is allowed to be directly present within a 1400 "case" statement in YANG 1.1. This needs to be considered carefully. 1401 Consider simply including the nested "choice" as additional "case" 1402 statements within the parent "choice" statement. Note that the 1403 "mandatory" and "default" statements within a nested "choice" 1404 statement only apply if the "case" containing the nested "choice" 1405 statement is first selected. 1407 5.14.1. Non-Presence Containers 1409 A non-presence container is used to organize data into specific 1410 subtrees. It is not intended to have semantics within the data model 1411 beyond this purpose, although YANG allows it (e.g., "must" statement 1412 within the non-presence container). 1414 Example using container wrappers: 1416 container top { 1417 container foos { 1418 list foo { ... } 1419 } 1420 container bars { 1421 list bar { ... } 1422 } 1423 } 1425 Example without container wrappers: 1427 container top { 1428 list foo { ... } 1429 list bar { ... } 1430 } 1432 Use of non-presence containers to organize data is a subjective 1433 matter similar to use of sub-directories in a file system. The 1434 NETCONF and RESTCONF protocols do not currently support the ability 1435 to delete all list (or leaf-list) entries at once. This deficiency 1436 is sometimes avoided by use of a parent container (i.e., deleting the 1437 container also removes all child entries). 1439 5.14.2. Top-Level Data Nodes 1441 Use of top-level objects needs to be considered carefully 1443 -top-level siblings are not ordered -top-level siblings not are not 1444 static, and depends on the modules that are loaded 1446 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1447 treated as a content-match node for all top-level-siblings 1449 o a top-level list with many instances may impact performance 1451 5.15. Operation Definitions 1453 If the operation semantics are defined in an external document (other 1454 than another YANG module indicated by an import statement), then a 1455 reference statement MUST be present. 1457 If the operation impacts system behavior in some way, it SHOULD be 1458 mentioned in the description statement. 1460 If the operation is potentially harmful to system behavior in some 1461 way, it MUST be mentioned in the Security Considerations section of 1462 the document. 1464 5.16. Notification Definitions 1466 The description statement MUST be present. 1468 If the notification semantics are defined in an external document 1469 (other than another YANG module indicated by an import statement), 1470 then a reference statement MUST be present. 1472 If the notification refers to a specific resource instance, then this 1473 instance SHOULD be identified in the notification data. This is 1474 usually done by including 'leafref' leaf nodes with the key leaf 1475 values for the resource instance. For example: 1477 notification interface-up { 1478 description "Sent when an interface is activated."; 1479 leaf name { 1480 type leafref { 1481 path "/if:interfaces/if:interface/if:name"; 1482 } 1483 } 1484 } 1486 Note that there are no formal YANG statements to identify any data 1487 node resources associated with a notification. The description 1488 statement for the notification SHOULD specify if and how the 1489 notification identifies any data node resources associated with the 1490 specific event. 1492 5.17. Feature Definitions 1494 The YANG "feature" statement is used to define a label for a set of 1495 optional functionality within a module. The "if-feature" statement 1496 is used in the YANG statements associated with a feature. 1498 The set of YANG features available in a module should be considered 1499 carefully. The description-stmt within a feature-stmt MUST specify 1500 any interactions with other features. 1502 If there is a large set of objects associated with a YANG feature, 1503 then consider moving those objects to a separate module, instead of 1504 using a YANG feature. Note that the set of features within a module 1505 is easily discovered by the reader, but the set of related modules 1506 within the entire YANG library is not as easy to identity. Module 1507 names with a common prefix can help readers identity the set of 1508 related modules, but this assumes the reader will have discovered and 1509 installed all the relevant modules. 1511 Another consideration for deciding whether to create a new module or 1512 add a YANG feature is the stability of the module in question. It 1513 may be desirable to have a stable base module that is not changed 1514 frequently. If new functionality is placed in a separate module, 1515 then the base module does not need to be republished. If it is 1516 designed as a YANG feature then the module will need to be 1517 republished. 1519 If one feature requires implementation of another feature, then an 1520 "if-feature" statement SHOULD be used in the dependent "feature" 1521 statement. 1523 For example, feature2 requires implementation of feature1: 1525 feature feature1 { 1526 description "Some protocol feature"; 1527 } 1529 feature feature2 { 1530 if-feature "feature1"; 1531 description "Another protocol feature"; 1532 } 1534 5.18. YANG Data Node Constraints 1536 5.18.1. Controlling Quantity 1538 The "min-elements" and "max-elements" statements can be use to 1539 control how many list or leaf-list instances are required for a 1540 particular data node. YANG constraint statements SHOULD be used to 1541 identify conditions that apply to all implementations of the data 1542 model. If platform-specific limitations (e.g., the "max-elements" 1543 supported for a particular list) are relevant to operations, then a 1544 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1545 used to identify the limit. 1547 5.18.2. must vs. when 1549 The "must" and "when" YANG statements are used to provide cross- 1550 object referential tests. They have very different behavior. The 1551 "when" statement causes data node instances to be silently deleted as 1552 soon as the condition becomes false. A false "when" expression is 1553 not considered to be an error. 1555 The "when" statement SHOULD be used together with the "augment" or 1556 "uses" statements to achieve conditional model composition. The 1557 condition SHOULD be based on static properties of the augmented entry 1558 (e.g., list key leafs). 1560 The "must" statement causes a datastore validation error if the 1561 condition is false. This statement SHOULD be used for enforcing 1562 parameter value restrictions that involve more than one data node 1563 (e.g., end-time parameter must be after the start-time parameter). 1565 5.19. Augment Statements 1567 The YANG "augment" statement is used to define a set of data 1568 definition statements that will be added as child nodes of a target 1569 data node. The module namespace for these data nodes will be the 1570 augmenting module, not the augmented module. 1572 A top-level "augment" statement SHOULD NOT be used if the target data 1573 node is in the same module or submodule as the evaluated "augment" 1574 statement. The data definition statements SHOULD be added inline 1575 instead. 1577 5.19.1. Conditional Augment Statements 1579 The "augment" statement is often used together with the "when" 1580 statement and/or "if-feature" statement to make the augmentation 1581 conditional on some portion of the data model. 1583 The following example from [RFC7223] shows how a conditional 1584 container called "ethernet" is added to the "interface" list only for 1585 entries of the type "ethernetCsmacd". 1587 augment "/if:interfaces/if:interface" { 1588 when "if:type = 'ianaift:ethernetCsmacd'"; 1590 container ethernet { 1591 leaf duplex { 1592 ... 1593 } 1594 } 1595 } 1597 5.19.2. Conditionally Mandatory Data Definition Statements 1599 YANG has very specific rules about how configuration data can be 1600 updated in new releases of a module. These rules allow an "old 1601 client" to continue interoperating with a "new server". 1603 If data nodes are added to an existing entry, the old client MUST NOT 1604 be required to provide any mandatory parameters that were not in the 1605 original module definition. 1607 It is possible to add conditional augment statements such that the 1608 old client would not know about the new condition, and would not 1609 specify the new condition. The conditional augment statement can 1610 contain mandatory objects only if the condition is false unless 1611 explicitly requested by the client. 1613 Only a conditional augment statement that uses the "when" statement 1614 form of condition can be used in this manner. The YANG features 1615 enabled on the server cannot be controlled by the client in any way, 1616 so it is not safe to add mandatory augmenting data nodes based on the 1617 "if-feature" statement. 1619 The XPath "when" statement condition MUST NOT reference data outside 1620 of target data node because the client does not have any control over 1621 this external data. 1623 In the following dummy example, it is OK to augment the "interface" 1624 entry with "mandatory-leaf" because the augmentation depends on 1625 support for "some-new-iftype". The old client does not know about 1626 this type so it would never select this type, and therefore not be 1627 adding a mandatory data node. 1629 module example-module { 1630 namespace "http://example.com/ns/example-module"; 1631 prefix mymod; 1633 import iana-if-type { prefix iana; } 1634 import ietf-interfaces { prefix if; } 1636 identity some-new-iftype { 1637 base iana:iana-interface-type; 1638 } 1640 augment "/if:interfaces/if:interface" { 1641 when "if:type = 'mymod:some-new-iftype'"; 1643 leaf mandatory-leaf { 1644 mandatory true; 1645 ... 1646 } 1647 } 1648 } 1650 Note that this practice is safe only for creating data resources. It 1651 is not safe for replacing or modifying resources if the client does 1652 not know about the new condition. The YANG data model MUST be 1653 packaged in a way that requires the client to be aware of the 1654 mandatory data nodes if it is aware of the condition for this data. 1655 In the example above, the "some-new-iftype" identity is defined in 1656 the same module as the "mandatory-leaf" data definition statement. 1658 This practice is not safe for identities defined in a common module 1659 such as "iana-if-type" because the client is not required to know 1660 about "my-module" just because it knows about the "iana-if-type" 1661 module. 1663 5.20. Deviation Statements 1665 The YANG "deviation" statement cannot appear in IETF YANG modules, 1666 but it can be useful for documenting server capabilities. Deviation 1667 statements are not reusable and typically not shared across all 1668 platforms. 1670 There are several reasons that deviations might be needed in an 1671 implementation, e.g., an object cannot be supported on all platforms, 1672 or feature delivery is done in multiple development phases. 1673 Deviation statements can also be used to add annotations to a module, 1674 which does not affect the conformance requirements for the module. 1676 It is suggested that deviation statements be defined in separate 1677 modules from regular YANG definitions. This allows the deviations to 1678 be platform-specific and/or temporary. 1680 The order that deviation statements are evaluated can affect the 1681 result. Therefore multiple deviation statements in the same module, 1682 for the same target object, SHOULD NOT be used. 1684 The "max-elements" statement is intended to describe an architectural 1685 limit to the number of list entries. It is not intended to describe 1686 platform limitations. It is better to use a "deviation" statement 1687 for the platforms that have a hard resource limit. 1689 Example documenting platform resource limits: 1691 Wrong: (max-elements in the list itself) 1693 container backups { 1694 list backup { 1695 ... 1696 max-elements 10; 1697 ... 1698 } 1699 } 1701 Correct: (max-elements in a deviation) 1703 deviation /bk:backups/bk:backup { 1704 deviate add { 1705 max-elements 10; 1706 } 1707 } 1709 5.21. Extension Statements 1711 The YANG "extension" statement is used to specify external 1712 definitions. This appears in the YANG syntax as an 1713 "unknown-statement". Usage of extension statements in a published 1714 module needs to be considered carefully. 1716 The following guidelines apply to the usage of YANG extensions: 1718 o The semantics of the extension MUST NOT contradict any YANG 1719 statements. Extensions can add semantics not covered by the 1720 normal YANG statements. 1722 o The module containing the extension statement MUST clearly 1723 identify the conformance requirements for the extension. It 1724 should be clear whether all implementations of the YANG module 1725 containing the extension need to also implement the extension. If 1726 not, identify what conditions apply that would require 1727 implementation of the extension. 1729 o The extension MUST clearly identify where it can be used within 1730 other YANG statements. 1732 o The extension MUST clearly identify if YANG statements or other 1733 extensions are allowed or required within the extension as sub- 1734 statements. 1736 5.22. Data Correlation 1738 Data can be correlated in various ways, using common data types, 1739 common data naming, and common data organization. There are several 1740 ways to extend the functionality of a module, based on the degree of 1741 coupling between the old and new functionality: 1743 o inline: update the module with new protocol-accessible objects. 1744 The naming and data organization of the original objects is used. 1745 The new objects are in the original module namespace. 1747 o augment: create a new module with new protocol-accessible objects 1748 that augment the original data structure. The naming and data 1749 organization of the original objects is used. The new objects are 1750 in the new module namespace. 1752 o mirror: create new objects in a new module or the original module, 1753 except use new a naming scheme and data location. The naming can 1754 be coupled in different ways. Tight coupling is achieved with a 1755 "leafref" data type, with the "require-instance" sub-statement set 1756 to "true". This method SHOULD be used. 1758 If the new data instances are not limited to the values in use in the 1759 original data structure, then the "require-instance" sub-statement 1760 MUST be set to "false". Loose coupling is achieved by using key 1761 leafs with the same data type as the original data structure. This 1762 has the same semantics as setting the "require-instance" sub- 1763 statement to "false". 1765 It is sometimes useful to separate configuration and operational 1766 data, so that they do not not even share the exact same naming 1767 characteristics. The correlation between configuration the 1768 operational data that is affected by changes in configuration is a 1769 complex problem. There may not be a simple 1:1 relationship between 1770 a configuration data node and an operational data node. Further work 1771 is needed in YANG to clarify this relationship. Protocol work may 1772 also be needed to allow a client to retrieve this type of information 1773 from a server. At this time the best practice is to clearly document 1774 any relationship to other data structures in the "description" 1775 statement. 1777 5.23. Operational Data 1779 In YANG, any data that has a "config" statement value of "false" 1780 could be considered operational data. The relationship between 1781 configuration (i.e., "config" statement has a value of "true") and 1782 operational data can be complex. 1784 One challenge for client developers is determining if the configured 1785 value is being used, which requires the developer to know which 1786 operational data parameters are associated with the particular 1787 configuration object (or group of objects). 1789 In the simplest use-cases , there is no interaction between 1790 configuration and operational data. For example, the arbitrary 1791 administrative name or sequence number assigned to an access control 1792 rule. The configured value is always the value that is being used by 1793 the system. 1795 However, some configuration parameters interact with routing and 1796 other signalling protocols, such that the operational value in use by 1797 the system may not be the same as the configured value. Other 1798 parameters specify the desired state, but environmental and other 1799 factors can cause the actual state to be different. 1801 For example a "temperature" configuration setting only represents the 1802 desired temperature. An operational data parameter is needed that 1803 reports the actual temperature in order to determine if the cooling 1804 system is operating correctly. YANG has no mechanism other than the 1805 "description" statement to associate the desired temperature and the 1806 actual temperature. 1808 Careful consideration needs to be given to the location of 1809 operational data. It can either be located within the configuration 1810 subtree for which it applies, or it can be located outside the 1811 particular configuration subtree. Placing operational data within 1812 the configuration subtree is appropriate if the operational values 1813 can only exist if the configuration exists. 1815 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1816 are an example of a complex relationship between configuration and 1817 operational data. The operational values can include interface 1818 entries that have been discovered or initialized by the system. An 1819 interface may be in use that has not been configured at all. 1820 Therefore, the operational data for an interface cannot be located 1821 within the configuration for that same interface. 1823 Sometimes the configured value represents some sort of procedure to 1824 be followed, in which the system will select an actual value, based 1825 on protocol negotiation. 1827 leaf duplex-admin-mode { 1828 type enumeration { 1829 enum auto; 1830 enum half; 1831 enum full; 1832 } 1833 } 1835 leaf duplex-oper-mode { 1836 config false; 1837 type enumeration { 1838 enum half; 1839 enum full; 1840 } 1841 } 1843 For example a "duplex" mode configuration may be "auto" to auto- 1844 negotiate the actual value to be used. The operational parameter 1845 will never contain the value "auto". It will always contain the 1846 result of the auto-negotiation, such as "half" or "full". This is 1847 just one way in which the configuration data model is not exactly the 1848 same as the operational data model. Another is if the detailed 1849 properties of the data are different for configured vs. learned 1850 entries. 1852 If all the data model properties are aligned between configuration 1853 and operational data, then it can be useful to define the 1854 configuration parameters within a grouping, and then replicate that 1855 grouping within the operational data portion of the data model. 1857 grouping parms { 1858 // do not use config-stmt in any of the nodes 1859 // placed in this grouping 1860 } 1862 container foo { 1863 uses parms; // these are all config=true by default 1864 state { 1865 config false; // only exists if foo config exists 1866 uses parms; 1867 } 1868 } 1870 Note that this mechanism can also be used if the configuration and 1871 operational data are in separate sub-trees: 1873 container bar { // bar config can exist without bar-state 1874 config true; 1875 uses parms; 1876 } 1878 container bar-state { // bar-state can exist without bar 1879 config false; 1880 uses parms; 1881 } 1883 The need to replicate objects or define different operational data 1884 objects depends on the data model. It is not possible to define one 1885 approach that will be optimal for all data models. Designers SHOULD 1886 describe the relationship in detail between configuration objects and 1887 any associated operational data objects. The "description" 1888 statements for both the configuration and the operational data SHOULD 1889 be used for this purpose. 1891 5.24. Performance Considerations 1893 It is generally likely that certain YANG statements require more 1894 runtime resources than other statements. Although there are no 1895 performance requirements for YANG validation, the following 1896 information MAY be considered when designing YANG data models: 1898 o Lists are generally more expensive than containers 1900 o "when-stmt" evaluation is generally more expensive than 1901 "if-feature" or "choice" statements 1903 o "must" statement is generally more expensive than "min-entries", 1904 "max-entries", "mandatory", or "unique" statements 1906 o "identityref" leafs are generally more expensive than 1907 "enumeration" leafs 1909 o "leafref" and "instance-identifier" types with "require-instance" 1910 set to true are generally more expensive than if 1911 "require-instance" is set to false 1913 5.25. Open Systems Considerations 1915 A YANG module MUST NOT be designed such that the set of modules found 1916 on a server implementation can be predetermined in advance. Only the 1917 modules imported by a particular module can be assumed to be present 1918 in an implementation. An open system MAY include any combination of 1919 YANG modules. 1921 5.26. YANG 1.1 Guidelines 1923 The set of YANG 1.1 guidelines will grow as operational experience is 1924 gained with the new language features. This section contains an 1925 initial set of guidelines. 1927 5.26.1. Importing Multiple Revisions 1929 Standard modules SHOULD NOT import multiple revisions of the same 1930 module into a module. This MAY be done if the authors can 1931 demonstrate that the "avoided" definitions from the most recent of 1932 the multiple revisions are somehow broken or harmful to 1933 interoperability. 1935 5.26.2. Using Feature Logic 1937 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 1938 "description" statement SHOULD describe the "if-feature" logic in 1939 text, to help readers understand the module. 1941 YANG features SHOULD be used instead of the "when" statement, if 1942 possible. Features are advertised by the server and objects 1943 conditional by if-feature are conceptually grouped together. There 1944 is no such commonality supported for "when" statements. 1946 Features generally require less server implementation complexity and 1947 runtime resources than objects that use "when" statements. Features 1948 are generally static (i.e., set when module is loaded and not changed 1949 at runtime). However every client edit might cause a "when" 1950 statement result to change. 1952 5.26.3. anyxml vs. anydata 1954 The "anyxml" statement MUST NOT be used to represent a conceptual 1955 subtree of YANG data nodes. The "anydata" statement MUST be used for 1956 this purpose. 1958 5.26.4. action vs. rpc 1960 The use of "action" statements or "rpc" statements is a subjective 1961 design decision. RPC operations are not associated with any 1962 particular data node. Actions are associated with a specific data 1963 node definition. An "action" statement SHOULD be used if the 1964 protocol operation is specific to a subset of all data nodes instead 1965 of all possible data nodes. 1967 The same action name MAY be used in different definitions within 1968 different data node. For example, a "reset" action defined with a 1969 data node definition for an interface might have different parameters 1970 than for a power supply or a VLAN. The same action name SHOULD be 1971 used to represent similar semantics. 1973 The NETCONF Access Control Model (NACM) [RFC6536] does not support 1974 parameter access control for RPC operations. The user is given 1975 permission (or not) to invoke the RPC operation with any parameters. 1976 For example, if each client is only allowed to reset their own 1977 interface, then NACM cannot be used. 1979 For example, NACM cannot enforce access access control based on the 1980 value of the "interface" parameter, only the "reset" operation 1981 itself: 1983 rpc reset { 1984 input { 1985 leaf interface { 1986 type if:interface-ref; 1987 mandatory true; 1988 description "The interface to reset."; 1989 } 1990 } 1991 } 1993 However, NACM can enforce access access control for individual 1994 interface instances, using a "reset" action, If the user does not 1995 have read access to the specific "interface" instance, then it cannot 1996 invoke the "reset" action for that interface instance: 1998 container interfaces { 1999 list interface { 2000 ... 2001 action reset { } 2002 } 2003 } 2005 5.27. Updating YANG Modules (Published vs. Unpublished) 2007 YANG modules can change over time. Typically, new data model 2008 definitions are needed to support new features. YANG update rules 2009 defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be 2010 followed for published modules. They MAY be followed for unpublished 2011 modules. 2013 The YANG update rules only apply to published module revisions. Each 2014 organization will have their own way to identity published work which 2015 is considered to be stable, and unpublished work which is considered 2016 to be unstable. For example, in the IETF, the RFC document is used 2017 for published work, and the Internet-Draft is used for unpublished 2018 work. 2020 6. IANA Considerations 2022 This document registers one URI in the IETF XML registry [RFC3688]. 2024 The following registration has been made: 2026 URI: urn:ietf:params:xml:ns:yang:ietf-template 2028 Registrant Contact: The NETMOD WG of the IETF. 2030 XML: N/A, the requested URI is an XML namespace. 2032 Per this document, the following assignment has been made in the YANG 2033 Module Names Registry for the YANG module template in Appendix C. 2035 +-----------+-------------------------------------------+ 2036 | Field | Value | 2037 +-----------+-------------------------------------------+ 2038 | Name | ietf-template | 2039 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2040 | Prefix | temp | 2041 | Reference | RFC XXXX | 2042 +-----------+-------------------------------------------+ 2044 YANG Registry Assignment 2046 7. Security Considerations 2048 This document defines documentation guidelines for NETCONF content 2049 defined with the YANG data modeling language. The guidelines for how 2050 to write a Security Considerations section for a YANG module are 2051 defined in the online document 2053 http://trac.tools.ietf.org/area/ops/trac/wiki/ 2054 yang-security-guidelines 2056 This document does not introduce any new or increased security risks 2057 into the management system. 2059 The following section contains the security considerations template 2060 dated 2010-06-16. Be sure to check the webpage at the URL listed 2061 above in case there is a more recent version available. 2063 Each specification that defines one or more YANG modules MUST contain 2064 a section that discusses security considerations relevant to those 2065 modules. This section MUST be patterned after the latest approved 2066 template (available at 2068 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 2070 In particular, writable data nodes that could be especially 2071 disruptive if abused MUST be explicitly listed by name and the 2072 associated security risks MUST be spelled out. 2074 Similarly, readable data nodes that contain especially sensitive 2075 information or that raise significant privacy concerns MUST be 2076 explicitly listed by name and the reasons for the sensitivity/privacy 2077 concerns MUST be explained. 2079 Further, if new RPC operations have been defined, then the security 2080 considerations of each new RPC operation MUST be explained. 2082 7.1. Security Considerations Section Template 2084 X. Security Considerations 2086 The YANG module defined in this memo is designed to be accessed via 2087 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 2088 secure transport layer and the mandatory-to-implement secure 2089 transport is SSH [RFC6242]. 2091 -- if you have any writable data nodes (those are all the 2092 -- "config true" nodes, and remember, that is the default) 2093 -- describe their specific sensitivity or vulnerability. 2095 There are a number of data nodes defined in this YANG module which 2096 are writable/creatable/deletable (i.e., config true, which is the 2097 default). These data nodes may be considered sensitive or vulnerable 2098 in some network environments. Write operations (e.g., edit-config) 2099 to these data nodes without proper protection can have a negative 2100 effect on network operations. These are the subtrees and data nodes 2101 and their sensitivity/vulnerability: 2103 2105 -- for all YANG modules you must evaluate whether any readable data 2106 -- nodes (those are all the "config false" nodes, but also all other 2107 -- nodes, because they can also be read via operations like get or 2108 -- get-config) are sensitive or vulnerable (for instance, if they 2109 -- might reveal customer information or violate personal privacy 2110 -- laws such as those of the European Union if exposed to 2111 -- unauthorized parties) 2113 Some of the readable data nodes in this YANG module may be considered 2114 sensitive or vulnerable in some network environments. It is thus 2115 important to control read access (e.g., via get, get-config, or 2116 notification) to these data nodes. These are the subtrees and data 2117 nodes and their sensitivity/vulnerability: 2119 2121 -- if your YANG module has defined any rpc operations 2122 -- describe their specific sensitivity or vulnerability. 2124 Some of the RPC operations in this YANG module may be considered 2125 sensitive or vulnerable in some network environments. It is thus 2126 important to control access to these operations. These are the 2127 operations and their sensitivity/vulnerability: 2129 2131 8. Acknowledgments 2133 The structure and contents of this document are adapted from 2134 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2136 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2137 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 2138 contributions to this document. 2140 9. Changes Since RFC 6087 2142 The following changes have been made to the guidelines published in 2143 [RFC6087]: 2145 o Updated NETCONF reference from RFC 4741 to RFC 6241 2147 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 2149 o Updated YANG Types reference from RFC 6021 to RFC 6991 2151 o Updated obsolete URLs for IETF resources 2153 o Changed top-level data node guideline 2155 o Clarified XPath usage for a literal value representing a YANG 2156 identity 2158 o Clarified XPath usage for a when-stmt 2160 o Clarified XPath usage for 'proceeding-sibling' and 2161 'following-sibling' axes 2163 o Added terminology guidelines 2165 o Added YANG tree diagram definition and guideline 2167 o Updated XPath guidelines for type conversions and function library 2168 usage. 2170 o Updated data types section 2172 o Updated notifications section 2174 o Clarified conditional key leaf nodes 2176 o Clarify usage of 'uint64' and 'int64' data types 2178 o Added text on YANG feature usage 2180 o Added Identifier Naming Conventions 2182 o Clarified use of mandatory nodes with conditional augmentations 2184 o Clarified namespace and domain conventions for example modules 2186 o Added and convention 2187 o Added YANG 1.1 guidelines 2189 o Added Data Model Constraints section 2191 10. References 2193 10.1. Normative References 2195 [I-D.ietf-netmod-rfc6020bis] 2196 Bjorklund, M., "YANG - A Data Modeling Language for the 2197 Network Configuration Protocol (NETCONF)", 2198 draft-ietf-netmod-rfc6020bis-07 (work in progress), 2199 September 2015. 2201 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2202 Requirement Levels", BCP 14, RFC 2119, March 1997. 2204 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 2205 RFC 2223, October 1997. 2207 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2208 January 2004. 2210 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2211 Resource Identifier (URI): Generic Syntax", STD 66, 2212 RFC 3986, January 2005. 2214 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2215 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2217 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 2218 and Boilerplates", RFC 5741, December 2009. 2220 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2221 Network Configuration Protocol (NETCONF)", RFC 6020, 2222 October 2010. 2224 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2225 and A. Bierman, Ed., "Network Configuration Protocol 2226 (NETCONF)", RFC 6241, June 2011. 2228 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2229 July 2013. 2231 [W3C.REC-xpath-19991116] 2232 Clark, J. and S. DeRose, "XML Path Language (XPath) 2233 Version 1.0", World Wide Web Consortium 2234 Recommendation REC-xpath-19991116, November 1999, 2235 . 2237 10.2. Informative References 2239 [RFC-STYLE] 2240 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2241 Style", September 2009, 2242 . 2244 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2245 Documents", BCP 111, RFC 4181, September 2005. 2247 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2248 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2249 May 2008. 2251 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2252 Data Model Documents", RFC 6087, January 2011. 2254 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2255 Protocol (NETCONF) Access Control Model", RFC 6536, 2256 March 2012. 2258 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2259 Management", RFC 7223, May 2014. 2261 Appendix A. Change Log 2263 -- RFC Ed.: remove this section before publication. 2265 A.1. v06 to v07 2267 o update contact statement guideline 2269 o update example modules guidelines 2271 o add guidelines on top-level data nodes 2273 o add guideline on use of NP containers 2275 o added guidelines on union types 2277 o add guideline on deviations 2279 o added section on open systems considerations 2281 o added guideline about definitions reserved for future use 2283 A.2. v05 to v06 2285 o Changed example 'my-module' to 'example-module' 2287 o Added section Updating YANG Modules (Published vs. Unpublished) 2289 o Added Example Modules section 2291 o Added "" convention for full example modules 2293 o Added section on using action vs. rpc 2295 o Changed term "operational state" to "operational data" 2297 o Added section on YANG Data Node Constraints 2299 o Added guidelines on using must vs. when statements 2301 o Made ietf-foo module validate for I-D submission 2303 A.3. v04 to v05 2305 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2306 no YANG 1.1 features needed 2308 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2309 standards track documents only) 2311 o Clarified module naming conventions for normative modules, example 2312 modules, and modules from other SDOs. 2314 o Added prefix value selection guidelines 2316 o Added new section on guidelines for reusable groupings 2318 o Made header guidelines less IETF-specific 2320 o Added new section on guidelines for extension statements 2322 o Added guidelines for nested "choice" statement within a "case" 2323 statement 2325 A.4. v03 ot v04 2327 o Added sections for deviation statements and performance 2328 considerations 2330 o Added YANG 1.1 section 2332 o Updated YANG reference from 1.0 to 1.1 2334 A.5. v02 to v03 2336 o Updated draft based on github data tracker issues added by Benoit 2337 Clause (Issues 12 - 18) 2339 A.6. v01 to v02 2341 o Updated draft based on mailing list comments. 2343 A.7. v00 to v01 2345 All issues from the issue tracker have been addressed. 2347 https://github.com/netmod-wg/rfc6087bis/issues 2349 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 2350 can use an Informative reference to this RFC for tree diagrams. 2351 Updated guidelines to reference this RFC when tree diagrams are 2352 used 2354 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2355 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2356 functions 2358 o Issue 3: XPath function document order issues: Added paragraph in 2359 XPath usage section about node-set ordering for 'local-name', 2360 'namespace-uri', 'name', 'string' and 'number' functions. Also 2361 any function that implicitly converts a node-set to a string. 2363 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2364 and text in XPath usage section already has proposed text from 2365 Lada. 2367 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2368 exception and example in XPath Usage section for augmented nodes. 2370 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2371 to 'numeric and boolean expressions' 2373 o Issue 7: XPath module containment: Added sub-section on XPath 2374 wildcards 2376 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2377 section about transitioning from active to deprecated and then to 2378 obsolete. 2380 o Issue 9: resource identification in notifications: Add text to 2381 Notifications section about identifying resources and using the 2382 leafref data type. 2384 o Issue 10: single quoted strings: Added text to Data Types section 2385 about using a single-quoted string for patterns. 2387 Appendix B. Module Review Checklist 2389 This section is adapted from RFC 4181. 2391 The purpose of a YANG module review is to review the YANG module both 2392 for technical correctness and for adherence to IETF documentation 2393 requirements. The following checklist may be helpful when reviewing 2394 an Internet-Draft: 2396 o I-D Boilerplate -- verify that the draft contains the required 2397 Internet-Draft boilerplate (see 2398 http://www.ietf.org/id-info/guidelines.html), including the 2399 appropriate statement to permit publication as an RFC, and that 2400 I-D boilerplate does not contain references or section numbers. 2402 o Abstract -- verify that the abstract does not contain references, 2403 that it does not have a section number, and that its content 2404 follows the guidelines in 2405 http://www.ietf.org/id-info/guidelines.html. 2407 o Copyright Notice -- verify that the draft has the appropriate text 2408 regarding the rights that document contributers provide to the 2409 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2410 copyright notice at the beginning of the document. The IETF Trust 2411 Legal Provisions (TLP) can be found at: 2413 http://trustee.ietf.org/license-info/ 2415 o Security Considerations section -- verify that the draft uses the 2416 latest approved template from the OPS area website (http:// 2417 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2418 and that the guidelines therein have been followed. 2420 o IANA Considerations section -- this section must always be 2421 present. For each module within the document, ensure that the 2422 IANA Considerations section contains entries for the following 2423 IANA registries: 2425 XML Namespace Registry: Register the YANG module namespace. 2427 YANG Module Registry: Register the YANG module name, prefix, 2428 namespace, and RFC number, according to the rules specified 2429 in [I-D.ietf-netmod-rfc6020bis]. 2431 o References -- verify that the references are properly divided 2432 between normative and informative references, that RFC 2119 is 2433 included as a normative reference if the terminology defined 2434 therein is used in the document, that all references required by 2435 the boilerplate are present, that all YANG modules containing 2436 imported items are cited as normative references, and that all 2437 citations point to the most current RFCs unless there is a valid 2438 reason to do otherwise (for example, it is OK to include an 2439 informative reference to a previous version of a specification to 2440 help explain a feature included for backward compatibility). Be 2441 sure citations for all imported modules are present somewhere in 2442 the document text (outside the YANG module). 2444 o License -- verify that the draft contains the Simplified BSD 2445 License in each YANG module or submodule. Some guidelines related 2446 to this requirement are described in Section 4.1. Make sure that 2447 the correct year is used in all copyright dates. Use the approved 2448 text from the latest Trust Legal Provisions (TLP) document, which 2449 can be found at: 2451 http://trustee.ietf.org/license-info/ 2453 o Other Issues -- check for any issues mentioned in 2454 http://www.ietf.org/id-info/checklist.html that are not covered 2455 elsewhere. 2457 o Technical Content -- review the actual technical content for 2458 compliance with the guidelines in this document. The use of a 2459 YANG module compiler is recommended when checking for syntax 2460 errors. A list of freely available tools and other information 2461 can be found at: 2463 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2465 Checking for correct syntax, however, is only part of the job. 2466 It is just as important to actually read the YANG module document 2467 from the point of view of a potential implementor. It is 2468 particularly important to check that description statements are 2469 sufficiently clear and unambiguous to allow interoperable 2470 implementations to be created. 2472 Appendix C. YANG Module Template 2474 file "ietf-template@2016-03-20.yang" 2476 module ietf-template { 2478 // replace this string with a unique namespace URN value 2479 namespace 2480 "urn:ietf:params:xml:ns:yang:ietf-template"; 2482 // replace this string, and try to pick a unique prefix 2483 prefix "temp"; 2485 // import statements here: e.g., 2486 // import ietf-yang-types { prefix yang; } 2487 // import ietf-inet-types { prefix inet; } 2489 // identify the IETF working group if applicable 2490 organization 2491 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2493 // update this contact statement with your info 2494 contact 2495 "WG Web: 2496 WG List: 2498 Editor: your-name 2499 "; 2501 // replace the first sentence in this description statement. 2502 // replace the copyright notice with the most recent 2503 // version, if it has been updated since the publication 2504 // of this document 2505 description 2506 "This module defines a template for other YANG modules. 2508 Copyright (c) IETF Trust and the persons 2509 identified as authors of the code. All rights reserved. 2511 Redistribution and use in source and binary forms, with or 2512 without modification, is permitted pursuant to, and subject 2513 to the license terms contained in, the Simplified BSD License 2514 set forth in Section 4.c of the IETF Trust's Legal Provisions 2515 Relating to IETF Documents 2516 (http://trustee.ietf.org/license-info). 2518 This version of this YANG module is part of RFC XXXX; see 2519 the RFC itself for full legal notices."; 2521 // RFC Ed.: replace XXXX with actual RFC number and remove 2522 // this note 2524 reference "RFC XXXX"; 2526 // RFC Ed.: remove this note 2527 // Note: extracted from RFC XXXX 2529 // replace '2016-03-20' with the module publication date 2530 // The format is (year-month-day) 2531 revision "2016-03-20" { 2532 description "what changed in this revision"; 2533 reference "document containing this module"; 2534 } 2536 // extension statements 2538 // feature statements 2540 // identity statements 2542 // typedef statements 2544 // grouping statements 2546 // data definition statements 2548 // augment statements 2550 // rpc statements 2552 // notification statements 2554 // DO NOT put deviation statements in a published module 2556 } 2558 2560 Author's Address 2562 Andy Bierman 2563 YumaWorks 2565 Email: andy@yumaworks.com