idnits 2.17.1 draft-ietf-netmod-rfc6087bis-05.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 (October 19, 2015) is 3105 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 322, but not defined == Missing Reference: 'RFC6242' is mentioned on line 1820, 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 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track October 19, 2015 5 Expires: April 21, 2016 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-05 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 April 21, 2016. 37 Copyright Notice 39 Copyright (c) 2015 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.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 64 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 65 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 66 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 67 4.6. Security Considerations Section . . . . . . . . . . . . . 10 68 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 69 4.7.1. Documents that Create a New Namespace . . . . . . . . 11 70 4.7.2. Documents that Extend an Existing Namespace . . . . . 12 71 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 72 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 73 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 12 74 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 75 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 76 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15 78 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15 79 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 16 81 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 17 82 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 17 83 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 18 84 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 19 85 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 19 86 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 20 87 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 20 88 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 21 89 5.8. Module Header, Meta, and Revision Statements . . . . . . . 22 90 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 23 91 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 24 92 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 24 93 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 25 94 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 25 95 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26 97 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27 98 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 28 99 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28 100 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 30 101 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 30 102 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 31 103 5.18. Augment Statements . . . . . . . . . . . . . . . . . . . . 31 104 5.18.1. Conditional Augment Statements . . . . . . . . . . . . 32 105 5.18.2. Conditionally Mandatory Data Definition Statements . . 32 106 5.19. Deviation Statements . . . . . . . . . . . . . . . . . . . 33 107 5.20. Extension Statements . . . . . . . . . . . . . . . . . . . 34 108 5.21. Data Correlation . . . . . . . . . . . . . . . . . . . . . 35 109 5.22. Operational State . . . . . . . . . . . . . . . . . . . . 36 110 5.23. Performance Considerations . . . . . . . . . . . . . . . . 38 111 5.24. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 38 112 5.24.1. Importing Multiple Revisions . . . . . . . . . . . . . 39 113 5.24.2. Using Feature Logic . . . . . . . . . . . . . . . . . 39 114 5.24.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 39 115 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 116 7. Security Considerations . . . . . . . . . . . . . . . . . . . 41 117 7.1. Security Considerations Section Template . . . . . . . . . 41 118 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 119 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 44 120 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 121 10.1. Normative References . . . . . . . . . . . . . . . . . . . 45 122 10.2. Informative References . . . . . . . . . . . . . . . . . . 46 123 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 124 A.1. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . . 47 125 A.2. 03 ot 04 . . . . . . . . . . . . . . . . . . . . . . . . . 47 126 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 47 127 A.4. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 47 128 A.5. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 48 129 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 49 130 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 51 131 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 53 133 1. Introduction 135 The standardization of network configuration interfaces for use with 136 the Network Configuration Protocol [RFC6241] requires a modular set 137 of data models, which can be reused and extended over time. 139 This document defines a set of usage guidelines for Standards Track 140 documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG 141 is used to define the data structures, protocol operations, and 142 notification content used within a NETCONF server. A server that 143 supports a particular YANG module will support client NETCONF 144 operation requests, as indicated by the specific content defined in 145 the YANG module. 147 This document is similar to the Structure of Management Information 148 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 149 and structure. However, since that document was written a decade 150 after SMIv2 modules had been in use, it was published as a 'Best 151 Current Practice' (BCP). This document is not a BCP, but rather an 152 informational reference, intended to promote consistency in documents 153 containing YANG modules. 155 Many YANG constructs are defined as optional to use, such as the 156 description statement. However, in order to maximize 157 interoperability of NETCONF implementations utilizing YANG data 158 models, it is desirable to define a set of usage guidelines that may 159 require a higher level of compliance than the minimum level defined 160 in the YANG specification. 162 In addition, YANG allows constructs such as infinite length 163 identifiers and string values, or top-level mandatory nodes, that a 164 compliant server is not required to support. Only constructs that 165 all servers are required to support can be used in IETF YANG modules. 167 This document defines usage guidelines related to the NETCONF 168 operations layer and NETCONF content layer, as defined in [RFC6241]. 169 These guidelines are intended to be used by authors and reviewers to 170 improve the readability and interoperability of published YANG data 171 models. 173 Note that this document is not a YANG tutorial and the reader is 174 expected to know the YANG data modeling language before using this 175 document. 177 2. Terminology 179 2.1. Requirements Notation 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 183 document are to be interpreted as described in [RFC2119]. 185 RFC 2119 language is used here to express the views of the NETMOD 186 working group regarding content for YANG modules. YANG modules 187 complying with this document will treat the RFC 2119 terminology as 188 if it were describing best current practices. 190 2.2. NETCONF Terms 192 The following terms are defined in [RFC6241] and are not redefined 193 here: 195 o capabilities 197 o client 199 o operation 201 o server 203 2.3. YANG Terms 205 The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and 206 are not redefined here: 208 o data node 210 o module 212 o namespace 214 o submodule 216 o version 218 o YANG 220 o YIN 222 Note that the term 'module' may be used as a generic term for a YANG 223 module or submodule. When describing properties that are specific to 224 submodules, the term 'submodule' is used instead. 226 2.4. Terms 228 The following terms are used throughout this document: 230 o published: A stable release of a module or submodule, usually 231 contained in an RFC. 233 o unpublished: An unstable release of a module or submodule, usually 234 contained in an Internet-Draft. 236 3. YANG Tree Diagrams 238 YANG tree diagrams provide a concise representation of a YANG module 239 to help readers understand the module structure. 241 The meaning of the symbols in YANG tree diagrams is as follows: 243 o Brackets "[" and "]" enclose list keys. 245 o Abbreviations before data node names: "rw" means configuration 246 (read-write) and "ro" state data (read-only). 248 o Symbols after data node names: "?" means an optional node, "!" 249 means a presence container, and "*" denotes a list and leaf-list. 251 o Parentheses enclose choice and case nodes, and case nodes are also 252 marked with a colon (":"). 254 o Ellipsis ("...") stands for contents of subtrees that are not 255 shown. 257 4. General Documentation Guidelines 259 YANG data model modules under review are likely to be contained in 260 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 261 followed. The RFC Editor provides guidelines for authors of RFCs, 262 which are first published as Internet-Drafts. These guidelines 263 should be followed and are defined in [RFC2223] and updated in 264 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 266 The following sections MUST be present in an Internet-Draft 267 containing a module: 269 o Narrative sections 271 o Definitions section 273 o Security Considerations section 275 o IANA Considerations section 277 o References section 279 4.1. Module Copyright 281 The module description statement MUST contain a reference to the 282 latest approved IETF Trust Copyright statement, which is available 283 online at: 285 http://trustee.ietf.org/license-info/ 287 Each YANG module or submodule contained within an Internet-Draft or 288 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 290 component. 292 The "" tag SHOULD be followed by a string identifying 293 the file name specified in Section 5.2 of 294 [I-D.ietf-netmod-rfc6020bis]. The following example is for the 295 '2010-01-18' revision of the 'ietf-foo' module: 297 file "ietf-foo@2010-01-18.yang" 298 module ietf-foo { 299 // ... 300 revision 2010-01-18 { 301 description "Latest revision"; 302 reference "RFC XXXX"; 303 } 304 // ... 305 } 306 308 Note that this convention MUST NOT be used for example modules or 309 module fragments. 311 4.2. Terminology Section 313 A terminology section MUST be present if any terms are defined in the 314 document or if any terms are imported from other documents. 316 If YANG tree diagrams are used, then a sub-section explaining the 317 YANG tree diagram syntax MUST be present, containing the following 318 text: 320 A simplified graphical representation of the data model is used in 321 this document. The meaning of the symbols in these diagrams is 322 defined in [RFCXXXX]. 324 -- RFC Editor: Replace XXXX with RFC number and remove note 326 4.3. Tree Diagrams 328 YANG tree diagrams provide a concise representation of a YANG module, 329 and SHOULD be included to help readers understand YANG module 330 structure. Tree diagrams MAY be split into sections to correspond to 331 document structure. 333 The following example shows a simple YANG tree diagram: 335 +--rw top-level-config-container 336 | +--rw config-list* [key-name] 337 | +--rw key-name string 338 | +--rw optional-parm? string 339 | +--rw mandatory-parm identityref 340 | +--ro read-only-leaf string 341 +--ro top-level-nonconfig-container 342 +--ro nonconfig-list* [name] 343 +--ro name string 344 +--ro type string 346 4.4. Narrative Sections 348 The narrative part MUST include an overview section that describes 349 the scope and field of application of the module(s) defined by the 350 specification and that specifies the relationship (if any) of these 351 modules to other standards, particularly to standards containing 352 other YANG modules. The narrative part SHOULD include one or more 353 sections to briefly describe the structure of the modules defined in 354 the specification. 356 If the module(s) defined by the specification imports definitions 357 from other modules (except for those defined in the 358 [I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always 359 implemented in conjunction with other modules, then those facts MUST 360 be noted in the overview section, as MUST be noted any special 361 interpretations of definitions in other modules. 363 4.5. Definitions Section 365 This section contains the module(s) defined by the specification. 366 These modules SHOULD be written using the YANG syntax defined in 367 [I-D.ietf-netmod-rfc6020bis]. YANG 1.0 [RFC6020] MAY be used if no 368 YANG 1.1 constructs or semantics are needed in the module. 370 A YIN syntax version of the module MAY also be present in the 371 document. There MAY also be other types of modules present in the 372 document, such as SMIv2, which are not affected by these guidelines. 374 Note that all YANG statements within a YANG module are considered 375 normative, if the module itself is considered normative, and not an 376 example module. The use of keywords defined in [RFC2119] apply to 377 YANG description statements in normative modules exactly as they 378 would in any other normative section. 380 Example YANG modules MUST NOT contain any normative text, including 381 any reserved words from [RFC2119]. 383 See Section 5 for guidelines on YANG usage. 385 4.6. Security Considerations Section 387 Each specification that defines one or more modules MUST contain a 388 section that discusses security considerations relevant to those 389 modules. 391 This section MUST be patterned after the latest approved template 392 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 393 yang-security-guidelines). Section 7.1 contains the security 394 considerations template dated 2013-05-08. Authors MUST check the 395 webpage at the URL listed above in case there is a more recent 396 version available. 398 In particular: 400 o Writable data nodes that could be especially disruptive if abused 401 MUST be explicitly listed by name and the associated security 402 risks MUST be explained. 404 o Readable data nodes that contain especially sensitive information 405 or that raise significant privacy concerns MUST be explicitly 406 listed by name and the reasons for the sensitivity/privacy 407 concerns MUST be explained. 409 o Operations (i.e., YANG 'rpc' statements) that are potentially 410 harmful to system behavior or that raise significant privacy 411 concerns MUST be explicitly listed by name and the reasons for the 412 sensitivity/privacy concerns MUST be explained. 414 4.7. IANA Considerations Section 416 In order to comply with IESG policy as set forth in 417 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 418 is submitted to the IESG for publication MUST contain an IANA 419 Considerations section. The requirements for this section vary 420 depending on what actions are required of the IANA. If there are no 421 IANA considerations applicable to the document, then the IANA 422 Considerations section stating that there are no actions is removed 423 by the RFC Editor before publication. Refer to the guidelines in 424 [RFC5226] for more details. 426 4.7.1. Documents that Create a New Namespace 428 If an Internet-Draft defines a new namespace that is to be 429 administered by the IANA, then the document MUST include an IANA 430 Considerations section that specifies how the namespace is to be 431 administered. 433 Specifically, if any YANG module namespace statement value contained 434 in the document is not already registered with IANA, then a new YANG 435 Namespace registry entry MUST be requested from the IANA. The 436 [I-D.ietf-netmod-rfc6020bis] specification includes the procedure for 437 this purpose in its IANA Considerations section. 439 4.7.2. Documents that Extend an Existing Namespace 441 It is possible to extend an existing namespace using a YANG submodule 442 that belongs to an existing module already administered by IANA. In 443 this case, the document containing the main module MUST be updated to 444 use the latest revision of the submodule. 446 4.8. Reference Sections 448 For every import or include statement that appears in a module 449 contained in the specification, which identifies a module in a 450 separate document, a corresponding normative reference to that 451 document MUST appear in the Normative References section. The 452 reference MUST correspond to the specific module version actually 453 used within the specification. 455 For every normative reference statement that appears in a module 456 contained in the specification, which identifies a separate document, 457 a corresponding normative reference to that document SHOULD appear in 458 the Normative References section. The reference SHOULD correspond to 459 the specific document version actually used within the specification. 460 If the reference statement identifies an informative reference, which 461 identifies a separate document, a corresponding informative reference 462 to that document MAY appear in the Informative References section. 464 4.9. Validation Tools 466 All modules need to be validated before submission in an Internet 467 Draft. The 'pyang' YANG compiler is freely available from github: 469 https://github.com/mbj4668/pyang 471 If the 'pyang' compiler is used, then the "--ietf" command line 472 option SHOULD be used to identify any IETF guideline issues. 474 4.10. Module Extraction Tools 476 A version of 'rfcstrip' is available which will extract YANG modules 477 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 478 YANG module extraction is freely available: 480 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 482 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 484 can be extracted correctly. 486 5. YANG Usage Guidelines 488 In general, modules in IETF Standards Track specifications MUST 489 comply with all syntactic and semantic requirements of YANG 490 [I-D.ietf-netmod-rfc6020bis]. The guidelines in this section are 491 intended to supplement the YANG specification, which is intended to 492 define a minimum set of conformance requirements. 494 In order to promote interoperability and establish a set of practices 495 based on previous experience, the following sections establish usage 496 guidelines for specific YANG constructs. 498 Only guidelines that clarify or restrict the minimum conformance 499 requirements are included here. 501 5.1. Module Naming Conventions 503 Normative modules contained in Standards Track documents MUST be 504 named according to the guidelines in the IANA Considerations section 505 of [I-D.ietf-netmod-rfc6020bis]. 507 A distinctive word or acronym (e.g., protocol name or working group 508 acronym) SHOULD be used in the module name. If new definitions are 509 being defined to extend one or more existing modules, then the same 510 word or acronym should be reused, instead of creating a new one. 512 All published module names MUST be unique. For a YANG module 513 published in an RFC, this uniqueness is guaranteed by IANA. For 514 unpublished modules, the authors need to check that no other work in 515 progress is using the same module name. 517 Example modules are non-normative, and SHOULD be named with the 518 prefix "example-". 520 It is suggested that a stable prefix be selected representing the 521 entire organization. All normative YANG modules published by the 522 IETF MUST begin with the prefix "ietf-". Another standards 523 organization, such as the IEEE, might use the prefix "ieee-" for all 524 YANG modules. 526 Once a module name is published, it MUST NOT be reused, even if the 527 RFC containing the module is reclassified to 'Historic' status. A 528 module name cannot be changed in YANG, and this would be treated as a 529 a new module, not a name change. 531 5.2. Prefixes 533 All YANG definitions are scoped by the module containing the 534 definition being referenced. This allows definitions from multiple 535 modules to be used, even if the names are not unique. In the example 536 below, the identifier "foo" is used in all 3 modules: 538 module example-foo { 539 namespace "http://example.com/ns/foo"; 540 prefix f; 542 container foo; 543 } 545 module example-bar { 546 namespace "http://example.com/ns/bar"; 547 prefix b; 549 typedef foo { type uint32; } 550 } 552 module example-one { 553 namespace "http://example.com/ns/one"; 554 prefix one; 555 import example-foo { prefix f; } 556 import example-bar { prefix b; } 558 augment "/f:foo" { 559 leaf foo { type b:foo; } 560 } 561 } 563 YANG defines the following rules for prefix usage: 565 o Prefixes are never allowed for built in data types and YANG 566 keywords. 568 o A prefix MUST be used for any external statement (i.e., a 569 statement defined with the YANG "extension" statement) 571 o The proper module prefix MUST be used for all identifiers imported 572 from other modules 574 o The proper module prefix MUST be used for all identifiers included 575 from a submodule. 577 The following guidelines apply to prefix usage of the current (local) 578 module: 580 o The local module prefix SHOULD be used instead of no prefix in all 581 path expressions. 583 o The local module prefix MUST be used instead of no prefix in all 584 "default" statements for an "identityref" or "instance-identifier" 585 data type 587 o The lcaol module prefix MAY be used for references to typedefs, 588 groupings, extensions, features, and identities defined in the 589 module. 591 Prefix values SHOULD be short, but also likely to be unique. Prefix 592 values SHOULD NOT conflict with known modules that have been 593 previously published. 595 5.3. Identifiers 597 Identifiers for all YANG identifiers in published modules MUST be 598 between 1 and 64 characters in length. These include any construct 599 specified as an 'identifier-arg-str' token in the ABNF in Section 13 600 of [I-D.ietf-netmod-rfc6020bis]. 602 5.3.1. Identifier Naming Conventions 604 Identifiers SHOULD follow a consistent naming pattern throughout the 605 module. Only lower-case letters, numbers, and dashes SHOULD be used 606 in identifier names. Upper-case characters and the underscore 607 character MAY be used if the identifier represents a well-known value 608 that uses these characters. 610 Identifiers SHOULD include complete words and/or well-known acronyms 611 or abbreviations. Child nodes within a container or list SHOULD NOT 612 replicate the parent identifier. YANG identifiers are hierarchical 613 and are only meant to be unique within the the set of sibling nodes 614 defined in the same module namespace. 616 It is permissible to use common identifiers such as "name" or "id" in 617 data definition statements, especially if these data nodes share a 618 common data type. 620 Identifiers SHOULD NOT carry any special semantics that identify data 621 modelling properties. Only YANG statements and YANG extension 622 statements are designed to convey machine readable data modelling 623 properties. For example, naming an object "config" or "state" does 624 not change whether it is configuration data or state data. Only 625 defined YANG statements or YANG extension statements can be used to 626 assign semantics in a machine readable format in YANG. 628 5.4. Defaults 630 In general, it is suggested that substatements containing very common 631 default values SHOULD NOT be present. The following substatements 632 are commonly used with the default value, which would make the module 633 difficult to read if used everywhere they are allowed. 635 +--------------+---------------+ 636 | Statement | Default Value | 637 +--------------+---------------+ 638 | config | true | 639 | mandatory | false | 640 | max-elements | unbounded | 641 | min-elements | 0 | 642 | ordered-by | system | 643 | status | current | 644 | yin-element | false | 645 +--------------+---------------+ 647 Statement Defaults 649 5.5. Conditional Statements 651 A module may be conceptually partitioned in several ways, using the 652 'if-feature' and/or 'when' statements. 654 Data model designers need to carefully consider all modularity 655 aspects, including the use of YANG conditional statements. 657 If a data definition is optional, depending on server support for a 658 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 659 be defined to indicate that the NETCONF capability is supported 660 within the data model. 662 If any notification data, or any data definition, for a non- 663 configuration data node is not mandatory, then the server may or may 664 not be required to return an instance of this data node. If any 665 conditional requirements exist for returning the data node in a 666 notification payload or retrieval request, they MUST be documented 667 somewhere. For example, a 'when' or 'if-feature' statement could 668 apply to the data node, or the conditional requirements could be 669 explained in a 'description' statement within the data node or one of 670 its ancestors (if any). 672 If any 'if-feature' statements apply to a list node, then the same 673 'if-feature' statements MUST apply to any key leaf nodes for the 674 list. There MUST NOT be any 'if-feature' statements applied to any 675 key leaf that do not also apply to the parent list node. 677 There SHOULD NOT be any 'when' statements applied to a key leaf node. 678 It is possible that a 'when' statement for an ancestor node of a key 679 leaf will have the exact node-set result as the key leaf. In such a 680 case, the 'when' statement for the key leaf is redundant and SHOULD 681 be avoided. 683 5.6. XPath Usage 685 This section describes guidelines for using the XML Path Language 686 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 688 5.6.1. XPath Evaluation Contexts 690 YANG defines 5 separate contexts for evaluation of XPath statements: 692 1) The "running" datastore: collection of all YANG configuration data 693 nodes. The document root is the conceptual container, (e.g., 694 "config" in the "edit-config" operation), which is the parent of all 695 top-level data definition statements with a "config" statement value 696 of "true". 698 2) State data + the "running" datastore: collection of all YANG data 699 nodes. The document root is the conceptual container, parent of all 700 top-level data definition statements. 702 3) Notification: an event notification document. The document root 703 is the notification element. 705 4) RPC Input: The document root is the conceptual "input" node, which 706 is the parent of all RPC input parameter definitions. 708 5) RPC Output: The document root is the conceptual "output" node, 709 which is the parent of all RPC output parameter definitions. 711 Note that these XPath contexts cannot be mixed. For example, a 712 "when" statement in a notification context cannot reference 713 configuration data. 715 notification foo { 716 leaf mtu { 717 // NOT OK because when-stmt context is this notification 718 when "/if:interfaces/if:interface[name='eth0']"; 719 type leafref { 720 // OK because path-stmt has a different context 721 path "/if:interfaces/if:interface/if:mtu"; 722 } 723 } 724 } 726 It is especially important to consider the XPath evaluation context 727 for XPath expressions defined in groupings. An XPath expression 728 defined in a grouping may not be portable, meaning it cannot be used 729 in multiple contexts and produce proper results. 731 If the XPath expressions defined in a grouping are intended for a 732 particular context, then this context SHOULD be identified in the 733 "description" statement for the grouping. 735 5.6.2. Function Library 737 The 'position' and 'last' functions SHOULD NOT be used. This applies 738 to implicit use of the 'position' function as well (e.g., 739 '//chapter[42]'). A server is only required to maintain the relative 740 XML document order of all instances of a particular user-ordered list 741 or leaf-list. The 'position' and 'last' functions MAY be used if 742 they are evaluated in a context where the context node is a user- 743 ordered 'list' or 'leaf-list'. 745 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 746 present in YANG documents so this function has no meaning. The YANG 747 compiler SHOULD return an empty string for this function. 749 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 750 Expanded names in XPath are different than YANG. A specific 751 canonical representation of a YANG expanded name does not exist. 753 The 'lang' function SHOULD NOT be used. This function does not apply 754 to YANG because there is no 'lang' attribute set with the document. 755 The YANG compiler SHOULD return 'false' for this function. 757 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 758 functions SHOULD NOT be used if the argument is a node-set. If so, 759 the function result will be determined by the document order of the 760 node-set. Since this order can be different on each server, the 761 function results can also be different. Any function call that 762 implicitly converts a node-set to a string will also have this issue. 764 The 'local-name' function SHOULD NOT be used to reference local names 765 outside of the YANG module defining the must or when expression 766 containing the 'local-name' function. Example of a local-name 767 function that should not be used: 769 /*[local-name()='foo'] 771 5.6.3. Axes 773 The 'attribute' and 'namespace' axes are not supported in YANG, and 774 MAY be empty in a NETCONF server implementation. 776 The 'preceding', and 'following' axes SHOULD NOT be used. These 777 constructs rely on XML document order within a NETCONF server 778 configuration database, which may not be supported consistently or 779 produce reliable results across implementations. Predicate 780 expressions based on static node properties (e.g., element name or 781 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 782 'preceding' and 'following' axes MAY be used if document order is not 783 relevant to the outcome of the expression (e.g., check for global 784 uniqueness of a parameter value). 786 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 787 however they MAY be used if document order is not relevant to the 788 outcome of the expression. 790 A server is only required to maintain the relative XML document order 791 of all instances of a particular user-ordered list or leaf-list. The 792 'preceding-sibling' and 'following-sibling' axes MAY be used if they 793 are evaluated in a context where the context node is a user-ordered 794 'list' or 'leaf-list'. 796 5.6.4. Types 798 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 799 be used within numeric or boolean expressions. There are boundary 800 conditions in which the translation from the YANG 64-bit type to an 801 XPath number can cause incorrect results. Specifically, an XPath 802 'double' precision floating point number cannot represent very large 803 positive or negative 64-bit numbers because it only provides a total 804 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 805 used in numeric expressions if the value can be represented with no 806 more than 53 bits of precision. 808 Data modelers need to be careful not to confuse the YANG value space 809 and the XPath value space. The data types are not the same in both, 810 and conversion between YANG and XPath data types SHOULD be considered 811 carefully. 813 Explicit XPath data type conversions MAY be used (e.g., 'string', 814 'boolean', or 'number' functions), instead of implicit XPath data 815 type conversions. 817 XPath expressions that contain a literal value representing a YANG 818 identity SHOULD always include the declared prefix of the module 819 where the identity is defined. 821 XPath expressions for 'when' statements SHOULD NOT reference the 822 context node or any descendant nodes of the context node. They MAY 823 reference descendant nodes if the 'when' statement is contained 824 within an 'augment' statement, and the referenced nodes are not 825 defined within the 'augment' statement. 827 Example: 829 augment "/rt:active-route/rt:input/rt:destination-address" { 830 when "rt:address-family='v4ur:ipv4-unicast'" { 831 description 832 "This augment is valid only for IPv4 unicast."; 833 } 834 // nodes defined here within the augment-stmt 835 // cannot be referenced in the when-stmt 836 } 838 5.6.5. Wildcards 840 It is possible to construct XPath expressions that will evaluate 841 differently when combined with several modules within a server 842 implementation, then when evaluated within the single module. This 843 is due to augmenting nodes from other modules. 845 Wildcard expansion is done within a server against all the nodes from 846 all namespaces, so it is possible for a 'must' or 'when' expression 847 that uses the '*' operator will always evaluate to false if processed 848 within a single YANG module. In such cases, the 'description' 849 statement SHOULD clarify that augmenting objects are expected to 850 match the wildcard expansion. 852 when /foo/services/*/active { 853 description 854 "No services directly defined in this module. 855 Matches objects that have augmented the services container."; 856 } 858 5.6.6. Boolean Expressions 860 The YANG "must" and "when" statements use an XPath boolean expression 861 to define the test condition for the statement. It is important to 862 specify these expressions in a way that will not cause inadvertent 863 changes in the result if the objects referenced in the expression are 864 updated in future revisions of the module. 866 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 867 to "one" or "three": 869 leaf foo1 { 870 type enumeration { 871 enum one; 872 enum two; 873 enum three; 874 } 875 } 877 leaf foo2 { 878 // INCORRECT 879 must "/f:foo1 != 'two'"; 880 type string; 881 } 883 leaf foo2 { 884 // CORRECT 885 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 886 type string; 887 } 889 In the next revision of the module, leaf "foo1" is extended with a 890 nem enum named "four": 892 leaf foo1 { 893 type enumeration { 894 enum one; 895 enum two; 896 enum three; 897 enum four; 898 } 899 } 901 Now the first XPath expression will allow the enum "four" to be 902 accepted in addition to the "one" and "three" enum values. 904 5.7. Lifecycle Management 906 The status statement MUST be present if its value is 'deprecated' or 907 'obsolete'. The status SHOULD NOT be changed from 'current' directly 908 to 'obsolete'. An object SHOULD be available for at least one year 909 with 'deprecated' status before it is changed to 'obsolete'. 911 The module or submodule name MUST NOT be changed, once the document 912 containing the module or submodule is published. 914 The module namespace URI value MUST NOT be changed, once the document 915 containing the module is published. 917 The revision-date substatement within the imports statement SHOULD be 918 present if any groupings are used from the external module. 920 The revision-date substatement within the include statement SHOULD be 921 present if any groupings are used from the external submodule. 923 If submodules are used, then the document containing the main module 924 MUST be updated so that the main module revision date is equal or 925 more recent than the revision date of any submodule that is (directly 926 or indirectly) included by the main module. 928 5.8. Module Header, Meta, and Revision Statements 930 For published modules, the namespace MUST be a globally unique URI, 931 as defined in [RFC3986]. This value is usually assigned by the IANA. 933 The organization statement MUST be present. If the module is 934 contained in a document intended for IETF Standards Track status, 935 then the organization SHOULD be the IETF working group chartered to 936 write the document. For other standards organizations, a similar 937 approach is also suggested. 939 The contact statement MUST be present. If the module is contained in 940 a document intended for Standards Track status, then the working 941 group web and mailing information MUST be present, and the main 942 document author or editor contact information SHOULD be present. If 943 additional authors or editors exist, their contact information MAY be 944 present. In addition, the Area Director and other contact 945 information MAY be present. 947 The description statement MUST be present. For modules published 948 within IETF documents, the appropriate IETF Trust Copyright text MUST 949 be present, as described in Section 4.1. 951 If the module relies on information contained in other documents, 952 which are not the same documents implied by the import statements 953 present in the module, then these documents MUST be identified in the 954 reference statement. 956 A revision statement MUST be present for each published version of 957 the module. The revision statement MUST have a reference 958 substatement. It MUST identify the published document that contains 959 the module. Modules are often extracted from their original 960 documents, and it is useful for developers and operators to know how 961 to find the original source document in a consistent manner. The 962 revision statement MAY have a description substatement. 964 Each new revision MUST include a revision date that is higher than 965 any other revision date in the module. The revision date does not 966 need to be updated if the module contents do not change in the new 967 document revision. 969 It is acceptable to reuse the same revision statement within 970 unpublished versions (i.e., Internet-Drafts), but the revision date 971 MUST be updated to a higher value each time the Internet-Draft is re- 972 posted. 974 5.9. Namespace Assignments 976 It is RECOMMENDED that only valid YANG modules be included in 977 documents, whether or not they are published yet. This allows: 979 o the module to compile correctly instead of generating disruptive 980 fatal errors. 982 o early implementors to use the modules without picking a random 983 value for the XML namespace. 985 o early interoperability testing since independent implementations 986 will use the same XML namespace value. 988 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 989 provided for the namespace statement in a YANG module. A value 990 SHOULD be selected that is not likely to collide with other YANG 991 namespaces. Standard module names, prefixes, and URI strings already 992 listed in the YANG Module Registry MUST NOT be used. 994 A standard namespace statement value SHOULD have the following form: 996 : 998 The following URN prefix string SHOULD be used for published and 999 unpublished YANG modules: 1001 urn:ietf:params:xml:ns:yang: 1003 The following example URNs would be valid namespace statement values 1004 for Standards Track modules: 1006 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1008 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1010 urn:ietf:params:xml:ns:yang:ietf-netconf 1012 Note that a different URN prefix string SHOULD be used for non- 1013 Standards-Track modules. The string SHOULD be selected according to 1014 the guidelines in [I-D.ietf-netmod-rfc6020bis]. 1016 The following examples are for non-Standards-Track modules. The 1017 domain "example.com" SHOULD be used in all namespace URIs for example 1018 modules. 1020 http://example.com/ns/example-interfaces 1022 http://example.com/ns/example-system 1024 5.10. Top-Level Data Definitions 1026 The top-level data organization SHOULD be considered carefully, in 1027 advance. Data model designers need to consider how the functionality 1028 for a given protocol or protocol family will grow over time. 1030 The separation of configuration data and operational state SHOULD be 1031 considered carefully. It is often useful to define separate top- 1032 level containers for configuration and non-configuration data. 1034 The number of top-level data nodes within a module SHOULD be 1035 minimized. It is often useful to retrieve related information within 1036 a single subtree. If data is too distributed, is becomes difficult 1037 to retrieve all at once. 1039 The names and data organization SHOULD reflect persistent 1040 information, such as the name of a protocol. The name of the working 1041 group SHOULD NOT be used because this may change over time. 1043 A mandatory database data definition is defined as a node that a 1044 client must provide for the database to be valid. The server is not 1045 required to provide a value. 1047 Top-level database data definitions MUST NOT be mandatory. If a 1048 mandatory node appears at the top level, it will immediately cause 1049 the database to be invalid. This can occur when the server boots or 1050 when a module is loaded dynamically at runtime. 1052 5.11. Data Types 1054 Selection of an appropriate data type (i.e., built-in type, existing 1055 derived type, or new derived type) is very subjective, and therefore 1056 few requirements can be specified on that subject. 1058 Data model designers SHOULD use the most appropriate built-in data 1059 type for the particular application. 1061 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1062 'int64') SHOULD NOT be used unless negative values are allowed for 1063 the desired semantics. 1065 5.11.1. Fixed Value Extensibility 1067 If the set of values is fixed and the data type contents are 1068 controlled by a single naming authority, then an enumeration data 1069 type SHOULD be used. 1071 leaf foo { 1072 type enumeration { 1073 enum one; 1074 enum two; 1075 } 1076 } 1078 If extensibility of enumerated values is required, then the 1079 'identityref' data type SHOULD be used instead of an enumeration or 1080 other built-in type. 1082 identity foo-type { 1083 description "Base for the extensible type"; 1084 } 1086 identity one { 1087 base f:foo-type; 1088 } 1089 identity two { 1090 base f:foo-type; 1091 } 1093 leaf foo { 1094 type identityref { 1095 base f:foo-type; 1096 } 1097 } 1099 Note that any module can declare an identity with base "foo-type" 1100 that is valid for the "foo" leaf. Identityref values are considered 1101 to be qualified names. 1103 5.11.2. Patterns and Ranges 1105 For string data types, if a machine-readable pattern can be defined 1106 for the desired semantics, then one or more pattern statements SHOULD 1107 be present. A single quoted string SHOULD be used to specify the 1108 pattern, since a double-quoted string can modify the content. 1110 The following typedef from [RFC6991] demonstrates the proper use of 1111 the "pattern" statement: 1113 typedef ipv4-address-no-zone { 1114 type inet:ipv4-address { 1115 pattern '[0-9\.]*'; 1116 } 1117 ... 1118 } 1120 For string data types, if the length of the string is required to be 1121 bounded in all implementations, then a length statement MUST be 1122 present. 1124 The following typedef from [RFC6991] demonstrates the proper use of 1125 the "length" statement: 1127 typedef yang-identifier { 1128 type string { 1129 length "1..max"; 1130 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1131 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1132 } 1133 ... 1134 } 1136 For numeric data types, if the values allowed by the intended 1137 semantics are different than those allowed by the unbounded intrinsic 1138 data type (e.g., 'int32'), then a range statement SHOULD be present. 1140 The following typedef from [RFC6991] demonstrates the proper use of 1141 the "range" statement: 1143 typedef dscp { 1144 type uint8 { 1145 range "0..63"; 1146 } 1147 ... 1148 } 1150 5.11.3. Enumerations and Bits 1152 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1153 or 'bit' SHOULD be documented. A separate description statement 1154 (within each 'enum' or 'bit' statement) SHOULD be present. 1156 leaf foo { 1157 // INCORRECT 1158 type enumeration { 1159 enum one; 1160 enum two; 1161 } 1162 description 1163 "The foo enum... 1164 one: The first enum 1165 two: The second enum"; 1166 } 1168 leaf foo { 1169 // CORRECT 1170 type enumeration { 1171 enum one { 1172 description "The first enum"; 1173 } 1174 enum two { 1175 description "The second enum"; 1176 } 1177 } 1178 description 1179 "The foo enum... "; 1180 } 1182 5.12. Reusable Type Definitions 1184 If an appropriate derived type exists in any standard module, such as 1185 [RFC6991], then it SHOULD be used instead of defining a new derived 1186 type. 1188 If an appropriate units identifier can be associated with the desired 1189 semantics, then a units statement SHOULD be present. 1191 If an appropriate default value can be associated with the desired 1192 semantics, then a default statement SHOULD be present. 1194 If a significant number of derived types are defined, and it is 1195 anticipated that these data types will be reused by multiple modules, 1196 then these derived types SHOULD be contained in a separate module or 1197 submodule, to allow easier reuse without unnecessary coupling. 1199 The description statement MUST be present. 1201 If the type definition semantics are defined in an external document 1202 (other than another YANG module indicated by an import statement), 1203 then the reference statement MUST be present. 1205 5.13. Reusable Groupings 1207 A reusable grouping is a YANG grouping that can be imported by 1208 another module, and is intended for use by other modules. This is 1209 not the same as a grouping that is used within the module it is 1210 defined, but happens to be exportable to another module because it is 1211 defined at the top-level of the YANG module. 1213 The following guidelines apply to reusable groupings, in order to 1214 make them as robust as possible: 1216 o Clearly identify the purpose of the grouping in the "description" 1217 statement. 1219 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1220 output, notification, config=true data nodes, and all data nodes). 1221 Clearly identify which XPath contexts are applicable or excluded 1222 for the grouping. 1224 o Do not reference data outside the grouping in any "path", "must", 1225 or "when" statements. 1227 o Do not include a "default" sub-statement on a leaf or choice 1228 unless the value applies on all possible contexts. 1230 o Do not include a "config" sub-statement on a data node unless the 1231 value applies on all possible contexts. 1233 o Clearly identify any external dependencies in the grouping 1234 "description" statement, such as nodes referenced by absolute path 1235 from a "path", "must", or "when" statement. 1237 5.14. Data Definitions 1239 The description statement MUST be present in the following YANG 1240 statements: 1242 o anyxml 1244 o augment 1246 o choice 1248 o container 1250 o extension 1251 o feature 1253 o grouping 1255 o identity 1257 o leaf 1259 o leaf-list 1261 o list 1263 o notification 1265 o rpc 1267 o typedef 1269 If the data definition semantics are defined in an external document, 1270 (other than another YANG module indicated by an import statement), 1271 then a reference statement MUST be present. 1273 The 'anyxml' construct may be useful to represent an HTML banner 1274 containing markup elements, such as '<b>' and '</b>', and 1275 MAY be used in such cases. However, this construct SHOULD NOT be 1276 used if other YANG data node types can be used instead to represent 1277 the desired syntax and semantics. 1279 It has been found that the 'anyxml' statement is not implemented 1280 consistently across all servers. It is possible that mixed mode XML 1281 will not be supported, or configuration anyxml nodes will not 1282 supported. 1284 If there are referential integrity constraints associated with the 1285 desired semantics that can be represented with XPath, then one or 1286 more 'must' statements SHOULD be present. 1288 For list and leaf-list data definitions, if the number of possible 1289 instances is required to be bounded for all implementations, then the 1290 max-elements statements SHOULD be present. 1292 If any 'must' or 'when' statements are used within the data 1293 definition, then the data definition description statement SHOULD 1294 describe the purpose of each one. 1296 The "choice" statement is allowed to be directly present within a 1297 "case" statement in YANG 1.1. This needs to be considered carefully. 1298 Consider simply including the nested "choice" as additional "case" 1299 statements within the parent "choice" statement. Note that the 1300 "mandatory" and "default" statements within a nested "choice" 1301 statement only apply if the "case" containing the nested "choice" 1302 statement is first selected. 1304 5.15. Operation Definitions 1306 If the operation semantics are defined in an external document (other 1307 than another YANG module indicated by an import statement), then a 1308 reference statement MUST be present. 1310 If the operation impacts system behavior in some way, it SHOULD be 1311 mentioned in the description statement. 1313 If the operation is potentially harmful to system behavior in some 1314 way, it MUST be mentioned in the Security Considerations section of 1315 the document. 1317 5.16. Notification Definitions 1319 The description statement MUST be present. 1321 If the notification semantics are defined in an external document 1322 (other than another YANG module indicated by an import statement), 1323 then a reference statement MUST be present. 1325 If the notification refers to a specific resource instance, then this 1326 instance SHOULD be identified in the notification data. This is 1327 usually done by including 'leafref' leaf nodes with the key leaf 1328 values for the resource instance. For example: 1330 notification interface-up { 1331 description "Sent when an interface is activated."; 1332 leaf name { 1333 type leafref { 1334 path "/if:interfaces/if:interface/if:name"; 1335 } 1336 } 1337 } 1339 Note that there are no formal YANG statements to identify any data 1340 node resources associated with a notification. The description 1341 statement for the notification SHOULD specify if and how the 1342 notification identifies any data node resources associated with the 1343 specific event. 1345 5.17. Feature Definitions 1347 The YANG "feature" statement is used to define a label for a set of 1348 optional functionality within a module. The "if-feature" statement 1349 is used in the YANG statements associated with a feature. 1351 The set of YANG features available in a module should be considered 1352 carefully. The description-stmt within a feature-stmt MUST specify 1353 any interactions with other features. 1355 If there is a large set of objects associated with a YANG feature, 1356 then consider moving those objects to a separate module, instead of 1357 using a YANG feature. Note that the set of features within a module 1358 is easily discovered by the reader, but the set of related modules 1359 within the entire YANG library is not as easy to identity. Module 1360 names with a common prefix can help readers identity the set of 1361 related modules, but this assumes the reader will have discovered and 1362 installed all the relevant modules. 1364 Another consideration for deciding whether to create a new module or 1365 add a YANG feature is the stability of the module in question. It 1366 may be desirable to have a stable base module that is not changed 1367 frequently. If new functionality is placed in a separate module, 1368 then the base module does not need to be republished. If it is 1369 designed as a YANG feature then the module will need to be 1370 republished. 1372 If one feature requires implementation of another feature, then an 1373 "if-feature" statement SHOULD be used in the dependent "feature" 1374 statement. 1376 For example, feature2 requires implementation of feature1: 1378 feature feature1 { 1379 description "Some protocol feature"; 1380 } 1382 feature feature2 { 1383 if-feature "feature1"; 1384 description "Another protocol feature"; 1385 } 1387 5.18. Augment Statements 1389 The YANG "augment" statement is used to define a set of data 1390 definition statements that will be added as child nodes of a target 1391 data node. The module namespace for these data nodes will be the 1392 augmenting module, not the augmented module. 1394 A top-level "augment" statement SHOULD NOT be used if the target data 1395 node is in the same module or submodule as the evaluated "augment" 1396 statement. The data definition statements SHOULD be added inline 1397 instead. 1399 5.18.1. Conditional Augment Statements 1401 The "augment" statement is often used together with the "when" 1402 statement and/or "if-feature" statement to make the augmentation 1403 conditional on some portion of the data model. 1405 The following example from [RFC7223] shows how a conditional 1406 container called "ethernet" is added to the "interface" list only for 1407 entries of the type "ethernetCsmacd". 1409 augment "/if:interfaces/if:interface" { 1410 when "if:type = 'ianaift:ethernetCsmacd'"; 1412 container ethernet { 1413 leaf duplex { 1414 ... 1415 } 1416 } 1417 } 1419 5.18.2. Conditionally Mandatory Data Definition Statements 1421 YANG has very specific rules about how configuration data can be 1422 updated in new releases of a module. These rules allow an "old 1423 client" to continue interoperating with a "new server". 1425 If data nodes are added to an existing entry, the old client MUST NOT 1426 be required to provide any mandatory parameters that were not in the 1427 original module definition. 1429 It is possible to add conditional augment statements such that the 1430 old client would not know about the new condition, and would not 1431 specify the new condition. The conditional augment statement can 1432 contain mandatory objects only if the condition is false unless 1433 explicitly requested by the client. 1435 Only a conditional augment statement that uses the "when" statement 1436 form of condition can be used in this manner. The YANG features 1437 enabled on the server cannot be controlled by the client in any way, 1438 so it is not safe to add mandatory augmenting data nodes based on the 1439 "if-feature" statement. 1441 The XPath "when" statement condition MUST NOT reference data outside 1442 of target data node because the client does not have any control over 1443 this external data. 1445 In the following dummy example, it is OK to augment the "interface" 1446 entry with "mandatory-leaf" because the augmentation depends on 1447 support for "some-new-iftype". The old client does not know about 1448 this type so it would never select this type, and therefore not be 1449 adding a mandatory data node. 1451 module my-module { 1452 ... 1454 identity some-new-iftype { 1455 base iana:iana-interface-type; 1456 } 1458 augment "/if:interfaces/if:interface" { 1459 when "if:type = 'mymod:some-new-iftype'"; 1461 leaf mandatory-leaf { 1462 mandatory true; 1463 ... 1464 } 1465 } 1466 } 1468 Note that this practice is safe only for creating data resources. It 1469 is not safe for replacing or modifying resources if the client does 1470 not know about the new condition. The YANG data model MUST be 1471 packaged in a way that requires the client to be aware of the 1472 mandatory data nodes if it is aware of the condition for this data. 1473 In the example above, the "some-new-iftype" identity is defined in 1474 the same module as the "mandatory-leaf" data definition statement. 1476 This practice is not safe for identities defined in a common module 1477 such as "iana-if-type" because the client is not required to know 1478 about "my-module" just because it knows about the "iana-if-type" 1479 module. 1481 5.19. Deviation Statements 1483 The YANG "deviation" statement cannot appear in IETF YANG modules, 1484 but it can be useful for documenting server capabilities. Deviation 1485 statements are not reusable and typically not shared across all 1486 platforms. 1488 There are several reasons that deviations might be needed in an 1489 implementation, e.g., an object cannot be supported on all platforms, 1490 or feature delivery is done in multiple development phases. 1492 It is suggested that deviation statements be defined in separate 1493 modules from regular YANG definitions. This allows the deviations to 1494 be platform-specific and/or temporary. 1496 The "max-elements" statement is intended to describe an architectural 1497 limit to the number of list entries. It is not intended to describe 1498 platform limitations. It is better to use a "deviation" statement 1499 for the platforms that have a hard resource limit. 1501 Example documenting platform resource limits: 1503 Wrong: (max-elements in the list itself) 1505 container backups { 1506 list backup { 1507 ... 1508 max-elements 10; 1509 ... 1510 } 1511 } 1513 Correct: (max-elements in a deviation) 1515 deviation /bk:backups/bk:backup { 1516 deviate add { 1517 max-elements 10; 1518 } 1519 } 1521 5.20. Extension Statements 1523 The YANG "extension" statement is used to specify external 1524 definitions. This appears in the YANG syntax as an 1525 "unknown-statement". Usage of extension statements in a published 1526 module needs to be considered carefully. 1528 The following guidelines apply to the usage of YANG extensions: 1530 o The semantics of the extension MUST NOT contradict any YANG 1531 statements. Extensions can add semantics not covered by the 1532 normal YANG statements. 1534 o The module containing the extension statement MUST clearly 1535 identify the conformance requirements for the extension. It 1536 should be clear whether all implementations of the YANG module 1537 containing the extension need to also implement the extension. If 1538 not, identify what conditions apply that would require 1539 implementation of the extension. 1541 o The extension MUST clearly identify where it can be used within 1542 other YANG statements. 1544 o The extension MUST clearly identify if YANG statements or other 1545 extensions are allowed or required within the extension as sub- 1546 statements. 1548 5.21. Data Correlation 1550 Data can be correlated in various ways, using common data types, 1551 common data naming, and common data organization. There are several 1552 ways to extend the functionality of a module, based on the degree of 1553 coupling between the old and new functionality: 1555 o inline: update the module with new protocol-accessible objects. 1556 The naming and data organization of the original objects is used. 1557 The new objects are in the original module namespace. 1559 o augment: create a new module with new protocol-accessible objects 1560 that augment the original data structure. The naming and data 1561 organization of the original objects is used. The new objects are 1562 in the new module namespace. 1564 o mirror: create new objects in a new module or the original module, 1565 except use new a naming scheme and data location. The naming can 1566 be coupled in different ways. Tight coupling is achieved with a 1567 "leafref" data type, with the "require-instance" sub-statement set 1568 to "true". This method SHOULD be used. 1570 If the new data instances are not limited to the values in use in the 1571 original data structure, then the "require-instance" sub-statement 1572 MUST be set to "false". Loose coupling is achieved by using key 1573 leafs with the same data type as the original data structure. This 1574 has the same semantics as setting the "require-instance" sub- 1575 statement to "false". 1577 It is sometimes useful to separate configuration and operational 1578 state, so that they do not not even share the exact same naming 1579 characteristics. The correlation between configuration the 1580 operational state data that is affected by changes in configuration 1581 is a complex problem. There may not be a simple 1:1 relationship 1582 between a configuration data node and an operational data node. 1583 Further work is needed in YANG to clarify this relationship. 1584 Protocol work may also be needed to allow a client to retrieve this 1585 type of information from a server. At this time the best practice is 1586 to clearly document any relationship to other data structures in the 1587 "description" statement. 1589 5.22. Operational State 1591 In YANG, any data that has a "config" statement value of "false" 1592 could be considered operational state. The relationship between 1593 configuration (i.e., "config" statement has a value of "true") and 1594 operational state can be complex. 1596 One challenge for client developers is determining if the configured 1597 value is being used, which requires the developer to know which 1598 operational state parameters are associated with the particular 1599 configuration object (or group of objects). 1601 The simplest interaction between configuration and operational state 1602 is "none". For example, the arbitrary administrative name or 1603 sequence number assigned to an access control rule. The configured 1604 value is always the value that is being used by the system. 1606 However, some configuration parameters interact with routing and 1607 other signalling protocols, such that the operational value in use by 1608 the system may not be the same as the configured value. Other 1609 parameters specify the desired state, but environmental and other 1610 factors can cause the actual state to be different. 1612 For example a "temperature" configuration setting only represents the 1613 desired temperature. An operational state parameter is needed that 1614 reports the actual temperature in order to determine if the cooling 1615 system is operating correctly. YANG has no mechanism other than the 1616 "description" statement to associate the desired temperature and the 1617 actual temperature. 1619 Careful consideration needs to be given to the location of 1620 operational state data. It can either be located within the 1621 configuration subtree for which it applies, or it can be located 1622 outside the particular configuration subtree. Placing operation 1623 state within the configuration subtree is appropriate if the 1624 operational values can only exist if the configuration exists. 1626 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1627 are an example of a complex relationship between configuration and 1628 operational state. The operational values can include interface 1629 entries that have been discovered or initialized by the system. An 1630 interface may be in use that has not been configured at all. 1631 Therefore, the operational state for an interface cannot be located 1632 within the configuration for that same interface. 1634 Sometimes the configured value represents some sort of procedure to 1635 be followed, in which the system will select an actual value, based 1636 on protocol negotiation. 1638 leaf duplex-admin-mode { 1639 type enumeration { 1640 enum auto; 1641 enum half; 1642 enum full; 1643 } 1644 } 1646 leaf duplex-oper-mode { 1647 config false; 1648 type enumeration { 1649 enum half; 1650 enum full; 1651 } 1652 } 1654 For example a "duplex" mode configuration may be "auto" to auto- 1655 negotiate the actual value to be used. The operational parameter 1656 will never contain the value "auto". It will always contain the 1657 result of the auto-negotiation, such as "half" or "full". This is 1658 just one way in which the configuration data model is not exactly the 1659 same as the operational data model. Another is if the detailed 1660 properties of the data are different for configured vs. learned 1661 entries. 1663 If all the data model properties are aligned between configuration 1664 and operational data, then it can be useful to define the 1665 configuration parameters within a grouping, and then replicate that 1666 grouping within the operational state portion of the data model. 1668 grouping parms { 1669 // do not use config-stmt in any of the nodes 1670 // placed in this grouping 1671 } 1673 container foo { 1674 uses parms; // these are all config=true by default 1675 state { 1676 config false; // only exists if foo config exists 1677 uses parms; 1678 } 1679 } 1681 Note that this mechanism can also be used if the configuration and 1682 operational state data are in separate sub-trees: 1684 container bar { // bar config can exist without bar-state 1685 config true; 1686 uses parms; 1687 } 1689 container bar-state { // bar-state can exist without bar 1690 config false; 1691 uses parms; 1692 } 1694 The need to replicate objects or define different operational state 1695 objects depends on the data model. It is not possible to define one 1696 approach that will be optimal for all data models. Designers SHOULD 1697 describe the relationship in detail between configuration objects and 1698 any associated operational state objects. The "description" 1699 statements for both the configuration and the operational state 1700 SHOULD be used for this purpose. 1702 5.23. Performance Considerations 1704 It is generally likely that certain YANG statements require more 1705 runtime resources than other statements. Although there are no 1706 performance requirements for YANG validation, the following 1707 information MAY be considered when designing YANG data models: 1709 o Lists are generally more expensive than containers 1711 o "when-stmt" evaluation is generally more expensive than 1712 "if-feature" or "choice" statements 1714 o "must" statement is generally more expensive than "min-entries", 1715 "max-entries", "mandatory", or "unique" statements 1717 o "identityref" leafs are generally more expensive than 1718 "enumeration" leafs 1720 o "leafref" and "instance-identifier" types with "requite-instance" 1721 set to true are generally more expensive than if 1722 "require-instance" is set to false 1724 5.24. YANG 1.1 Guidelines 1726 TODO: need more input on YANG 1.1 guidelines 1728 5.24.1. Importing Multiple Revisions 1730 Standard modules SHOULD NOT import multiple revisions of the same 1731 module into a module. This MAY be done if the authors can 1732 demonstrate that the "avoided" definitions from most recent of the 1733 multiple revisions are somehow broken or harmful to interoperability. 1735 5.24.2. Using Feature Logic 1737 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 1738 "description" statement SHOULD describe the "if-feature" logic in 1739 text, to help readers understand the module. 1741 YANG features SHOULD be used instead of the "when" statement, if 1742 possible. This reduces server implementation complexity and might 1743 reduce runtime resource requirements as well. 1745 5.24.3. anyxml vs. anydata 1747 The "anyxml" statement MUST NOT be used to represent a conceptual 1748 subtree of YANG data nodes. The "anydata" statement MUST be used for 1749 this purpose. 1751 6. IANA Considerations 1753 This document registers one URI in the IETF XML registry [RFC3688]. 1755 The following registration has been made: 1757 URI: urn:ietf:params:xml:ns:yang:ietf-template 1759 Registrant Contact: The NETMOD WG of the IETF. 1761 XML: N/A, the requested URI is an XML namespace. 1763 Per this document, the following assignment has been made in the YANG 1764 Module Names Registry for the YANG module template in Appendix C. 1766 +-----------+-------------------------------------------+ 1767 | Field | Value | 1768 +-----------+-------------------------------------------+ 1769 | Name | ietf-template | 1770 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 1771 | Prefix | temp | 1772 | Reference | RFC XXXX | 1773 +-----------+-------------------------------------------+ 1775 YANG Registry Assignment 1777 7. Security Considerations 1779 This document defines documentation guidelines for NETCONF content 1780 defined with the YANG data modeling language. The guidelines for how 1781 to write a Security Considerations section for a YANG module are 1782 defined in the online document 1784 http://trac.tools.ietf.org/area/ops/trac/wiki/ 1785 yang-security-guidelines 1787 This document does not introduce any new or increased security risks 1788 into the management system. 1790 The following section contains the security considerations template 1791 dated 2010-06-16. Be sure to check the webpage at the URL listed 1792 above in case there is a more recent version available. 1794 Each specification that defines one or more YANG modules MUST contain 1795 a section that discusses security considerations relevant to those 1796 modules. This section MUST be patterned after the latest approved 1797 template (available at 1799 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 1801 In particular, writable data nodes that could be especially 1802 disruptive if abused MUST be explicitly listed by name and the 1803 associated security risks MUST be spelled out. 1805 Similarly, readable data nodes that contain especially sensitive 1806 information or that raise significant privacy concerns MUST be 1807 explicitly listed by name and the reasons for the sensitivity/privacy 1808 concerns MUST be explained. 1810 Further, if new RPC operations have been defined, then the security 1811 considerations of each new RPC operation MUST be explained. 1813 7.1. Security Considerations Section Template 1815 X. Security Considerations 1817 The YANG module defined in this memo is designed to be accessed via 1818 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1819 secure transport layer and the mandatory-to-implement secure 1820 transport is SSH [RFC6242]. 1822 -- if you have any writable data nodes (those are all the 1823 -- "config true" nodes, and remember, that is the default) 1824 -- describe their specific sensitivity or vulnerability. 1826 There are a number of data nodes defined in this YANG module which 1827 are writable/creatable/deletable (i.e., config true, which is the 1828 default). These data nodes may be considered sensitive or vulnerable 1829 in some network environments. Write operations (e.g., edit-config) 1830 to these data nodes without proper protection can have a negative 1831 effect on network operations. These are the subtrees and data nodes 1832 and their sensitivity/vulnerability: 1834 1836 -- for all YANG modules you must evaluate whether any readable data 1837 -- nodes (those are all the "config false" nodes, but also all other 1838 -- nodes, because they can also be read via operations like get or 1839 -- get-config) are sensitive or vulnerable (for instance, if they 1840 -- might reveal customer information or violate personal privacy 1841 -- laws such as those of the European Union if exposed to 1842 -- unauthorized parties) 1844 Some of the readable data nodes in this YANG module may be considered 1845 sensitive or vulnerable in some network environments. It is thus 1846 important to control read access (e.g., via get, get-config, or 1847 notification) to these data nodes. These are the subtrees and data 1848 nodes and their sensitivity/vulnerability: 1850 1852 -- if your YANG module has defined any rpc operations 1853 -- describe their specific sensitivity or vulnerability. 1855 Some of the RPC operations in this YANG module may be considered 1856 sensitive or vulnerable in some network environments. It is thus 1857 important to control access to these operations. These are the 1858 operations and their sensitivity/vulnerability: 1860 1862 8. Acknowledgments 1864 The structure and contents of this document are adapted from 1865 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 1867 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 1868 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 1869 contributions to this document. 1871 9. Changes Since RFC 6087 1873 The following changes have been made to the guidelines published in 1874 [RFC6087]: 1876 o Updated NETCONF reference from RFC 4741 to RFC 6241 1878 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 1880 o Updated YANG Types reference from RFC 6021 to RFC 6991 1882 o Updated obsolete URLs for IETF resources 1884 o Changed top-level data node guideline 1886 o Clarified XPath usage for a literal value representing a YANG 1887 identity 1889 o Clarified XPath usage for a when-stmt 1891 o Clarified XPath usage for 'proceeding-sibling' and 1892 'following-sibling' axes 1894 o Added terminology guidelines 1896 o Added YANG tree diagram definition and guideline 1898 o Updated XPath guidelines for type conversions and function library 1899 usage. 1901 o Updated data types section 1903 o Updated notifications section 1905 o Clarified conditional key leaf nodes 1907 o Clarify usage of 'uint64' and 'int64' data types 1909 o Added text on YANG feature usage 1911 o Added Identifier Naming Conventions 1913 o Clarified use of mandatory nodes with conditional augmentations 1915 o Clarified namespace and domain conventions for example modules 1917 10. References 1919 10.1. Normative References 1921 [I-D.ietf-netmod-rfc6020bis] 1922 Bjorklund, M., "YANG - A Data Modeling Language for the 1923 Network Configuration Protocol (NETCONF)", 1924 draft-ietf-netmod-rfc6020bis-07 (work in progress), 1925 September 2015. 1927 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1928 Requirement Levels", BCP 14, RFC 2119, March 1997. 1930 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1931 RFC 2223, October 1997. 1933 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1934 January 2004. 1936 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1937 Resource Identifier (URI): Generic Syntax", STD 66, 1938 RFC 3986, January 2005. 1940 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 1941 to the IETF Trust", BCP 78, RFC 5378, November 2008. 1943 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 1944 and Boilerplates", RFC 5741, December 2009. 1946 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1947 Network Configuration Protocol (NETCONF)", RFC 6020, 1948 October 2010. 1950 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1951 and A. Bierman, Ed., "Network Configuration Protocol 1952 (NETCONF)", RFC 6241, June 2011. 1954 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1955 July 2013. 1957 [W3C.REC-xpath-19991116] 1958 Clark, J. and S. DeRose, "XML Path Language (XPath) 1959 Version 1.0", World Wide Web Consortium 1960 Recommendation REC-xpath-19991116, November 1999, 1961 . 1963 10.2. Informative References 1965 [RFC-STYLE] 1966 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 1967 Style", September 2009, 1968 . 1970 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1971 Documents", BCP 111, RFC 4181, September 2005. 1973 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1974 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1975 May 2008. 1977 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 1978 Data Model Documents", RFC 6087, January 2011. 1980 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1981 Management", RFC 7223, May 2014. 1983 Appendix A. Change Log 1985 -- RFC Ed.: remove this section before publication. 1987 A.1. 04 to 05 1989 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 1990 no YANG 1.1 features needed 1992 o Changed SHOULD follow YANG naming conventions to MUST follow (for 1993 standards track documents only) 1995 o Clarified module naming conventions for normative modules, example 1996 modules, and modules from other SDOs. 1998 o Added prefix value selection guidelines 2000 o Added new section on guidelines for reusable groupings 2002 o Made header guidelines less IETF-specific 2004 o Added new section on guidelines for extension statements 2006 o Added guidelines for nested "choice" statement within a "case" 2007 statement 2009 A.2. 03 ot 04 2011 o Added sections for deviation statements and performance 2012 considerations 2014 o Added YANG 1.1 section 2016 o Updated YANG reference from 1.0 to 1.1 2018 A.3. 02 to 03 2020 o Updated draft based on github data tracker issues added by Benoit 2021 Clause (Issues 12 - 18) 2023 A.4. 01 to 02 2025 o Updated draft based on mailing list comments. 2027 A.5. 00 to 01 2029 All issues from the issue tracker have been addressed. 2031 https://github.com/netmod-wg/rfc6087bis/issues 2033 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 2034 can use an Informative reference to this RFC for tree diagrams. 2035 Updated guidelines to reference this RFC when tree diagrams are 2036 used 2038 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2039 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2040 functions 2042 o Issue 3: XPath function document order issues: Added paragraph in 2043 XPath usage section about node-set ordering for 'local-name', 2044 'namespace-uri', 'name', 'string' and 'number' functions. Also 2045 any function that implicitly converts a node-set to a string. 2047 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2048 and text in XPath usage section already has proposed text from 2049 Lada. 2051 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2052 exception and example in XPath Usage section for augmented nodes. 2054 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2055 to 'numeric and boolean expressions' 2057 o Issue 7: XPath module containment: Added sub-section on XPath 2058 wildcards 2060 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2061 section about transitioning from active to deprecated and then to 2062 obsolete. 2064 o Issue 9: resource identification in notifications: Add text to 2065 Notifications section about identifying resources and using the 2066 leafref data type. 2068 o Issue 10: single quoted strings: Added text to Data Types section 2069 about using a single-quoted string for patterns. 2071 Appendix B. Module Review Checklist 2073 This section is adapted from RFC 4181. 2075 The purpose of a YANG module review is to review the YANG module both 2076 for technical correctness and for adherence to IETF documentation 2077 requirements. The following checklist may be helpful when reviewing 2078 an Internet-Draft: 2080 o I-D Boilerplate -- verify that the draft contains the required 2081 Internet-Draft boilerplate (see 2082 http://www.ietf.org/id-info/guidelines.html), including the 2083 appropriate statement to permit publication as an RFC, and that 2084 I-D boilerplate does not contain references or section numbers. 2086 o Abstract -- verify that the abstract does not contain references, 2087 that it does not have a section number, and that its content 2088 follows the guidelines in 2089 http://www.ietf.org/id-info/guidelines.html. 2091 o Copyright Notice -- verify that the draft has the appropriate text 2092 regarding the rights that document contributers provide to the 2093 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2094 copyright notice at the beginning of the document. The IETF Trust 2095 Legal Provisions (TLP) can be found at: 2097 http://trustee.ietf.org/license-info/ 2099 o Security Considerations section -- verify that the draft uses the 2100 latest approved template from the OPS area website (http:// 2101 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2102 and that the guidelines therein have been followed. 2104 o IANA Considerations section -- this section must always be 2105 present. For each module within the document, ensure that the 2106 IANA Considerations section contains entries for the following 2107 IANA registries: 2109 XML Namespace Registry: Register the YANG module namespace. 2111 YANG Module Registry: Register the YANG module name, prefix, 2112 namespace, and RFC number, according to the rules specified 2113 in [I-D.ietf-netmod-rfc6020bis]. 2115 o References -- verify that the references are properly divided 2116 between normative and informative references, that RFC 2119 is 2117 included as a normative reference if the terminology defined 2118 therein is used in the document, that all references required by 2119 the boilerplate are present, that all YANG modules containing 2120 imported items are cited as normative references, and that all 2121 citations point to the most current RFCs unless there is a valid 2122 reason to do otherwise (for example, it is OK to include an 2123 informative reference to a previous version of a specification to 2124 help explain a feature included for backward compatibility). Be 2125 sure citations for all imported modules are present somewhere in 2126 the document text (outside the YANG module). 2128 o License -- verify that the draft contains the Simplified BSD 2129 License in each YANG module or submodule. Some guidelines related 2130 to this requirement are described in Section 4.1. Make sure that 2131 the correct year is used in all copyright dates. Use the approved 2132 text from the latest Trust Legal Provisions (TLP) document, which 2133 can be found at: 2135 http://trustee.ietf.org/license-info/ 2137 o Other Issues -- check for any issues mentioned in 2138 http://www.ietf.org/id-info/checklist.html that are not covered 2139 elsewhere. 2141 o Technical Content -- review the actual technical content for 2142 compliance with the guidelines in this document. The use of a 2143 YANG module compiler is recommended when checking for syntax 2144 errors. A list of freely available tools and other information 2145 can be found at: 2147 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2149 Checking for correct syntax, however, is only part of the job. 2150 It is just as important to actually read the YANG module document 2151 from the point of view of a potential implementor. It is 2152 particularly important to check that description statements are 2153 sufficiently clear and unambiguous to allow interoperable 2154 implementations to be created. 2156 Appendix C. YANG Module Template 2158 file "ietf-template@2010-05-18.yang" 2160 module ietf-template { 2162 // replace this string with a unique namespace URN value 2163 namespace 2164 "urn:ietf:params:xml:ns:yang:ietf-template"; 2166 // replace this string, and try to pick a unique prefix 2167 prefix "temp"; 2169 // import statements here: e.g., 2170 // import ietf-yang-types { prefix yang; } 2171 // import ietf-inet-types { prefix inet; } 2173 // identify the IETF working group if applicable 2174 organization 2175 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2177 // update this contact statement with your info 2178 contact 2179 "WG Web: 2180 WG List: 2182 WG Chair: your-WG-chair 2183 2185 Editor: your-name 2186 "; 2188 // replace the first sentence in this description statement. 2189 // replace the copyright notice with the most recent 2190 // version, if it has been updated since the publication 2191 // of this document 2192 description 2193 "This module defines a template for other YANG modules. 2195 Copyright (c) IETF Trust and the persons 2196 identified as authors of the code. All rights reserved. 2198 Redistribution and use in source and binary forms, with or 2199 without modification, is permitted pursuant to, and subject 2200 to the license terms contained in, the Simplified BSD License 2201 set forth in Section 4.c of the IETF Trust's Legal Provisions 2202 Relating to IETF Documents 2203 (http://trustee.ietf.org/license-info). 2205 This version of this YANG module is part of RFC XXXX; see 2206 the RFC itself for full legal notices."; 2208 // RFC Ed.: replace XXXX with actual RFC number and remove 2209 // this note 2211 reference "RFC XXXX"; 2213 // RFC Ed.: remove this note 2214 // Note: extracted from RFC XXXX 2216 // replace '2010-05-18' with the module publication date 2217 // The format is (year-month-day) 2218 revision "2010-05-18" { 2219 description 2220 "Initial version"; 2221 } 2223 // extension statements 2225 // feature statements 2227 // identity statements 2229 // typedef statements 2231 // grouping statements 2233 // data definition statements 2235 // augment statements 2237 // rpc statements 2239 // notification statements 2241 // DO NOT put deviation statements in a published module 2243 } 2245 2247 Author's Address 2249 Andy Bierman 2250 YumaWorks 2252 Email: andy@yumaworks.com