idnits 2.17.1 draft-ietf-netmod-rfc6087bis-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 18, 2018) is 2290 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC5378' is defined on line 2470, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-04 -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Obsoletes: 6087 (if approved) January 18, 2018 5 Intended status: BCP 6 Expires: July 22, 2018 8 Guidelines for Authors and Reviewers of YANG Data Model Documents 9 draft-ietf-netmod-rfc6087bis-16 11 Abstract 13 This memo provides guidelines for authors and reviewers of Standards 14 Track specifications containing YANG data model modules. Applicable 15 portions may be used as a basis for reviews of other YANG data model 16 documents. Recommendations and procedures are defined, which are 17 intended to increase interoperability and usability of Network 18 Configuration Protocol (NETCONF) and RESTCONF protocol 19 implementations that utilize YANG data model modules. This document 20 obsoletes RFC 6087. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 22, 2018. 39 Copyright Notice 41 Copyright (c) 2018 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8 60 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8 61 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 63 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 3. General Documentation Guidelines . . . . . . . . . . . . . . . 10 65 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10 66 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 10 67 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11 68 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11 69 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 70 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 71 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 72 3.7. Security Considerations Section . . . . . . . . . . . . . 13 73 3.7.1. Security Considerations Section Template . . . . . . . 13 74 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 14 75 3.8.1. Documents that Create a New Namespace . . . . . . . . 15 76 3.8.2. Documents that Extend an Existing Namespace . . . . . 15 77 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15 78 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 79 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16 80 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 16 81 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 17 82 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 17 83 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 18 84 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 19 85 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 19 86 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 20 87 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 20 88 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 21 89 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 21 90 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 22 91 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 23 92 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 23 93 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 24 94 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 24 95 4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 25 96 4.8. Module Header, Meta, and Revision Statements . . . . . . . 26 97 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 27 98 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 28 99 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 29 100 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 29 101 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 30 102 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 31 103 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 32 104 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 33 105 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 34 106 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 35 107 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 35 108 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 37 109 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 37 110 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 38 111 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 38 112 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 39 113 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 39 114 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 39 115 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 40 116 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 40 117 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 40 118 4.19.2. Conditionally Mandatory Data Definition Statements . . 41 119 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 42 120 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 43 121 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 44 122 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 45 123 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 46 124 4.23.1. Combining Operational State and Configuration Data . . 46 125 4.23.2. Representing Operational Values of Configuration 126 Data . . . . . . . . . . . . . . . . . . . . . . . . . 47 127 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 47 128 4.24. Performance Considerations . . . . . . . . . . . . . . . . 51 129 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 51 130 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 52 131 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 52 132 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 52 133 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 52 134 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 52 135 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 53 136 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 137 6. Security Considerations . . . . . . . . . . . . . . . . . . . 56 138 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 57 139 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 140 8.1. Normative References . . . . . . . . . . . . . . . . . . . 58 141 8.2. Informative References . . . . . . . . . . . . . . . . . . 58 142 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61 143 A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 61 144 A.2. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 61 145 A.3. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 146 A.4. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 147 A.5. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 62 148 A.6. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 62 149 A.7. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 62 150 A.8. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 151 A.9. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 152 A.10. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 63 153 A.11. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 154 A.12. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 155 A.13. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 64 156 A.14. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 157 A.15. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 158 A.16. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 159 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66 160 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68 161 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 163 1. Introduction 165 The standardization of network configuration interfaces for use with 166 network configuration management protocols, such as the Network 167 Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a 168 modular set of data models, which can be reused and extended over 169 time. 171 This document defines a set of usage guidelines for Standards Track 172 documents containing [RFC7950] data models. YANG is used to define 173 the data structures, protocol operations, and notification content 174 used within a NETCONF and/or RESTCONF server. A NETCONF or RESTCONF 175 server that supports a particular YANG module will support client 176 NETCONF and/or RESTCONF operation requests, as indicated by the 177 specific content defined in the YANG module. 179 Many YANG constructs are defined as optional to use, such as the 180 description statement. However, in order to make YANG modules more 181 useful, it is desirable to define a set of usage guidelines that 182 entails a higher level of compliance than the minimum level defined 183 in the YANG specification. 185 In addition, YANG allows constructs such as infinite length 186 identifiers and string values, or top-level mandatory nodes, that a 187 compliant server is not required to support. Only constructs that 188 all servers are required to support can be used in IETF YANG modules. 190 This document defines usage guidelines related to the NETCONF 191 operations layer and NETCONF content layer, as defined in [RFC6241], 192 and the RESTCONF methods and RESTCONF resources, as defined in 193 [RFC8040], 195 These guidelines are intended to be used by authors and reviewers to 196 improve the readability and interoperability of published YANG data 197 models. 199 Note that this document is not a YANG tutorial and the reader is 200 expected to know the YANG data modeling language before using this 201 document. 203 1.1. Changes Since RFC 6087 205 The following changes have been made to the guidelines published in 206 [RFC6087]: 208 o Updated NETCONF reference from RFC 4741 to RFC 6241 209 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 211 o Updated YANG Types reference from RFC 6021 to RFC 6991 213 o Updated obsolete URLs for IETF resources 215 o Changed top-level data node guideline 217 o Clarified XPath usage for a literal value representing a YANG 218 identity 220 o Clarified XPath usage for a when-stmt 222 o Clarified XPath usage for 'proceeding-sibling' and 223 'following-sibling' axes 225 o Added terminology guidelines 227 o Added YANG tree diagram guidelines 229 o Updated XPath guidelines for type conversions and function library 230 usage. 232 o Updated data types section 234 o Updated notifications section 236 o Clarified conditional key leaf nodes 238 o Clarify usage of 'uint64' and 'int64' data types 240 o Added text on YANG feature usage 242 o Added Identifier Naming Conventions 244 o Clarified use of mandatory nodes with conditional augmentations 246 o Clarified namespace and domain conventions for example modules 248 o Clarified conventions for identifying code components 250 o Added YANG 1.1 guidelines 252 o Added Data Model Constraints section 254 o Added mention of RESTCONF protocol 255 o Added guidelines for NMDA Revised Datastores 257 2. Terminology 259 2.1. Requirements Notation 261 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 262 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 263 document are to be interpreted as described in BCP 14 [RFC2119] 264 [RFC8174] when, and only when, they appear in all capitals, as shown 265 here. 267 RFC 2119 language is used here to express the views of the NETMOD 268 working group regarding content for YANG modules. YANG modules 269 complying with this document will treat the RFC 2119 terminology as 270 if it were describing best current practices. 272 2.2. NETCONF Terms 274 The following terms are defined in [RFC6241] and are not redefined 275 here: 277 o capabilities 279 o client 281 o operation 283 o server 285 2.3. YANG Terms 287 The following terms are defined in [RFC7950] and are not redefined 288 here: 290 o data node 292 o module 294 o namespace 296 o submodule 298 o version 300 o YANG 302 o YIN 304 Note that the term 'module' may be used as a generic term for a YANG 305 module or submodule. When describing properties that are specific to 306 submodules, the term 'submodule' is used instead. 308 2.4. NMDA Terms 310 The following terms are defined in the Network Management Datastore 311 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not 312 redefined here: 314 o configuration 316 o conventional configuration datastore 318 o datastore 320 o operational state 322 o operational state datastore 324 2.5. Terms 326 The following terms are used throughout this document: 328 o published: A stable release of a module or submodule. For example 329 the "Request for Comments" described in section 2.1 of [RFC2026] 330 is considered a stable publication. 332 o unpublished: An unstable release of a module or submodule. For 333 example the "Internet-Draft" described in section 2.2 of [RFC2026] 334 is considered an unstable publication that is a work-in-progress, 335 subject to change at any time. 337 o YANG fragment: A set of YANG statements that are not intended to 338 represent a complete YANG module or submodule. These statements 339 are not intended for actual use, except to provide an example of 340 YANG statement usage. The invalid syntax "..." is sometimes used 341 to indicate that additional YANG statements would be present in a 342 real YANG module. 344 3. General Documentation Guidelines 346 YANG data model modules under review are likely to be contained in 347 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 348 followed. The RFC Editor provides guidelines for authors of RFCs, 349 which are first published as Internet-Drafts. These guidelines 350 should be followed and are defined in [RFC7322] and updated in 351 [RFC7841] and "RFC Document Style" [RFC-STYLE]. 353 The following sections MUST be present in an Internet-Draft 354 containing a module: 356 o Narrative sections 358 o Definitions section 360 o Security Considerations section 362 o IANA Considerations section 364 o References section 366 There are three usage scenarios for YANG that can appear in an 367 Internet-Draft or RFC: 369 o normative module or submodule 371 o example module or submodule 373 o example YANG fragment not part of any module or submodule 375 The guidelines in this document refer mainly to a normative complete 376 module or submodule, but may be applicable to example modules and 377 YANG fragments as well. 379 3.1. Module Copyright 381 The module description statement MUST contain a reference to the 382 latest approved IETF Trust Copyright statement, which is available 383 online at: 385 http://trustee.ietf.org/license-info/ 387 3.2. Code Components 389 Each normative YANG module or submodule contained within an Internet- 390 Draft or RFC is considered to be a code component. The strings 391 "" and "" MUST be used to identify each code 392 component. 394 The "" tag SHOULD be followed by a string identifying 395 the file name specified in Section 5.2 of [RFC7950]. The name string 396 form that includes the revision-date SHOULD be used. The following 397 example is for the '2010-01-18' revision of the 'ietf-foo' module: 399 file "ietf-foo@2016-03-20.yang" 401 module ietf-foo { 402 namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; 403 prefix "foo"; 404 organization "..."; 405 contact "..."; 406 description "..."; 407 revision 2016-03-20 { 408 description "Latest revision"; 409 reference "RFC XXXX"; 410 } 411 // ... more statements 412 } 414 416 3.2.1. Example Modules 418 Example modules are not code components. The 419 convention MUST NOT be used for example modules. 421 An example module SHOULD be named using the term "example", followed 422 by a hyphen, followed by a descriptive name, e.g., "example-toaster". 424 3.3. Terminology Section 426 A terminology section MUST be present if any terms are defined in the 427 document or if any terms are imported from other documents. 429 If YANG tree diagrams are used, then a normative reference to the 430 YANG tree diagrams specification MUST be provided for each diagram. 431 (Refer to the example in the next section.) 433 3.4. Tree Diagrams 435 YANG tree diagrams provide a concise representation of a YANG module, 436 and SHOULD be included to help readers understand YANG module 437 structure. Guidelines on tree diagrams can be found in Section 3 of 438 [I-D.ietf-netmod-yang-tree-diagrams]. 440 The following example shows a simple YANG tree diagram 441 [I-D.ietf-netmod-yang-tree-diagrams]: 443 +--rw top-level-config-container 444 | +--rw config-list* [key-name] 445 | +--rw key-name string 446 | +--rw optional-parm? string 447 | +--rw mandatory-parm identityref 448 | +--ro read-only-leaf string 449 +--ro top-level-nonconfig-container 450 +--ro nonconfig-list* [name] 451 +--ro name string 452 +--ro type string 454 3.5. Narrative Sections 456 The narrative part MUST include an overview section that describes 457 the scope and field of application of the module(s) defined by the 458 specification and that specifies the relationship (if any) of these 459 modules to other standards, particularly to standards containing 460 other YANG modules. The narrative part SHOULD include one or more 461 sections to briefly describe the structure of the modules defined in 462 the specification. 464 If the module(s) defined by the specification imports definitions 465 from other modules (except for those defined in the [RFC7950] or 466 [RFC6991] documents), or are always implemented in conjunction with 467 other modules, then those facts MUST be noted in the overview 468 section, as MUST be noted any special interpretations of definitions 469 in other modules. 471 3.6. Definitions Section 473 This section contains the module(s) defined by the specification. 474 These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. 475 YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or 476 semantics are needed in the module. 478 A YIN syntax version of the module MAY also be present in the 479 document. There MAY also be other types of modules present in the 480 document, such as SMIv2, which are not affected by these guidelines. 482 Note that all YANG statements within a YANG module are considered 483 normative, if the module itself is considered normative, and not an 484 example module. The use of keywords defined in [RFC2119] apply to 485 YANG description statements in normative modules exactly as they 486 would in any other normative section. 488 Example YANG modules MUST NOT contain any normative text, including 489 any reserved words from [RFC2119]. 491 See Section 4 for guidelines on YANG usage. 493 3.7. Security Considerations Section 495 Each specification that defines one or more modules MUST contain a 496 section that discusses security considerations relevant to those 497 modules. 499 This section MUST be patterned after the latest approved template 500 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 501 yang-security-guidelines). Section 3.7.1 contains the security 502 considerations template dated 2013-05-08 and last updated 2017-12-21. 503 Authors MUST check the WEB page at the URL listed above in case there 504 is a more recent version available. 506 In particular: 508 o Writable data nodes that could be especially disruptive if abused 509 MUST be explicitly listed by name and the associated security 510 risks MUST be explained. 512 o Readable data nodes that contain especially sensitive information 513 or that raise significant privacy concerns MUST be explicitly 514 listed by name and the reasons for the sensitivity/privacy 515 concerns MUST be explained. 517 o Operations (i.e., YANG 'rpc' statements) that are potentially 518 harmful to system behavior or that raise significant privacy 519 concerns MUST be explicitly listed by name and the reasons for the 520 sensitivity/privacy concerns MUST be explained. 522 3.7.1. Security Considerations Section Template 524 X. Security Considerations 526 The YANG module specified in this document defines a schema for data 527 that is designed to be accessed via network management protocols such 528 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 529 is the secure transport layer, and the mandatory-to-implement secure 530 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 531 is HTTPS, and the mandatory-to-implement secure transport is TLS 532 [RFC5246]. 534 The NETCONF access control model [RFC6536] provides the means to 535 restrict access for particular NETCONF or RESTCONF users to a 536 preconfigured subset of all available NETCONF or RESTCONF protocol 537 operations and content. 539 -- if you have any writeable data nodes (those are all the 540 -- "config true" nodes, and remember, that is the default) 541 -- describe their specific sensitivity or vulnerability. 543 There are a number of data nodes defined in this YANG module that are 544 writable/creatable/deletable (i.e., config true, which is the 545 default). These data nodes may be considered sensitive or vulnerable 546 in some network environments. Write operations (e.g., edit-config) 547 to these data nodes without proper protection can have a negative 548 effect on network operations. These are the subtrees and data nodes 549 and their sensitivity/vulnerability: 551 553 -- for all YANG modules you must evaluate whether any readable data 554 -- nodes (those are all the "config false" nodes, but also all other 555 -- nodes, because they can also be read via operations like get or 556 -- get-config) are sensitive or vulnerable (for instance, if they 557 -- might reveal customer information or violate personal privacy 558 -- laws such as those of the European Union if exposed to 559 -- unauthorized parties) 561 Some of the readable data nodes in this YANG module may be considered 562 sensitive or vulnerable in some network environments. It is thus 563 important to control read access (e.g., via get, get-config, or 564 notification) to these data nodes. These are the subtrees and data 565 nodes and their sensitivity/vulnerability: 567 569 -- if your YANG module has defined any rpc operations 570 -- describe their specific sensitivity or vulnerability. 572 Some of the RPC operations in this YANG module may be considered 573 sensitive or vulnerable in some network environments. It is thus 574 important to control access to these operations. These are the 575 operations and their sensitivity/vulnerability: 577 579 3.8. IANA Considerations Section 581 In order to comply with IESG policy as set forth in 582 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 583 is submitted to the IESG for publication MUST contain an IANA 584 Considerations section. The requirements for this section vary 585 depending on what actions are required of the IANA. If there are no 586 IANA considerations applicable to the document, then the IANA 587 Considerations section stating that there are no actions is removed 588 by the RFC Editor before publication. Refer to the guidelines in 589 [RFC8126] for more details. 591 Each normative YANG module MUST be registered in the XML namespace 592 Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. 593 This applies to new modules and updated modules. Examples of these 594 registrations for the "ietf-template" module can be found in 595 Section 5. 597 3.8.1. Documents that Create a New Namespace 599 If an Internet-Draft defines a new namespace that is to be 600 administered by the IANA, then the document MUST include an IANA 601 Considerations section that specifies how the namespace is to be 602 administered. 604 Specifically, if any YANG module namespace statement value contained 605 in the document is not already registered with IANA, then a new YANG 606 Namespace registry entry MUST be requested from the IANA. The 607 [RFC7950] specification includes the procedure for this purpose in 608 its IANA Considerations section. 610 3.8.2. Documents that Extend an Existing Namespace 612 It is possible to extend an existing namespace using a YANG submodule 613 that belongs to an existing module already administered by IANA. In 614 this case, the document containing the main module MUST be updated to 615 use the latest revision of the submodule. 617 3.9. Reference Sections 619 For every import or include statement that appears in a module 620 contained in the specification, which identifies a module in a 621 separate document, a corresponding normative reference to that 622 document MUST appear in the Normative References section. The 623 reference MUST correspond to the specific module version actually 624 used within the specification. 626 For every normative reference statement that appears in a module 627 contained in the specification, which identifies a separate document, 628 a corresponding normative reference to that document SHOULD appear in 629 the Normative References section. The reference SHOULD correspond to 630 the specific document version actually used within the specification. 631 If the reference statement identifies an informative reference, which 632 identifies a separate document, a corresponding informative reference 633 to that document MAY appear in the Informative References section. 635 3.10. Validation Tools 637 All modules need to be validated before submission in an Internet 638 Draft. The 'pyang' YANG compiler is freely available from github: 640 https://github.com/mbj4668/pyang 642 If the 'pyang' compiler is used to validate a normative module, then 643 the "--ietf" command line option MUST be used to identify any IETF 644 guideline issues. 646 If the 'pyang' compiler is used to validate an example module, then 647 the "--ietf" command line option MAY be used to identify any IETF 648 guideline issues. 650 3.11. Module Extraction Tools 652 A version of 'rfcstrip' is available which will extract YANG modules 653 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 654 YANG module extraction is freely available: 656 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 658 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 660 can be extracted correctly. 662 3.12. Module Usage Examples 664 Each specification that defines one or more modules SHOULD contain 665 usage examples, either throughout the document or in an appendix. 666 This includes example instance document snippets in an appropriate 667 encoding (e.g., XML and/or JSON) to demonstrate the intended usage of 668 the YANG module(s). 670 4. YANG Usage Guidelines 672 Modules in IETF Standards Track specifications MUST comply with all 673 syntactic and semantic requirements of YANG [RFC7950]. The 674 guidelines in this section are intended to supplement the YANG 675 specification, which is intended to define a minimum set of 676 conformance requirements. 678 In order to promote interoperability and establish a set of practices 679 based on previous experience, the following sections establish usage 680 guidelines for specific YANG constructs. 682 Only guidelines that clarify or restrict the minimum conformance 683 requirements are included here. 685 4.1. Module Naming Conventions 687 Normative modules contained in Standards Track documents MUST be 688 named according to the guidelines in the IANA Considerations section 689 of [RFC7950]. 691 A distinctive word or acronym (e.g., protocol name or working group 692 acronym) SHOULD be used in the module name. If new definitions are 693 being defined to extend one or more existing modules, then the same 694 word or acronym should be reused, instead of creating a new one. 696 All published module names MUST be unique. For a YANG module 697 published in an RFC, this uniqueness is guaranteed by IANA. For 698 unpublished modules, the authors need to check that no other work in 699 progress is using the same module name. 701 Example modules are non-normative, and SHOULD be named with the 702 prefix "example-". 704 It is suggested that a stable prefix be selected representing the 705 entire organization. All normative YANG modules published by the 706 IETF MUST begin with the prefix "ietf-". Another standards 707 organization, such as the IEEE, might use the prefix "ieee-" for all 708 YANG modules. 710 Once a module name is published, it MUST NOT be reused, even if the 711 RFC containing the module is reclassified to 'Historic' status. A 712 module name cannot be changed in YANG, and this would be treated as a 713 a new module, not a name change. 715 4.2. Prefixes 717 All YANG definitions are scoped by the module containing the 718 definition being referenced. This allows definitions from multiple 719 modules to be used, even if the names are not unique. In the example 720 below, the identifier "foo" is used in all 3 modules: 722 module example-foo { 723 namespace "http://example.com/ns/foo"; 724 prefix f; 726 container foo; 727 } 729 module example-bar { 730 namespace "http://example.com/ns/bar"; 731 prefix b; 733 typedef foo { type uint32; } 734 } 736 module example-one { 737 namespace "http://example.com/ns/one"; 738 prefix one; 739 import example-foo { prefix f; } 740 import example-bar { prefix b; } 742 augment "/f:foo" { 743 leaf foo { type b:foo; } 744 } 745 } 747 YANG defines the following rules for prefix usage: 749 o Prefixes are never allowed for built in data types and YANG 750 keywords. 752 o A prefix MUST be used for any external statement (i.e., a 753 statement defined with the YANG "extension" statement) 755 o The proper module prefix MUST be used for all identifiers imported 756 from other modules 758 o The proper module prefix MUST be used for all identifiers included 759 from a submodule. 761 The following guidelines apply to prefix usage of the current (local) 762 module: 764 o The local module prefix SHOULD be used instead of no prefix in all 765 path expressions. 767 o The local module prefix MUST be used instead of no prefix in all 768 "default" statements for an "identityref" or "instance-identifier" 769 data type 771 o The local module prefix MAY be used for references to typedefs, 772 groupings, extensions, features, and identities defined in the 773 module. 775 Prefix values SHOULD be short, but also likely to be unique. Prefix 776 values SHOULD NOT conflict with known modules that have been 777 previously published. 779 4.3. Identifiers 781 Identifiers for all YANG identifiers in published modules MUST be 782 between 1 and 64 characters in length. These include any construct 783 specified as an 'identifier-arg-str' token in the ABNF in Section 13 784 of [RFC7950]. 786 4.3.1. Identifier Naming Conventions 788 Identifiers SHOULD follow a consistent naming pattern throughout the 789 module. Only lower-case letters, numbers, and dashes SHOULD be used 790 in identifier names. Upper-case characters and the underscore 791 character MAY be used if the identifier represents a well-known value 792 that uses these characters. 794 Identifiers SHOULD include complete words and/or well-known acronyms 795 or abbreviations. Child nodes within a container or list SHOULD NOT 796 replicate the parent identifier. YANG identifiers are hierarchical 797 and are only meant to be unique within the the set of sibling nodes 798 defined in the same module namespace. 800 It is permissible to use common identifiers such as "name" or "id" in 801 data definition statements, especially if these data nodes share a 802 common data type. 804 Identifiers SHOULD NOT carry any special semantics that identify data 805 modelling properties. Only YANG statements and YANG extension 806 statements are designed to convey machine readable data modelling 807 properties. For example, naming an object "config" or "state" does 808 not change whether it is configuration data or state data. Only 809 defined YANG statements or YANG extension statements can be used to 810 assign semantics in a machine readable format in YANG. 812 4.4. Defaults 814 In general, it is suggested that substatements containing very common 815 default values SHOULD NOT be present. The following substatements 816 are commonly used with the default value, which would make the module 817 difficult to read if used everywhere they are allowed. 819 +--------------+---------------+ 820 | Statement | Default Value | 821 +--------------+---------------+ 822 | config | true | 823 | mandatory | false | 824 | max-elements | unbounded | 825 | min-elements | 0 | 826 | ordered-by | system | 827 | status | current | 828 | yin-element | false | 829 +--------------+---------------+ 831 Statement Defaults 833 4.5. Conditional Statements 835 A module may be conceptually partitioned in several ways, using the 836 'if-feature' and/or 'when' statements. 838 Data model designers need to carefully consider all modularity 839 aspects, including the use of YANG conditional statements. 841 If a data definition is optional, depending on server support for a 842 NETCONF or RESTCONF protocol capability, then a YANG 'feature' 843 statement SHOULD be defined to indicate that the NETCONF or RESTCONF 844 capability is supported within the data model. 846 If any notification data, or any data definition, for a non- 847 configuration data node is not mandatory, then the server may or may 848 not be required to return an instance of this data node. If any 849 conditional requirements exist for returning the data node in a 850 notification payload or retrieval request, they MUST be documented 851 somewhere. For example, a 'when' or 'if-feature' statement could 852 apply to the data node, or the conditional requirements could be 853 explained in a 'description' statement within the data node or one of 854 its ancestors (if any). 856 If any 'if-feature' statements apply to a list node, then the same 857 'if-feature' statements MUST apply to any key leaf nodes for the 858 list. There MUST NOT be any 'if-feature' statements applied to any 859 key leaf that do not also apply to the parent list node. 861 There SHOULD NOT be any 'when' statements applied to a key leaf node. 862 It is possible that a 'when' statement for an ancestor node of a key 863 leaf will have the exact node-set result as the key leaf. In such a 864 case, the 'when' statement for the key leaf is redundant and SHOULD 865 be avoided. 867 4.6. XPath Usage 869 This section describes guidelines for using the XML Path Language 870 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 872 4.6.1. XPath Evaluation Contexts 874 YANG defines 5 separate contexts for evaluation of XPath statements: 876 1) The "running" datastore: collection of all YANG configuration data 877 nodes. The document root is the conceptual container, (e.g., 878 "config" in the "edit-config" operation), which is the parent of all 879 top-level data definition statements with a "config" statement value 880 of "true". 882 2) State data + the "running" datastore: collection of all YANG data 883 nodes. The document root is the conceptual container, parent of all 884 top-level data definition statements. 886 3) Notification: an event notification document. The document root 887 is the notification element. 889 4) RPC Input: The document root is the conceptual "input" node, which 890 is the parent of all RPC input parameter definitions. 892 5) RPC Output: The document root is the conceptual "output" node, 893 which is the parent of all RPC output parameter definitions. 895 Note that these XPath contexts cannot be mixed. For example, a 896 "when" statement in a notification context cannot reference 897 configuration data. 899 notification foo { 900 leaf mtu { 901 // NOT OK because when-stmt context is this notification 902 when "/if:interfaces/if:interface[name='eth0']"; 903 type leafref { 904 // OK because path-stmt has a different context 905 path "/if:interfaces/if:interface/if:mtu"; 906 } 907 } 908 } 910 It is especially important to consider the XPath evaluation context 911 for XPath expressions defined in groupings. An XPath expression 912 defined in a grouping may not be portable, meaning it cannot be used 913 in multiple contexts and produce proper results. 915 If the XPath expressions defined in a grouping are intended for a 916 particular context, then this context SHOULD be identified in the 917 "description" statement for the grouping. 919 4.6.2. Function Library 921 The 'position' and 'last' functions SHOULD NOT be used. This applies 922 to implicit use of the 'position' function as well (e.g., 923 '//chapter[42]'). A server is only required to maintain the relative 924 XML document order of all instances of a particular user-ordered list 925 or leaf-list. The 'position' and 'last' functions MAY be used if 926 they are evaluated in a context where the context node is a user- 927 ordered 'list' or 'leaf-list'. 929 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 930 present in YANG documents so this function has no meaning. The YANG 931 compiler SHOULD return an empty string for this function. 933 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 934 Expanded names in XPath are different than YANG. A specific 935 canonical representation of a YANG expanded name does not exist. 937 The 'lang' function SHOULD NOT be used. This function does not apply 938 to YANG because there is no 'lang' attribute set with the document. 939 The YANG compiler SHOULD return 'false' for this function. 941 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 942 functions SHOULD NOT be used if the argument is a node-set. If so, 943 the function result will be determined by the document order of the 944 node-set. Since this order can be different on each server, the 945 function results can also be different. Any function call that 946 implicitly converts a node-set to a string will also have this issue. 948 The 'local-name' function SHOULD NOT be used to reference local names 949 outside of the YANG module defining the must or when expression 950 containing the 'local-name' function. Example of a local-name 951 function that should not be used: 953 /*[local-name()='foo'] 955 4.6.3. Axes 957 The 'attribute' and 'namespace' axes are not supported in YANG, and 958 MAY be empty in a NETCONF or RESTCONF server implementation. 960 The 'preceding', and 'following' axes SHOULD NOT be used. These 961 constructs rely on XML document order within a NETCONF or RESTCONF 962 server configuration database, which may not be supported 963 consistently or produce reliable results across implementations. 964 Predicate expressions based on static node properties (e.g., element 965 name or value, 'ancestor' or 'descendant' axes) SHOULD be used 966 instead. The 'preceding' and 'following' axes MAY be used if 967 document order is not relevant to the outcome of the expression 968 (e.g., check for global uniqueness of a parameter value). 970 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 971 however they MAY be used if document order is not relevant to the 972 outcome of the expression. 974 A server is only required to maintain the relative XML document order 975 of all instances of a particular user-ordered list or leaf-list. The 976 'preceding-sibling' and 'following-sibling' axes MAY be used if they 977 are evaluated in a context where the context node is a user-ordered 978 'list' or 'leaf-list'. 980 4.6.4. Types 982 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 983 be used within numeric or boolean expressions. There are boundary 984 conditions in which the translation from the YANG 64-bit type to an 985 XPath number can cause incorrect results. Specifically, an XPath 986 'double' precision floating point number cannot represent very large 987 positive or negative 64-bit numbers because it only provides a total 988 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 989 used in numeric expressions if the value can be represented with no 990 more than 53 bits of precision. 992 Data modelers need to be careful not to confuse the YANG value space 993 and the XPath value space. The data types are not the same in both, 994 and conversion between YANG and XPath data types SHOULD be considered 995 carefully. 997 Explicit XPath data type conversions MAY be used (e.g., 'string', 998 'boolean', or 'number' functions), instead of implicit XPath data 999 type conversions. 1001 XPath expressions that contain a literal value representing a YANG 1002 identity SHOULD always include the declared prefix of the module 1003 where the identity is defined. 1005 XPath expressions for 'when' statements SHOULD NOT reference the 1006 context node or any descendant nodes of the context node. They MAY 1007 reference descendant nodes if the 'when' statement is contained 1008 within an 'augment' statement, and the referenced nodes are not 1009 defined within the 'augment' statement. 1011 Example: 1013 augment "/rt:active-route/rt:input/rt:destination-address" { 1014 when "rt:address-family='v4ur:ipv4-unicast'" { 1015 description 1016 "This augment is valid only for IPv4 unicast."; 1017 } 1018 // nodes defined here within the augment-stmt 1019 // cannot be referenced in the when-stmt 1020 } 1022 4.6.5. Wildcards 1024 It is possible to construct XPath expressions that will evaluate 1025 differently when combined with several modules within a server 1026 implementation, then when evaluated within the single module. This 1027 is due to augmenting nodes from other modules. 1029 Wildcard expansion is done within a server against all the nodes from 1030 all namespaces, so it is possible for a 'must' or 'when' expression 1031 that uses the '*' operator will always evaluate to false if processed 1032 within a single YANG module. In such cases, the 'description' 1033 statement SHOULD clarify that augmenting objects are expected to 1034 match the wildcard expansion. 1036 when /foo/services/*/active { 1037 description 1038 "No services directly defined in this module. 1039 Matches objects that have augmented the services container."; 1040 } 1042 4.6.6. Boolean Expressions 1044 The YANG "must" and "when" statements use an XPath boolean expression 1045 to define the test condition for the statement. It is important to 1046 specify these expressions in a way that will not cause inadvertent 1047 changes in the result if the objects referenced in the expression are 1048 updated in future revisions of the module. 1050 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 1051 to "one" or "three": 1053 leaf foo1 { 1054 type enumeration { 1055 enum one; 1056 enum two; 1057 enum three; 1058 } 1059 } 1061 leaf foo2 { 1062 // INCORRECT 1063 must "/f:foo1 != 'two'"; 1064 type string; 1065 } 1067 leaf foo2 { 1068 // CORRECT 1069 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 1070 type string; 1071 } 1073 In the next revision of the module, leaf "foo1" is extended with a 1074 new enum named "four": 1076 leaf foo1 { 1077 type enumeration { 1078 enum one; 1079 enum two; 1080 enum three; 1081 enum four; 1082 } 1083 } 1085 Now the first XPath expression will allow the enum "four" to be 1086 accepted in addition to the "one" and "three" enum values. 1088 4.7. Lifecycle Management 1090 The status statement MUST be present if its value is 'deprecated' or 1091 'obsolete'. The status SHOULD NOT be changed from 'current' directly 1092 to 'obsolete'. An object SHOULD be available for at least one year 1093 with 'deprecated' status before it is changed to 'obsolete'. 1095 The module or submodule name MUST NOT be changed, once the document 1096 containing the module or submodule is published. 1098 The module namespace URI value MUST NOT be changed, once the document 1099 containing the module is published. 1101 The revision-date substatement within the import statement SHOULD be 1102 present if any groupings are used from the external module. 1104 The revision-date substatement within the include statement SHOULD be 1105 present if any groupings are used from the external submodule. 1107 If an import statement is for a module from a stable source (e.g., an 1108 RFC for an IETF module), then a reference-stmt SHOULD be present 1109 within an import statement. 1111 import ietf-yang-types { 1112 prefix yang; 1113 reference "RFC 6991"; 1114 } 1116 If submodules are used, then the document containing the main module 1117 MUST be updated so that the main module revision date is equal or 1118 more recent than the revision date of any submodule that is (directly 1119 or indirectly) included by the main module. 1121 Definitions for future use SHOULD NOT be specified in a module. Do 1122 not specify placeholder objects like the "reserved" example below: 1124 leaf reserved { 1125 type string; 1126 description 1127 "This object has no purpose at this time, but a future 1128 revision of this module might define a purpose 1129 for this object."; 1130 } 1131 } 1133 4.8. Module Header, Meta, and Revision Statements 1135 For published modules, the namespace MUST be a globally unique URI, 1136 as defined in [RFC3986]. This value is usually assigned by the IANA. 1138 The organization statement MUST be present. If the module is 1139 contained in a document intended for IETF Standards Track status, 1140 then the organization SHOULD be the IETF working group chartered to 1141 write the document. For other standards organizations, a similar 1142 approach is also suggested. 1144 The contact statement MUST be present. If the module is contained in 1145 a document intended for Standards Track status, then the working 1146 group web and mailing information MUST be present, and the main 1147 document author or editor contact information SHOULD be present. If 1148 additional authors or editors exist, their contact information MAY be 1149 present. 1151 The description statement MUST be present. For modules published 1152 within IETF documents, the appropriate IETF Trust Copyright text MUST 1153 be present, as described in Section 3.1. 1155 If the module relies on information contained in other documents, 1156 which are not the same documents implied by the import statements 1157 present in the module, then these documents MUST be identified in the 1158 reference statement. 1160 A revision statement MUST be present for each published version of 1161 the module. The revision statement MUST have a reference 1162 substatement. It MUST identify the published document that contains 1163 the module. Modules are often extracted from their original 1164 documents, and it is useful for developers and operators to know how 1165 to find the original source document in a consistent manner. The 1166 revision statement MAY have a description substatement. 1168 It is not required to keep the full revision history of draft 1169 versions (e.g., modules contained within Internet-Drafts). That is, 1170 within a sequence of draft versions, only the most recent revision 1171 need be recorded in the module. However, whenever a new (i.e. 1172 changed) version is made available (e.g., via a new version of an 1173 Internet-Draft), the revision date of that new version MUST be 1174 updated to a date later than that of the previous version. 1176 4.9. Namespace Assignments 1178 It is RECOMMENDED that only valid YANG modules be included in 1179 documents, whether or not they are published yet. This allows: 1181 o the module to compile correctly instead of generating disruptive 1182 fatal errors. 1184 o early implementors to use the modules without picking a random 1185 value for the XML namespace. 1187 o early interoperability testing since independent implementations 1188 will use the same XML namespace value. 1190 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 1191 provided for the namespace statement in a YANG module. A value 1192 SHOULD be selected that is not likely to collide with other YANG 1193 namespaces. Standard module names, prefixes, and URI strings already 1194 listed in the YANG Module Registry MUST NOT be used. 1196 A standard namespace statement value SHOULD have the following form: 1198 : 1200 The following URN prefix string SHOULD be used for published and 1201 unpublished YANG modules: 1203 urn:ietf:params:xml:ns:yang: 1205 The following example URNs would be valid namespace statement values 1206 for Standards Track modules: 1208 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 1210 urn:ietf:params:xml:ns:yang:ietf-netconf-state 1212 urn:ietf:params:xml:ns:yang:ietf-netconf 1214 Note that a different URN prefix string SHOULD be used for non- 1215 Standards-Track modules. The string SHOULD be selected according to 1216 the guidelines in [RFC7950]. 1218 The following URIs exemplify what might be used by non Standards 1219 Track modules. Note that the domain "example.com" SHOULD be used by 1220 example modules in IETF drafts. 1222 Example URIs using URLs per RFC 3986 [RFC3986]: 1224 http://example.com/ns/example-interfaces 1226 http://example.com/ns/example-system 1228 Example URIs using tags per RFC 4151 [RFC4151]: 1230 tag:example.com,2017:example-interfaces 1232 tag:example.com,2017:example-system 1234 4.10. Top-Level Data Definitions 1236 The top-level data organization SHOULD be considered carefully, in 1237 advance. Data model designers need to consider how the functionality 1238 for a given protocol or protocol family will grow over time. 1240 The separation of configuration data and operational state SHOULD be 1241 considered carefully. It is sometimes useful to define separate top- 1242 level containers for configuration and non-configuration data. For 1243 some existing top-level data nodes, configuration data was not in 1244 scope, so only one container representing operational state was 1245 created. 1247 The number of top-level data nodes within a module SHOULD be 1248 minimized. It is often useful to retrieve related information within 1249 a single subtree. If data is too distributed, is becomes difficult 1250 to retrieve all at once. 1252 The names and data organization SHOULD reflect persistent 1253 information, such as the name of a protocol. The name of the working 1254 group SHOULD NOT be used because this may change over time. 1256 A mandatory database data definition is defined as a node that a 1257 client must provide for the database to be valid. The server is not 1258 required to provide a value. 1260 Top-level database data definitions MUST NOT be mandatory. If a 1261 mandatory node appears at the top level, it will immediately cause 1262 the database to be invalid. This can occur when the server boots or 1263 when a module is loaded dynamically at runtime. 1265 4.11. Data Types 1267 Selection of an appropriate data type (i.e., built-in type, existing 1268 derived type, or new derived type) is very subjective, and therefore 1269 few requirements can be specified on that subject. 1271 Data model designers SHOULD use the most appropriate built-in data 1272 type for the particular application. 1274 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1275 'int64') SHOULD NOT be used unless negative values are allowed for 1276 the desired semantics. 1278 4.11.1. Fixed Value Extensibility 1280 If the set of values is fixed and the data type contents are 1281 controlled by a single naming authority, then an enumeration data 1282 type SHOULD be used. 1284 leaf foo { 1285 type enumeration { 1286 enum one; 1287 enum two; 1288 } 1289 } 1291 If extensibility of enumerated values is required, then the 1292 'identityref' data type SHOULD be used instead of an enumeration or 1293 other built-in type. 1295 identity foo-type { 1296 description "Base for the extensible type"; 1297 } 1299 identity one { 1300 base f:foo-type; 1301 } 1302 identity two { 1303 base f:foo-type; 1304 } 1306 leaf foo { 1307 type identityref { 1308 base f:foo-type; 1309 } 1310 } 1312 Note that any module can declare an identity with base "foo-type" 1313 that is valid for the "foo" leaf. Identityref values are considered 1314 to be qualified names. 1316 4.11.2. Patterns and Ranges 1318 For string data types, if a machine-readable pattern can be defined 1319 for the desired semantics, then one or more pattern statements SHOULD 1320 be present. A single quoted string SHOULD be used to specify the 1321 pattern, since a double-quoted string can modify the content. 1323 The following typedef from [RFC6991] demonstrates the proper use of 1324 the "pattern" statement: 1326 typedef ipv4-address-no-zone { 1327 type inet:ipv4-address { 1328 pattern '[0-9\.]*'; 1329 } 1330 ... 1331 } 1333 For string data types, if the length of the string is required to be 1334 bounded in all implementations, then a length statement MUST be 1335 present. 1337 The following typedef from [RFC6991] demonstrates the proper use of 1338 the "length" statement: 1340 typedef yang-identifier { 1341 type string { 1342 length "1..max"; 1343 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1344 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1345 } 1346 ... 1347 } 1349 For numeric data types, if the values allowed by the intended 1350 semantics are different than those allowed by the unbounded intrinsic 1351 data type (e.g., 'int32'), then a range statement SHOULD be present. 1353 The following typedef from [RFC6991] demonstrates the proper use of 1354 the "range" statement: 1356 typedef dscp { 1357 type uint8 { 1358 range "0..63"; 1359 } 1360 ... 1361 } 1363 4.11.3. Enumerations and Bits 1365 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1366 or 'bit' SHOULD be documented. A separate description statement 1367 (within each 'enum' or 'bit' statement) SHOULD be present. 1369 leaf foo { 1370 // INCORRECT 1371 type enumeration { 1372 enum one; 1373 enum two; 1374 } 1375 description 1376 "The foo enum... 1377 one: The first enum 1378 two: The second enum"; 1379 } 1381 leaf foo { 1382 // CORRECT 1383 type enumeration { 1384 enum one { 1385 description "The first enum"; 1386 } 1387 enum two { 1388 description "The second enum"; 1389 } 1390 } 1391 description 1392 "The foo enum... "; 1393 } 1395 4.11.4. Union Types 1397 The YANG "union" type is evaluated by testing a value against each 1398 member type in the union. The first type definition that accepts a 1399 value as valid is the member type used. In general, member types 1400 SHOULD be ordered from most restrictive to least restrictive types. 1402 In the following example, the "enumeration" type will never be 1403 matched because the preceding "string" type will match everything. 1405 Incorrect: 1407 type union { 1408 type string; 1409 type enumeration { 1410 enum up; 1411 enum down; 1412 } 1413 } 1415 Correct: 1417 type union { 1418 type enumeration { 1419 enum up; 1420 enum down; 1421 } 1422 type string; 1423 } 1425 It is possible for different member types to match, depending on the 1426 input encoding format. In XML, all values are passed as string 1427 nodes, but in JSON there are different value types for numbers, 1428 booleans, and strings. 1430 In the following example, a JSON numeric value will always be matched 1431 by the "int32" type but in XML the string value representing a number 1432 will be matched by the "string" type. The second version will match 1433 the "int32" member type no matter how the input is encoded. 1435 Incorrect: 1437 type union { 1438 type string; 1439 type int32; 1440 } 1442 Correct: 1444 type union { 1445 type int32; 1446 type string; 1447 } 1449 4.11.5. Empty and Boolean 1451 YANG provides an "empty" data type, which has one value (i.e., 1452 present). The default is "not present", which is not actually a 1453 value. When used within a list key, only one value can (and must) 1454 exist for this key leaf. The type "empty" SHOULD NOT be used for a 1455 key leaf since it is pointless. 1457 There is really no difference between a leaf of type "empty" and a 1458 leaf-list of type "empty". Both are limited to one instance. The 1459 type "empty" SHOULD NOT be used for a leaf-list. 1461 The advantage of using type "empty" instead of type "boolean" is that 1462 the default (not present) does not take up any bytes in a 1463 representation. The disadvantage is that the client may not be sure 1464 if an empty leaf is missing because it was filtered somehow or not 1465 implemented. The client may not have a complete and accurate schema 1466 for the data returned by the server, and not be aware of the missing 1467 leaf. 1469 The YANG "boolean" data type provides two values ("true" and 1470 "false"). When used within a list key, two entries can exist for 1471 this key leaf. Default values are ignored for key leafs, but a 1472 default statement is often used for plain boolean leafs. The 1473 advantage of the "boolean" type is that the leaf or leaf-list has a 1474 clear representation for both values. The default value is usually 1475 not returned unless explicitly requested by the client, so no bytes 1476 are used in a typical representation. 1478 In general, the "boolean" data type SHOULD be used instead of the 1479 "empty" data type, as shown in the example below: 1481 Incorrect: 1483 leaf flag1 { 1484 type empty; 1485 } 1487 Correct: 1489 leaf flag2 { 1490 type boolean; 1491 default false; 1492 } 1494 4.12. Reusable Type Definitions 1496 If an appropriate derived type exists in any standard module, such as 1497 [RFC6991], then it SHOULD be used instead of defining a new derived 1498 type. 1500 If an appropriate units identifier can be associated with the desired 1501 semantics, then a units statement SHOULD be present. 1503 If an appropriate default value can be associated with the desired 1504 semantics, then a default statement SHOULD be present. 1506 If a significant number of derived types are defined, and it is 1507 anticipated that these data types will be reused by multiple modules, 1508 then these derived types SHOULD be contained in a separate module or 1509 submodule, to allow easier reuse without unnecessary coupling. 1511 The description statement MUST be present. 1513 If the type definition semantics are defined in an external document 1514 (other than another YANG module indicated by an import statement), 1515 then the reference statement MUST be present. 1517 4.13. Reusable Groupings 1519 A reusable grouping is a YANG grouping that can be imported by 1520 another module, and is intended for use by other modules. This is 1521 not the same as a grouping that is used within the module it is 1522 defined, but happens to be exportable to another module because it is 1523 defined at the top-level of the YANG module. 1525 The following guidelines apply to reusable groupings, in order to 1526 make them as robust as possible: 1528 o Clearly identify the purpose of the grouping in the "description" 1529 statement. 1531 o There are 5 different XPath contexts in YANG (rpc/input, rpc/ 1532 output, notification, config=true data nodes, and all data nodes). 1533 Clearly identify which XPath contexts are applicable or excluded 1534 for the grouping. 1536 o Do not reference data outside the grouping in any "path", "must", 1537 or "when" statements. 1539 o Do not include a "default" sub-statement on a leaf or choice 1540 unless the value applies on all possible contexts. 1542 o Do not include a "config" sub-statement on a data node unless the 1543 value applies on all possible contexts. 1545 o Clearly identify any external dependencies in the grouping 1546 "description" statement, such as nodes referenced by absolute path 1547 from a "path", "must", or "when" statement. 1549 4.14. Data Definitions 1551 The description statement MUST be present in the following YANG 1552 statements: 1554 o anyxml 1556 o augment 1558 o choice 1559 o container 1561 o extension 1563 o feature 1565 o grouping 1567 o identity 1569 o leaf 1571 o leaf-list 1573 o list 1575 o notification 1577 o rpc 1579 o typedef 1581 If the data definition semantics are defined in an external document, 1582 (other than another YANG module indicated by an import statement), 1583 then a reference statement MUST be present. 1585 The 'anyxml' construct may be useful to represent an HTML banner 1586 containing markup elements, such as '<b>' and '</b>', and 1587 MAY be used in such cases. However, this construct SHOULD NOT be 1588 used if other YANG data node types can be used instead to represent 1589 the desired syntax and semantics. 1591 It has been found that the 'anyxml' statement is not implemented 1592 consistently across all servers. It is possible that mixed mode XML 1593 will not be supported, or configuration anyxml nodes will not 1594 supported. 1596 If there are referential integrity constraints associated with the 1597 desired semantics that can be represented with XPath, then one or 1598 more 'must' statements SHOULD be present. 1600 For list and leaf-list data definitions, if the number of possible 1601 instances is required to be bounded for all implementations, then the 1602 max-elements statements SHOULD be present. 1604 If any 'must' or 'when' statements are used within the data 1605 definition, then the data definition description statement SHOULD 1606 describe the purpose of each one. 1608 The "choice" statement is allowed to be directly present within a 1609 "case" statement in YANG 1.1. This needs to be considered carefully. 1610 Consider simply including the nested "choice" as additional "case" 1611 statements within the parent "choice" statement. Note that the 1612 "mandatory" and "default" statements within a nested "choice" 1613 statement only apply if the "case" containing the nested "choice" 1614 statement is first selected. 1616 4.14.1. Non-Presence Containers 1618 A non-presence container is used to organize data into specific 1619 subtrees. It is not intended to have semantics within the data model 1620 beyond this purpose, although YANG allows it (e.g., "must" statement 1621 within the non-presence container). 1623 Example using container wrappers: 1625 container top { 1626 container foos { 1627 list foo { ... } 1628 } 1629 container bars { 1630 list bar { ... } 1631 } 1632 } 1634 Example without container wrappers: 1636 container top { 1637 list foo { ... } 1638 list bar { ... } 1639 } 1641 Use of non-presence containers to organize data is a subjective 1642 matter similar to use of sub-directories in a file system. The 1643 NETCONF and RESTCONF protocols do not currently support the ability 1644 to delete all list (or leaf-list) entries at once. This deficiency 1645 is sometimes avoided by use of a parent container (i.e., deleting the 1646 container also removes all child entries). 1648 4.14.2. Top-Level Data Nodes 1650 Use of top-level objects needs to be considered carefully 1652 -top-level siblings are not ordered -top-level siblings not are not 1653 static, and depends on the modules that are loaded 1654 o for sub-tree filtering, retrieval of a top-level leaf-list will be 1655 treated as a content-match node for all top-level-siblings 1657 o a top-level list with many instances may impact performance 1659 4.15. Operation Definitions 1661 If the operation semantics are defined in an external document (other 1662 than another YANG module indicated by an import statement), then a 1663 reference statement MUST be present. 1665 If the operation impacts system behavior in some way, it SHOULD be 1666 mentioned in the description statement. 1668 If the operation is potentially harmful to system behavior in some 1669 way, it MUST be mentioned in the Security Considerations section of 1670 the document. 1672 4.16. Notification Definitions 1674 The description statement MUST be present. 1676 If the notification semantics are defined in an external document 1677 (other than another YANG module indicated by an import statement), 1678 then a reference statement MUST be present. 1680 If the notification refers to a specific resource instance, then this 1681 instance SHOULD be identified in the notification data. This is 1682 usually done by including 'leafref' leaf nodes with the key leaf 1683 values for the resource instance. For example: 1685 notification interface-up { 1686 description "Sent when an interface is activated."; 1687 leaf name { 1688 type leafref { 1689 path "/if:interfaces/if:interface/if:name"; 1690 } 1691 } 1692 } 1694 Note that there are no formal YANG statements to identify any data 1695 node resources associated with a notification. The description 1696 statement for the notification SHOULD specify if and how the 1697 notification identifies any data node resources associated with the 1698 specific event. 1700 4.17. Feature Definitions 1702 The YANG "feature" statement is used to define a label for a set of 1703 optional functionality within a module. The "if-feature" statement 1704 is used in the YANG statements associated with a feature. 1706 The set of YANG features available in a module should be considered 1707 carefully. The description-stmt within a feature-stmt MUST specify 1708 any interactions with other features. 1710 If there is a large set of objects associated with a YANG feature, 1711 then consider moving those objects to a separate module, instead of 1712 using a YANG feature. Note that the set of features within a module 1713 is easily discovered by the reader, but the set of related modules 1714 within the entire YANG library is not as easy to identity. Module 1715 names with a common prefix can help readers identity the set of 1716 related modules, but this assumes the reader will have discovered and 1717 installed all the relevant modules. 1719 Another consideration for deciding whether to create a new module or 1720 add a YANG feature is the stability of the module in question. It 1721 may be desirable to have a stable base module that is not changed 1722 frequently. If new functionality is placed in a separate module, 1723 then the base module does not need to be republished. If it is 1724 designed as a YANG feature then the module will need to be 1725 republished. 1727 If one feature requires implementation of another feature, then an 1728 "if-feature" statement SHOULD be used in the dependent "feature" 1729 statement. 1731 For example, feature2 requires implementation of feature1: 1733 feature feature1 { 1734 description "Some protocol feature"; 1735 } 1737 feature feature2 { 1738 if-feature "feature1"; 1739 description "Another protocol feature"; 1740 } 1742 4.18. YANG Data Node Constraints 1744 4.18.1. Controlling Quantity 1746 The "min-elements" and "max-elements" statements can be use to 1747 control how many list or leaf-list instances are required for a 1748 particular data node. YANG constraint statements SHOULD be used to 1749 identify conditions that apply to all implementations of the data 1750 model. If platform-specific limitations (e.g., the "max-elements" 1751 supported for a particular list) are relevant to operations, then a 1752 data model definition statement (e.g., "max-ports" leaf) SHOULD be 1753 used to identify the limit. 1755 4.18.2. must vs. when 1757 The "must" and "when" YANG statements are used to provide cross- 1758 object referential tests. They have very different behavior. The 1759 "when" statement causes data node instances to be silently deleted as 1760 soon as the condition becomes false. A false "when" expression is 1761 not considered to be an error. 1763 The "when" statement SHOULD be used together with the "augment" or 1764 "uses" statements to achieve conditional model composition. The 1765 condition SHOULD be based on static properties of the augmented entry 1766 (e.g., list key leafs). 1768 The "must" statement causes a datastore validation error if the 1769 condition is false. This statement SHOULD be used for enforcing 1770 parameter value restrictions that involve more than one data node 1771 (e.g., end-time parameter must be after the start-time parameter). 1773 4.19. Augment Statements 1775 The YANG "augment" statement is used to define a set of data 1776 definition statements that will be added as child nodes of a target 1777 data node. The module namespace for these data nodes will be the 1778 augmenting module, not the augmented module. 1780 A top-level "augment" statement SHOULD NOT be used if the target data 1781 node is in the same module or submodule as the evaluated "augment" 1782 statement. The data definition statements SHOULD be added inline 1783 instead. 1785 4.19.1. Conditional Augment Statements 1787 The "augment" statement is often used together with the "when" 1788 statement and/or "if-feature" statement to make the augmentation 1789 conditional on some portion of the data model. 1791 The following example from [RFC7223] shows how a conditional 1792 container called "ethernet" is added to the "interface" list only for 1793 entries of the type "ethernetCsmacd". 1795 augment "/if:interfaces/if:interface" { 1796 when "if:type = 'ianaift:ethernetCsmacd'"; 1798 container ethernet { 1799 leaf duplex { 1800 ... 1801 } 1802 } 1803 } 1805 4.19.2. Conditionally Mandatory Data Definition Statements 1807 YANG has very specific rules about how configuration data can be 1808 updated in new releases of a module. These rules allow an "old 1809 client" to continue interoperating with a "new server". 1811 If data nodes are added to an existing entry, the old client MUST NOT 1812 be required to provide any mandatory parameters that were not in the 1813 original module definition. 1815 It is possible to add conditional augment statements such that the 1816 old client would not know about the new condition, and would not 1817 specify the new condition. The conditional augment statement can 1818 contain mandatory objects only if the condition is false unless 1819 explicitly requested by the client. 1821 Only a conditional augment statement that uses the "when" statement 1822 form of condition can be used in this manner. The YANG features 1823 enabled on the server cannot be controlled by the client in any way, 1824 so it is not safe to add mandatory augmenting data nodes based on the 1825 "if-feature" statement. 1827 The XPath "when" statement condition MUST NOT reference data outside 1828 of target data node because the client does not have any control over 1829 this external data. 1831 In the following dummy example, it is OK to augment the "interface" 1832 entry with "mandatory-leaf" because the augmentation depends on 1833 support for "some-new-iftype". The old client does not know about 1834 this type so it would never select this type, and therefore not be 1835 adding a mandatory data node. 1837 module example-module { 1838 namespace "http://example.com/ns/example-module"; 1839 prefix mymod; 1841 import iana-if-type { prefix iana; } 1842 import ietf-interfaces { prefix if; } 1844 identity some-new-iftype { 1845 base iana:iana-interface-type; 1846 } 1848 augment "/if:interfaces/if:interface" { 1849 when "if:type = 'mymod:some-new-iftype'"; 1851 leaf mandatory-leaf { 1852 mandatory true; 1853 ... 1854 } 1855 } 1856 } 1858 Note that this practice is safe only for creating data resources. It 1859 is not safe for replacing or modifying resources if the client does 1860 not know about the new condition. The YANG data model MUST be 1861 packaged in a way that requires the client to be aware of the 1862 mandatory data nodes if it is aware of the condition for this data. 1863 In the example above, the "some-new-iftype" identity is defined in 1864 the same module as the "mandatory-leaf" data definition statement. 1866 This practice is not safe for identities defined in a common module 1867 such as "iana-if-type" because the client is not required to know 1868 about "my-module" just because it knows about the "iana-if-type" 1869 module. 1871 4.20. Deviation Statements 1873 The YANG "deviation" statement cannot appear in IETF YANG modules, 1874 but it can be useful for documenting server capabilities. Deviation 1875 statements are not reusable and typically not shared across all 1876 platforms. 1878 There are several reasons that deviations might be needed in an 1879 implementation, e.g., an object cannot be supported on all platforms, 1880 or feature delivery is done in multiple development phases. 1881 Deviation statements can also be used to add annotations to a module, 1882 which does not affect the conformance requirements for the module. 1884 It is suggested that deviation statements be defined in separate 1885 modules from regular YANG definitions. This allows the deviations to 1886 be platform-specific and/or temporary. 1888 The order that deviation statements are evaluated can affect the 1889 result. Therefore multiple deviation statements in the same module, 1890 for the same target object, SHOULD NOT be used. 1892 The "max-elements" statement is intended to describe an architectural 1893 limit to the number of list entries. It is not intended to describe 1894 platform limitations. It is better to use a "deviation" statement 1895 for the platforms that have a hard resource limit. 1897 Example documenting platform resource limits: 1899 Wrong: (max-elements in the list itself) 1901 container backups { 1902 list backup { 1903 ... 1904 max-elements 10; 1905 ... 1906 } 1907 } 1909 Correct: (max-elements in a deviation) 1911 deviation /bk:backups/bk:backup { 1912 deviate add { 1913 max-elements 10; 1914 } 1915 } 1917 4.21. Extension Statements 1919 The YANG "extension" statement is used to specify external 1920 definitions. This appears in the YANG syntax as an 1921 "unknown-statement". Usage of extension statements in a published 1922 module needs to be considered carefully. 1924 The following guidelines apply to the usage of YANG extensions: 1926 o The semantics of the extension MUST NOT contradict any YANG 1927 statements. Extensions can add semantics not covered by the 1928 normal YANG statements. 1930 o The module containing the extension statement MUST clearly 1931 identify the conformance requirements for the extension. It 1932 should be clear whether all implementations of the YANG module 1933 containing the extension need to also implement the extension. If 1934 not, identify what conditions apply that would require 1935 implementation of the extension. 1937 o The extension MUST clearly identify where it can be used within 1938 other YANG statements. 1940 o The extension MUST clearly identify if YANG statements or other 1941 extensions are allowed or required within the extension as sub- 1942 statements. 1944 4.22. Data Correlation 1946 Data can be correlated in various ways, using common data types, 1947 common data naming, and common data organization. There are several 1948 ways to extend the functionality of a module, based on the degree of 1949 coupling between the old and new functionality: 1951 o inline: update the module with new protocol-accessible objects. 1952 The naming and data organization of the original objects is used. 1953 The new objects are in the original module namespace. 1955 o augment: create a new module with new protocol-accessible objects 1956 that augment the original data structure. The naming and data 1957 organization of the original objects is used. The new objects are 1958 in the new module namespace. 1960 o mirror: create new objects in a new module or the original module, 1961 except use new a naming scheme and data location. The naming can 1962 be coupled in different ways. Tight coupling is achieved with a 1963 "leafref" data type, with the "require-instance" sub-statement set 1964 to "true". This method SHOULD be used. 1966 If the new data instances are not limited to the values in use in the 1967 original data structure, then the "require-instance" sub-statement 1968 MUST be set to "false". Loose coupling is achieved by using key 1969 leafs with the same data type as the original data structure. This 1970 has the same semantics as setting the "require-instance" sub- 1971 statement to "false". 1973 It is sometimes useful to separate configuration data and operational 1974 state, so that they do not not even share the exact same naming 1975 characteristics. The correlation between configuration the 1976 operational state that is affected by changes in configuration is a 1977 complex problem. There may not be a simple 1:1 relationship between 1978 a configuration data node and an operational state node. Further 1979 work is needed in YANG to clarify this relationship. Protocol work 1980 may also be needed to allow a client to retrieve this type of 1981 information from a server. At this time the best practice is to 1982 clearly document any relationship to other data structures in the 1983 "description" statement. 1985 4.22.1. Use of Leafref for Key Correlation 1987 Sometimes it is not practical to augment a data structure. For 1988 example, the correlated data could have different keys or contain 1989 mandatory nodes. 1991 The following example shows the use of the "leafref" data type for 1992 data correlation purposes: 1994 Not preferred: 1996 list foo { 1997 key name; 1998 leaf name { 1999 type string; 2000 } 2001 ... 2002 } 2004 list foo-addon { 2005 key name; 2006 config false; 2007 leaf name { 2008 type string; 2009 } 2010 ... 2011 } 2013 Preferred: 2015 list foo { 2016 key name; 2017 leaf name { 2018 type string; 2019 } 2020 ... 2021 } 2023 list foo-addon { 2024 key name; 2025 config false; 2026 leaf name { 2027 type leafref { 2028 path "/foo/name"; 2029 require-instance false; 2030 } 2031 } 2032 leaf addon { 2033 type string; 2034 mandatory true; 2035 } 2036 } 2038 4.23. Operational State 2040 The modeling operational state with YANG has been refined over time. 2041 At first, only data that has a "config" statement value of "false" 2042 was considered to be operational state. This data was not considered 2043 to be part of any datastore, which made YANG XPath definition much 2044 more complicated. 2046 Operational state is now modeled using YANG according to new NMDA, 2047 and is now conceptually contained in the operational state datastore, 2048 which also includes the operational values of configuration data. 2049 There is no longer any need to duplicate data structures to provide 2050 separate configuration and operational state sections. 2052 This section describes some data modeling issues related to 2053 operational state, and guidelines for transitioning YANG data model 2054 design to be NMDA-compatible. 2056 4.23.1. Combining Operational State and Configuration Data 2058 If possible, operational state SHOULD be combined with its associated 2059 configuration data. This prevents duplication of key leafs and 2060 ancestor nodes. It also prevents race conditions for retrieval of 2061 dynamic entries, and allows configuration and operational state to be 2062 retrieved together with minimal message overhead. 2064 container foo { 2065 ... 2066 // contains config=true and config=false nodes that have 2067 // no corresponding config=true object (e.g., counters) 2068 } 2070 4.23.2. Representing Operational Values of Configuration Data 2072 If possible the same data type SHOULD be used to represent the 2073 configured value and the operational value, for a given leaf or leaf- 2074 list object. 2076 Sometimes the configured value set is different than the operational 2077 value set for that object. For example, the "admin-state" and 2078 "oper-state" leafs in [RFC7223]. In this case a separate object MAY 2079 be used to represent the configured and operational values. 2081 Sometimes the list keys are not identical for configuration data and 2082 the corresponding operational state. In this case separate lists MAY 2083 be used to represent the configured and operational values. 2085 If it is not possible to combine configuration and operational state, 2086 then the keys used to represent list entries SHOULD be the same type. 2087 The "leafref" data type SHOULD be used in operational state for key 2088 leafs that have corresponding configuration instances. The 2089 "require-instance" statement MAY be set to "false" (in YANG 1.1 2090 modules only) to indicate instances are allowed in the operational 2091 state that do not exist in the associated configuration data. 2093 The need to replicate objects or define different operational state 2094 objects depends on the data model. It is not possible to define one 2095 approach that will be optimal for all data models. 2097 Designers SHOULD describe and justify any NMDA exceptions in detail, 2098 such as the use of separate subtrees and/or separate leafs. The 2099 "description" statements for both the configuration and the 2100 operational state SHOULD be used for this purpose. 2102 4.23.3. NMDA Transition Guidelines 2104 YANG modules SHOULD be designed assuming they will be used on servers 2105 supporting the operational state datastore. With this in mind, YANG 2106 modules SHOULD define config "false" wherever they make sense to the 2107 data model. Config "false" nodes SHOULD NOT be defined to provide 2108 the operational value for configuration nodes, except when the value 2109 space of a configured and operational values may differ, in which 2110 case a distinct config "false" node SHOULD be defined to hold the 2111 operational value for the configured node. 2113 The following guidelines are meant to help modelers develop YANG 2114 modules that will maximize the utility of the model with both current 2115 and new implementations. 2117 New modules and modules that are not concerned with the operational 2118 state of configuration information SHOULD immediately be structured 2119 to be NMDA-compatible, as described in Section 4.23.1. This 2120 transition MAY be deferred if the module does not contain any 2121 configuration datastore objects. 2123 The remaining are options that MAY be followed during the time that 2124 NMDA mechanisms are being defined. 2126 (a) Modules that require immediate support for the NMDA features 2127 SHOULD be structured for NMDA. A temporary non-NMDA version of this 2128 type of module MAY exist, either an existing model or a model created 2129 either by hand or with suitable tools that mirror the current 2130 modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 2131 be published in the same document, with NMDA modules in the document 2132 main body and the non-NMDA modules in a non-normative appendix. The 2133 use of the non-NMDA module will allow temporary bridging of the time 2134 period until NMDA implementations are available. 2136 (b) For published models, the model should be republished with an 2137 NMDA-compatible structure, deprecating non-NMDA constructs. For 2138 example, the "ietf-interfaces" model in [RFC7223] will be 2139 restructured as an NMDA-compatible model. The "/interfaces-state" 2140 hierarchy will be marked "status deprecated". Models that mark their 2141 "/foo-state" hierarchy with "status deprecated" will allow NMDA- 2142 capable implementations to avoid the cost of duplicating the state 2143 nodes, while enabling non-NMDA-capable implementations to utilize 2144 them for access to the operational values. 2146 (c) For models that augment models which have not been structured 2147 with the NMDA, the modeler will have to consider the structure of the 2148 base model and the guidelines listed above. Where possible, such 2149 models should move to new revisions of the base model that are NMDA- 2150 compatible. When that is not possible, augmenting "state" containers 2151 SHOULD be avoided, with the expectation that the base model will be 2152 re-released with the state containers marked as deprecated. It is 2153 RECOMMENDED to augment only the "/foo" hierarchy of the base model. 2154 Where this recommendation cannot be followed, then any new "state" 2155 elements SHOULD be included in their own module. 2157 4.23.3.1. Temporary non-NMDA Modules 2159 A temporary non-NMDA module allows a non-NMDA aware client to access 2160 operational state from an NMDA-compliant server. It contains the 2161 top-level config=false data nodes that would have been defined in a 2162 legacy YANG module (before NMDA). 2164 A server that needs to support both NMDA and non-NMDA clients can 2165 advertise both the new NMDA module and the temporary non-NMDA module. 2166 A non-NMDA client can use separate "foo" and "foo-state" subtrees, 2167 except the "foo-state" subtree is located in a different (temporary) 2168 module. The NMDA module can be used by a non-NMDA client to access 2169 the conventional configuration datastores, and the deprecated 2170 operation to access nested config=false data nodes. 2172 To create the temporary non-NMDA model from an NMDA model, the 2173 following steps can be taken: 2175 o Change the module name by appending "-state" to the original 2176 module name 2178 o Change the namespace by appending "-state" to the original 2179 namespace value 2181 o Change the prefix by appending "-s" to the original prefix value 2183 o Add an import to the original module (e.g., for typedef 2184 definitions) 2186 o Retain or create only the top-level nodes that have a "config" 2187 statement value "false". These subtrees represent config=false 2188 data nodes that were combined into the configuration subtree, and 2189 therefore not available to non-NMDA aware clients. Set the 2190 "status" statement to "deprecated" for each new node. 2192 o The module description SHOULD clearly identify the module as a 2193 temporary non-NMDA module 2195 4.23.3.2. Example: Create a New NMDA Module 2197 Create an NMDA-compliant module, using combined configuration and 2198 state subtrees, whenever possible. 2200 module example-foo { 2201 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2202 prefix "foo"; 2204 container foo { 2205 // configuration data child nodes 2206 // operational value in operational state datastore only 2207 // may contain config=false nodes as needed 2208 } 2210 } 2212 4.23.3.3. Example: Convert an old Non-NMDA Module 2214 Do not remove non-compliant objects from existing modules. Instead, 2215 change the status to "deprecated". At some point, usually after 1 2216 year, the status MAY be changed to "obsolete". 2218 Old Module: 2220 module example-foo { 2221 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2222 prefix "foo"; 2224 container foo { 2225 // configuration data child nodes 2226 } 2228 container foo-state { 2229 config false; 2230 // operational state child nodes 2231 } 2232 } 2234 Converted NMDA Module: 2236 module example-foo { 2237 namespace "urn:example.com:params:xml:ns:yang:example-foo"; 2238 prefix "foo"; 2240 container foo { 2241 // configuration data child nodes 2242 // operational value in operational state datastore only 2243 // may contain config=false nodes as needed 2244 // will contain any data nodes from old foo-state 2245 } 2247 // keep original foo-state but change status to deprecated 2248 container foo-state { 2249 config false; 2250 status deprecated; 2251 // operational state child nodes 2252 } 2253 } 2255 4.23.3.4. Example: Create a Temporary NMDA Module: 2257 Create a new module that contains the top-level operational state 2258 data nodes that would have been available before they were combined 2259 with configuration data nodes (to be NMDA compliant). 2261 module example-foo-state { 2262 namespace "urn:example.com:params:xml:ns:yang:example-foo-state"; 2263 prefix "foo-s"; 2265 // import new or converted module; not used in this example 2266 import example-foo { prefix foo; } 2268 container foo-state { 2269 config false; 2270 status deprecated; 2271 // operational state child nodes 2272 } 2273 } 2275 4.24. Performance Considerations 2277 It is generally likely that certain YANG statements require more 2278 runtime resources than other statements. Although there are no 2279 performance requirements for YANG validation, the following 2280 information MAY be considered when designing YANG data models: 2282 o Lists are generally more expensive than containers 2284 o "when-stmt" evaluation is generally more expensive than 2285 "if-feature" or "choice" statements 2287 o "must" statement is generally more expensive than "min-entries", 2288 "max-entries", "mandatory", or "unique" statements 2290 o "identityref" leafs are generally more expensive than 2291 "enumeration" leafs 2293 o "leafref" and "instance-identifier" types with "require-instance" 2294 set to true are generally more expensive than if 2295 "require-instance" is set to false 2297 4.25. Open Systems Considerations 2299 A YANG module MUST NOT be designed such that the set of modules found 2300 on a server implementation can be predetermined in advance. Only the 2301 modules imported by a particular module can be assumed to be present 2302 in an implementation. An open system MAY include any combination of 2303 YANG modules. 2305 4.26. YANG 1.1 Guidelines 2307 The set of YANG 1.1 guidelines will grow as operational experience is 2308 gained with the new language features. This section contains an 2309 initial set of guidelines. 2311 4.26.1. Importing Multiple Revisions 2313 Standard modules SHOULD NOT import multiple revisions of the same 2314 module into a module. This MAY be done if the authors can 2315 demonstrate that the "avoided" definitions from the most recent of 2316 the multiple revisions are somehow broken or harmful to 2317 interoperability. 2319 4.26.2. Using Feature Logic 2321 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 2322 "description" statement SHOULD describe the "if-feature" logic in 2323 text, to help readers understand the module. 2325 YANG features SHOULD be used instead of the "when" statement, if 2326 possible. Features are advertised by the server and objects 2327 conditional by if-feature are conceptually grouped together. There 2328 is no such commonality supported for "when" statements. 2330 Features generally require less server implementation complexity and 2331 runtime resources than objects that use "when" statements. Features 2332 are generally static (i.e., set when module is loaded and not changed 2333 at runtime). However every client edit might cause a "when" 2334 statement result to change. 2336 4.26.3. anyxml vs. anydata 2338 The "anyxml" statement MUST NOT be used to represent a conceptual 2339 subtree of YANG data nodes. The "anydata" statement MUST be used for 2340 this purpose. 2342 4.26.4. action vs. rpc 2344 The use of "action" statements or "rpc" statements is a subjective 2345 design decision. RPC operations are not associated with any 2346 particular data node. Actions are associated with a specific data 2347 node definition. An "action" statement SHOULD be used if the 2348 protocol operation is specific to a subset of all data nodes instead 2349 of all possible data nodes. 2351 The same action name MAY be used in different definitions within 2352 different data node. For example, a "reset" action defined with a 2353 data node definition for an interface might have different parameters 2354 than for a power supply or a VLAN. The same action name SHOULD be 2355 used to represent similar semantics. 2357 The NETCONF Access Control Model (NACM) [RFC6536] does not support 2358 parameter access control for RPC operations. The user is given 2359 permission (or not) to invoke the RPC operation with any parameters. 2360 For example, if each client is only allowed to reset their own 2361 interface, then NACM cannot be used. 2363 For example, NACM cannot enforce access access control based on the 2364 value of the "interface" parameter, only the "reset" operation 2365 itself: 2367 rpc reset { 2368 input { 2369 leaf interface { 2370 type if:interface-ref; 2371 mandatory true; 2372 description "The interface to reset."; 2373 } 2374 } 2375 } 2377 However, NACM can enforce access access control for individual 2378 interface instances, using a "reset" action, If the user does not 2379 have read access to the specific "interface" instance, then it cannot 2380 invoke the "reset" action for that interface instance: 2382 container interfaces { 2383 list interface { 2384 ... 2385 action reset { } 2386 } 2387 } 2389 4.27. Updating YANG Modules (Published vs. Unpublished) 2391 YANG modules can change over time. Typically, new data model 2392 definitions are needed to support new features. YANG update rules 2393 defined in section 11 of [RFC7950] MUST be followed for published 2394 modules. They MAY be followed for unpublished modules. 2396 The YANG update rules only apply to published module revisions. Each 2397 organization will have their own way to identify published work which 2398 is considered to be stable, and unpublished work which is considered 2399 to be unstable. For example, in the IETF, the RFC document is used 2400 for published work, and the Internet-Draft is used for unpublished 2401 work. 2403 5. IANA Considerations 2405 -- RFC Ed: These registries need to be updated to reference this 2406 RFC instead of RFC 6087 for the ietf-template module, and 2407 remove this note. 2409 This document registers one URI in the IETF XML registry [RFC3688]. 2411 The following registration has been made in [RFC6087] and updated by 2412 this document. 2414 URI: urn:ietf:params:xml:ns:yang:ietf-template 2416 Registrant Contact: The IESG. 2418 XML: N/A, the requested URI is an XML namespace. 2420 The following assignment has been made in [RFC6087] and updated by 2421 this document in the YANG Module Names Registry, or the YANG module 2422 template in Appendix C. 2424 +-----------+-------------------------------------------+ 2425 | Field | Value | 2426 +-----------+-------------------------------------------+ 2427 | Name | ietf-template | 2428 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 2429 | Prefix | temp | 2430 | Reference | RFC XXXX | 2431 +-----------+-------------------------------------------+ 2433 YANG Registry Assignment 2435 6. Security Considerations 2437 This document defines documentation guidelines for NETCONF or 2438 RESTCONF content defined with the YANG data modeling language, and 2439 therefore does not introduce any new or increased security risks into 2440 the management system. 2442 7. Acknowledgments 2444 The structure and contents of this document are adapted from 2445 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 2447 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 2448 Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive 2449 reviews and contributions to this document. 2451 8. References 2453 8.1. Normative References 2455 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2456 Requirement Levels", BCP 14, RFC 2119, March 1997. 2458 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2459 January 2004. 2461 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2462 Resource Identifier (URI): Generic Syntax", STD 66, 2463 RFC 3986, January 2005. 2465 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2466 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 2467 RFC5246, August 2008, 2468 . 2470 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 2471 to the IETF Trust", BCP 78, RFC 5378, November 2008. 2473 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2474 Network Configuration Protocol (NETCONF)", RFC 6020, 2475 October 2010. 2477 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2478 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2479 . 2481 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2482 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2483 May 2017, . 2485 [W3C.REC-xpath-19991116] 2486 Clark, J. and S. DeRose, "XML Path Language (XPath) 2487 Version 1.0", World Wide Web Consortium 2488 Recommendation REC-xpath-19991116, November 1999, 2489 . 2491 8.2. Informative References 2493 [I-D.ietf-netmod-revised-datastores] 2494 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2495 and R. Wilton, "Network Management Datastore 2496 Architecture", draft-ietf-netmod-revised-datastores-10 2497 (work in progress), January 2018. 2499 [I-D.ietf-netmod-yang-tree-diagrams] 2500 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", 2501 draft-ietf-netmod-yang-tree-diagrams-04 (work in 2502 progress), December 2017. 2504 [RFC-STYLE] 2505 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 2506 Style", September 2009, 2507 . 2509 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 2510 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 2511 . 2513 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 2514 RFC 4151, DOI 10.17487/RFC4151, October 2005, 2515 . 2517 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 2518 Documents", BCP 111, RFC 4181, September 2005. 2520 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 2521 Data Model Documents", RFC 6087, January 2011. 2523 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2524 and A. Bierman, Ed., "Network Configuration Protocol 2525 (NETCONF)", RFC 6241, June 2011. 2527 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2528 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2529 . 2531 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2532 Protocol (NETCONF) Access Control Model", RFC 6536, 2533 March 2012. 2535 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2536 July 2013. 2538 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2539 Management", RFC 7223, May 2014. 2541 [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, 2542 DOI 10.17487/RFC7322, September 2014, 2543 . 2545 [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., 2546 "RFC Streams, Headers, and Boilerplates", RFC 7841, 2547 DOI 10.17487/RFC7841, May 2016, 2548 . 2550 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2551 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2552 . 2554 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2555 Writing an IANA Considerations Section in RFCs", BCP 26, 2556 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2557 . 2559 Appendix A. Change Log 2561 -- RFC Ed.: remove this section before publication. 2563 A.1. v15 to v16 2565 o address document shephard comments posted 2018-01-15 2567 o add yang-version to template module 2569 A.2. v14 to v15 2571 o changed Intended status from Informational to BCP 2573 o update tree diagram guidelines section 2575 o Change IANA template to list IESG instead of NETMOD WG as the 2576 Registrant 2578 o Update some references 2580 A.3. v13 to v14 2582 o Replaced sec. 4.23 Operational Data with Operational Data from 2583 NMDA text by Lou Berger and Kent Watsen 2585 o Added NMDA Terms section 2587 o Changed term operational data to operational state 2589 o Clarified that reference-stmt SHOULD be present in import-stmt 2591 A.4. v12 to v13 2593 o Clarify that the revision-date SHOULD be used in a CODE BEGINS 2594 YANG file extraction macro. 2596 o Clarify the IANA requirements section wrt/ XML namespace and YANG 2597 module name registries. 2599 o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. 2601 o Update Operation Data section to consider revised datastores. 2603 o Add reference to YANG Tree Diagrams and update 2 sections that use 2604 this reference. 2606 o Add reference to Revised Datastores and guidelines drafts 2608 A.5. v11 to v12 2610 o fix incorrect location of new Module Usage Examples section 2612 A.6. v10 to v11 2614 o updated YANG tree diagram syntax to align with pyang 1.7.1 2616 o added general guideline to include module usage examples 2618 A.7. v09 to v10 2620 o clarified is only for normative modules 2622 o clarified example module namespace URI conventions 2624 o clarified pyang usage for normative and example modules 2626 o updated YANG tree diagrams section with text from RFC 8022 2628 A.8. v08 to v09 2630 o fixed references 2632 o added mention of RESTCONF to abstract and intro 2634 o created separate section for code components 2636 o fixed document status 2638 A.9. v07 to v08 2640 o changed CODE BEGINS guideline for example modules 2642 o updated tree diagram guidelines 2644 o clarified published and unpublished terms 2646 o added section on Empty and Boolean data types 2648 o clarified how to update the revision statement 2650 o updated operational state guidelines 2652 o added 'YANG fragment' to terminology section 2654 A.10. v06 to v07 2656 o update contact statement guideline 2658 o update example modules guidelines 2660 o add guidelines on top-level data nodes 2662 o add guideline on use of NP containers 2664 o added guidelines on union types 2666 o add guideline on deviations 2668 o added section on open systems considerations 2670 o added guideline about definitions reserved for future use 2672 A.11. v05 to v06 2674 o Changed example 'my-module' to 'example-module' 2676 o Added section Updating YANG Modules (Published vs. Unpublished) 2678 o Added Example Modules section 2680 o Added "" convention for full example modules 2682 o Added section on using action vs. rpc 2684 o Changed term "operational state" to "operational data" 2686 o Added section on YANG Data Node Constraints 2688 o Added guidelines on using must vs. when statements 2690 o Made ietf-foo module validate for I-D submission 2692 A.12. v04 to v05 2694 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if 2695 no YANG 1.1 features needed 2697 o Changed SHOULD follow YANG naming conventions to MUST follow (for 2698 standards track documents only) 2700 o Clarified module naming conventions for normative modules, example 2701 modules, and modules from other SDOs. 2703 o Added prefix value selection guidelines 2705 o Added new section on guidelines for reusable groupings 2707 o Made header guidelines less IETF-specific 2709 o Added new section on guidelines for extension statements 2711 o Added guidelines for nested "choice" statement within a "case" 2712 statement 2714 A.13. v03 ot v04 2716 o Added sections for deviation statements and performance 2717 considerations 2719 o Added YANG 1.1 section 2721 o Updated YANG reference from 1.0 to 1.1 2723 A.14. v02 to v03 2725 o Updated draft based on github data tracker issues added by Benoit 2726 Clause (Issues 12 - 18) 2728 A.15. v01 to v02 2730 o Updated draft based on mailing list comments. 2732 A.16. v00 to v01 2734 All issues from the issue tracker have been addressed. 2736 https://github.com/netmod-wg/rfc6087bis/issues 2738 o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with 2739 YANG modules can use an Informative reference to this RFC for tree 2740 diagrams. Updated guidelines to reference this RFC when tree 2741 diagrams are used 2743 o Issue 2: XPath function restrictions: Added paragraphs in XPath 2744 usage section for 'id', 'namespace-uri', 'name', and 'lang' 2745 functions 2747 o Issue 3: XPath function document order issues: Added paragraph in 2748 XPath usage section about node-set ordering for 'local-name', 2749 'namespace-uri', 'name', 'string' and 'number' functions. Also 2750 any function that implicitly converts a node-set to a string. 2752 o Issue 4: XPath preceding-sibling and following-sibling: Checked 2753 and text in XPath usage section already has proposed text from 2754 Lada. 2756 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 2757 exception and example in XPath Usage section for augmented nodes. 2759 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 2760 to 'numeric and boolean expressions' 2762 o Issue 7: XPath module containment: Added sub-section on XPath 2763 wildcards 2765 o Issue 8: status-stmt usage: Added text to Lifecycle Management 2766 section about transitioning from active to deprecated and then to 2767 obsolete. 2769 o Issue 9: resource identification in notifications: Add text to 2770 Notifications section about identifying resources and using the 2771 leafref data type. 2773 o Issue 10: single quoted strings: Added text to Data Types section 2774 about using a single-quoted string for patterns. 2776 Appendix B. Module Review Checklist 2778 This section is adapted from RFC 4181. 2780 The purpose of a YANG module review is to review the YANG module both 2781 for technical correctness and for adherence to IETF documentation 2782 requirements. The following checklist may be helpful when reviewing 2783 an Internet-Draft: 2785 o I-D Boilerplate -- verify that the draft contains the required 2786 Internet-Draft boilerplate (see 2787 http://www.ietf.org/id-info/guidelines.html), including the 2788 appropriate statement to permit publication as an RFC, and that 2789 I-D boilerplate does not contain references or section numbers. 2791 o Abstract -- verify that the abstract does not contain references, 2792 that it does not have a section number, and that its content 2793 follows the guidelines in 2794 http://www.ietf.org/id-info/guidelines.html. 2796 o Copyright Notice -- verify that the draft has the appropriate text 2797 regarding the rights that document contributers provide to the 2798 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 2799 copyright notice at the beginning of the document. The IETF Trust 2800 Legal Provisions (TLP) can be found at: 2802 http://trustee.ietf.org/license-info/ 2804 o Security Considerations section -- verify that the draft uses the 2805 latest approved template from the OPS area website (http:// 2806 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 2807 and that the guidelines therein have been followed. 2809 o IANA Considerations section -- this section must always be 2810 present. For each module within the document, ensure that the 2811 IANA Considerations section contains entries for the following 2812 IANA registries: 2814 XML Namespace Registry: Register the YANG module namespace. 2816 YANG Module Registry: Register the YANG module name, prefix, 2817 namespace, and RFC number, according to the rules specified 2818 in [RFC7950]. 2820 o References -- verify that the references are properly divided 2821 between normative and informative references, that RFC 2119 is 2822 included as a normative reference if the terminology defined 2823 therein is used in the document, that all references required by 2824 the boilerplate are present, that all YANG modules containing 2825 imported items are cited as normative references, and that all 2826 citations point to the most current RFCs unless there is a valid 2827 reason to do otherwise (for example, it is OK to include an 2828 informative reference to a previous version of a specification to 2829 help explain a feature included for backward compatibility). Be 2830 sure citations for all imported modules are present somewhere in 2831 the document text (outside the YANG module). 2833 o License -- verify that the draft contains the Simplified BSD 2834 License in each YANG module or submodule. Some guidelines related 2835 to this requirement are described in Section 3.1. Make sure that 2836 the correct year is used in all copyright dates. Use the approved 2837 text from the latest Trust Legal Provisions (TLP) document, which 2838 can be found at: 2840 http://trustee.ietf.org/license-info/ 2842 o Other Issues -- check for any issues mentioned in 2843 http://www.ietf.org/id-info/checklist.html that are not covered 2844 elsewhere. 2846 o Technical Content -- review the actual technical content for 2847 compliance with the guidelines in this document. The use of a 2848 YANG module compiler is recommended when checking for syntax 2849 errors. A list of freely available tools and other information 2850 can be found at: 2852 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2854 Checking for correct syntax, however, is only part of the job. 2855 It is just as important to actually read the YANG module document 2856 from the point of view of a potential implementor. It is 2857 particularly important to check that description statements are 2858 sufficiently clear and unambiguous to allow interoperable 2859 implementations to be created. 2861 Appendix C. YANG Module Template 2863 file "ietf-template@2016-03-20.yang" 2865 module ietf-template { 2867 yang-version 1.1; 2869 // replace this string with a unique namespace URN value 2870 namespace 2871 "urn:ietf:params:xml:ns:yang:ietf-template"; 2873 // replace this string, and try to pick a unique prefix 2874 prefix "temp"; 2876 // import statements here: e.g., 2877 // import ietf-yang-types { prefix yang; } 2878 // import ietf-inet-types { prefix inet; } 2880 // identify the IETF working group if applicable 2881 organization 2882 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2884 // update this contact statement with your info 2885 contact 2886 "WG Web: 2887 WG List: 2889 Editor: your-name 2890 "; 2892 // replace the first sentence in this description statement. 2893 // replace the copyright notice with the most recent 2894 // version, if it has been updated since the publication 2895 // of this document 2896 description 2897 "This module defines a template for other YANG modules. 2899 Copyright (c) IETF Trust and the persons 2900 identified as authors of the code. All rights reserved. 2902 Redistribution and use in source and binary forms, with or 2903 without modification, is permitted pursuant to, and subject 2904 to the license terms contained in, the Simplified BSD License 2905 set forth in Section 4.c of the IETF Trust's Legal Provisions 2906 Relating to IETF Documents 2907 (http://trustee.ietf.org/license-info). 2908 This version of this YANG module is part of RFC XXXX; see 2909 the RFC itself for full legal notices."; 2911 // RFC Ed.: replace XXXX with actual RFC number and remove 2912 // this note 2914 reference "RFC XXXX"; 2916 // RFC Ed.: remove this note 2917 // Note: extracted from RFC XXXX 2919 // replace '2016-03-20' with the module publication date 2920 // The format is (year-month-day) 2921 revision "2016-03-20" { 2922 description "what changed in this revision"; 2923 reference "document containing this module"; 2924 } 2926 // extension statements 2928 // feature statements 2930 // identity statements 2932 // typedef statements 2934 // grouping statements 2936 // data definition statements 2938 // augment statements 2940 // rpc statements 2942 // notification statements 2944 // DO NOT put deviation statements in a published module 2946 } 2948 2950 Author's Address 2952 Andy Bierman 2953 YumaWorks 2955 Email: andy@yumaworks.com