idnits 2.17.1 draft-ietf-netmod-rfc6087bis-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 24, 2015) is 3290 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 299, but not defined == Missing Reference: 'RFC6242' is mentioned on line 1108, but not defined ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track April 24, 2015 5 Expires: October 26, 2015 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-02 10 Abstract 12 This memo provides guidelines for authors and reviewers of Standards 13 Track specifications containing YANG data model modules. Applicable 14 portions may be used as a basis for reviews of other YANG data model 15 documents. Recommendations and procedures are defined, which are 16 intended to increase interoperability and usability of Network 17 Configuration Protocol (NETCONF) implementations that utilize YANG 18 data model modules. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on October 26, 2015. 37 Copyright Notice 39 Copyright (c) 2015 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 57 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 58 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 61 4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 62 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 63 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 64 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 65 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 9 66 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 67 4.6. Security Considerations Section . . . . . . . . . . . . . 10 68 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 69 4.7.1. Documents that Create a New Namespace . . . . . . . . 11 70 4.7.2. Documents that Extend an Existing Namespace . . . . . 11 71 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11 72 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 73 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 74 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 75 5.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 13 76 5.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 5.4. Conditional Statements . . . . . . . . . . . . . . . . . . 14 78 5.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 15 79 5.5.1. Function Library . . . . . . . . . . . . . . . . . . . 15 80 5.5.2. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 15 81 5.5.3. Types . . . . . . . . . . . . . . . . . . . . . . . . 16 82 5.5.4. Wildcards . . . . . . . . . . . . . . . . . . . . . . 17 83 5.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 17 84 5.7. Module Header, Meta, and Revision Statements . . . . . . . 18 85 5.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 19 86 5.9. Top-Level Data Definitions . . . . . . . . . . . . . . . . 20 87 5.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 20 88 5.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 21 89 5.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 21 90 5.13. Operation Definitions . . . . . . . . . . . . . . . . . . 23 91 5.14. Notification Definitions . . . . . . . . . . . . . . . . . 23 92 5.15. Feature Definitions . . . . . . . . . . . . . . . . . . . 24 93 5.16. Data Correlation . . . . . . . . . . . . . . . . . . . . . 24 94 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 95 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 96 7.1. Security Considerations Section Template . . . . . . . . . 27 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 98 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 30 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 100 10.1. Normative References . . . . . . . . . . . . . . . . . . . 31 101 10.2. Informative References . . . . . . . . . . . . . . . . . . 31 102 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33 103 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 33 104 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 34 105 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 36 106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38 108 1. Introduction 110 The standardization of network configuration interfaces for use with 111 the Network Configuration Protocol [RFC6241] requires a modular set 112 of data models, which can be reused and extended over time. 114 This document defines a set of usage guidelines for Standards Track 115 documents containing [RFC6020] data models. YANG is used to define 116 the data structures, protocol operations, and notification content 117 used within a NETCONF server. A server that supports a particular 118 YANG module will support client NETCONF operation requests, as 119 indicated by the specific content defined in the YANG module. 121 This document is similar to the Structure of Management Information 122 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 123 and structure. However, since that document was written a decade 124 after SMIv2 modules had been in use, it was published as a 'Best 125 Current Practice' (BCP). This document is not a BCP, but rather an 126 informational reference, intended to promote consistency in documents 127 containing YANG modules. 129 Many YANG constructs are defined as optional to use, such as the 130 description statement. However, in order to maximize 131 interoperability of NETCONF implementations utilizing YANG data 132 models, it is desirable to define a set of usage guidelines that may 133 require a higher level of compliance than the minimum level defined 134 in the YANG specification. 136 In addition, YANG allows constructs such as infinite length 137 identifiers and string values, or top-level mandatory nodes, that a 138 compliant server is not required to support. Only constructs that 139 all servers are required to support can be used in IETF YANG modules. 141 This document defines usage guidelines related to the NETCONF 142 operations layer and NETCONF content layer, as defined in [RFC6241]. 143 These guidelines are intended to be used by authors and reviewers to 144 improve the readability and interoperability of published YANG data 145 models. 147 Note that this document is not a YANG tutorial and the reader is 148 expected to know the YANG data modeling language before using this 149 document. 151 2. Terminology 153 2.1. Requirements Notation 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 157 document are to be interpreted as described in [RFC2119]. 159 RFC 2119 language is used here to express the views of the NETMOD 160 working group regarding content for YANG modules. YANG modules 161 complying with this document will treat the RFC 2119 terminology as 162 if it were describing best current practices. 164 2.2. NETCONF Terms 166 The following terms are defined in [RFC6241] and are not redefined 167 here: 169 o capabilities 171 o client 173 o operation 175 o server 177 2.3. YANG Terms 179 The following terms are defined in [RFC6020] and are not redefined 180 here: 182 o data node 184 o module 186 o namespace 188 o submodule 190 o version 192 o YANG 194 o YIN 196 Note that the term 'module' may be used as a generic term for a YANG 197 module or submodule. When describing properties that are specific to 198 submodules, the term 'submodule' is used instead. 200 2.4. Terms 202 The following terms are used throughout this document: 204 o published: A stable release of a module or submodule, usually 205 contained in an RFC. 207 o unpublished: An unstable release of a module or submodule, usually 208 contained in an Internet-Draft. 210 3. YANG Tree Diagrams 212 YANG tree diagrams provide a concise representation of a YANG module 213 to help readers understand the module structure. 215 The meaning of the symbols in YANG tree diagrams is as follows: 217 o Brackets "[" and "]" enclose list keys. 219 o Abbreviations before data node names: "rw" means configuration 220 (read-write) and "ro" state data (read-only). 222 o Symbols after data node names: "?" means an optional node, "!" 223 means a presence container, and "*" denotes a list and leaf-list. 225 o Parentheses enclose choice and case nodes, and case nodes are also 226 marked with a colon (":"). 228 o Ellipsis ("...") stands for contents of subtrees that are not 229 shown. 231 4. General Documentation Guidelines 233 YANG data model modules under review are likely to be contained in 234 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 235 followed. The RFC Editor provides guidelines for authors of RFCs, 236 which are first published as Internet-Drafts. These guidelines 237 should be followed and are defined in [RFC2223] and updated in 238 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 240 The following sections MUST be present in an Internet-Draft 241 containing a module: 243 o Narrative sections 245 o Definitions section 247 o Security Considerations section 249 o IANA Considerations section 251 o References section 253 4.1. Module Copyright 255 The module description statement MUST contain a reference to the 256 latest approved IETF Trust Copyright statement, which is available 257 online at: 259 http://trustee.ietf.org/license-info/ 261 Each YANG module or submodule contained within an Internet-Draft or 262 RFC is considered to be a code component. The strings '' and '' MUST be used to identify each code 264 component. 266 The '' tag SHOULD be followed by a string identifying 267 the file name specified in Section 5.2 of [RFC6020]. The following 268 example is for the '2010-01-18' revision of the 'ietf-foo' module: 270 file "ietf-foo@2010-01-18.yang" 271 module ietf-foo { 272 // ... 273 revision 2010-01-18 { 274 description "Latest revision"; 275 reference "RFC XXXX"; 276 } 277 // ... 278 } 280 282 Note that this convention MUST NOT be used for example modules or 283 module fragments. 285 [FIXME: should a new convention called be added for 286 YANG example modules?] 288 4.2. Terminology Section 290 A terminology section MUST be present if any terms are defined in the 291 document or if any terms are imported from other documents. 293 If YANG tree diagrams are used, then a sub-section explaining the 294 YANG tree diagram syntax MUST be present, containing the following 295 text: 297 A simplified graphical representation of the data model is used in 298 this document. The meaning of the symbols in these diagrams is 299 defined in [RFCXXXX]. 301 -- RFC Editor: Replace XXXX with RFC number and remove note 303 4.3. Tree Diagrams 305 YANG tree diagrams provide a concise representation of a YANG module, 306 and SHOULD be included to help readers understand YANG module 307 structure. Tree diagrams MAY be split into sections to correspond to 308 document structure. 310 The following example shows a simple YANG tree diagram: 312 +--rw top-level-config-container 313 | +--rw config-list* [key-name] 314 | +--rw key-name string 315 | +--rw optional-parm? string 316 | +--rw mandatory-parm identityref 317 | +--ro read-only-leaf string 318 +--ro top-level-nonconfig-container 319 +--ro nonconfig-list* [name] 320 +--ro name string 321 +--ro type string 323 4.4. Narrative Sections 325 The narrative part MUST include an overview section that describes 326 the scope and field of application of the module(s) defined by the 327 specification and that specifies the relationship (if any) of these 328 modules to other standards, particularly to standards containing 329 other YANG modules. The narrative part SHOULD include one or more 330 sections to briefly describe the structure of the modules defined in 331 the specification. 333 If the module(s) defined by the specification imports definitions 334 from other modules (except for those defined in the [RFC6020] or 335 [RFC6991] documents), or are always implemented in conjunction with 336 other modules, then those facts MUST be noted in the overview 337 section, as MUST be noted any special interpretations of definitions 338 in other modules. 340 4.5. Definitions Section 342 This section contains the module(s) defined by the specification. 343 These modules MUST be written using the YANG syntax defined in 344 [RFC6020]. A YIN syntax version of the module MAY also be present in 345 the document. There MAY also be other types of modules present in 346 the document, such as SMIv2, which are not affected by these 347 guidelines. 349 See Section 5 for guidelines on YANG usage. 351 4.6. Security Considerations Section 353 Each specification that defines one or more modules MUST contain a 354 section that discusses security considerations relevant to those 355 modules. 357 This section MUST be patterned after the latest approved template 358 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 359 yang-security-guidelines). Section 7.1 contains the security 360 considerations template dated 2013-05-08. Authors MUST check the 361 webpage at the URL listed above in case there is a more recent 362 version available. 364 In particular: 366 o Writable data nodes that could be especially disruptive if abused 367 MUST be explicitly listed by name and the associated security 368 risks MUST be explained. 370 o Readable data nodes that contain especially sensitive information 371 or that raise significant privacy concerns MUST be explicitly 372 listed by name and the reasons for the sensitivity/privacy 373 concerns MUST be explained. 375 o Operations (i.e., YANG 'rpc' statements) that are potentially 376 harmful to system behavior or that raise significant privacy 377 concerns MUST be explicitly listed by name and the reasons for the 378 sensitivity/privacy concerns MUST be explained. 380 4.7. IANA Considerations Section 382 In order to comply with IESG policy as set forth in 383 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 384 is submitted to the IESG for publication MUST contain an IANA 385 Considerations section. The requirements for this section vary 386 depending on what actions are required of the IANA. If there are no 387 IANA considerations applicable to the document, then the IANA 388 Considerations section stating that there are no actions is removed 389 by the RFC Editor before publication. Refer to the guidelines in 390 [RFC5226] for more details. 392 4.7.1. Documents that Create a New Namespace 394 If an Internet-Draft defines a new namespace that is to be 395 administered by the IANA, then the document MUST include an IANA 396 Considerations section that specifies how the namespace is to be 397 administered. 399 Specifically, if any YANG module namespace statement value contained 400 in the document is not already registered with IANA, then a new YANG 401 Namespace registry entry MUST be requested from the IANA. The 402 [RFC6020] specification includes the procedure for this purpose in 403 its IANA Considerations section. 405 4.7.2. Documents that Extend an Existing Namespace 407 It is possible to extend an existing namespace using a YANG submodule 408 that belongs to an existing module already administered by IANA. In 409 this case, the document containing the main module MUST be updated to 410 use the latest revision of the submodule. 412 4.8. Reference Sections 414 For every import or include statement that appears in a module 415 contained in the specification, which identifies a module in a 416 separate document, a corresponding normative reference to that 417 document MUST appear in the Normative References section. The 418 reference MUST correspond to the specific module version actually 419 used within the specification. 421 For every normative reference statement that appears in a module 422 contained in the specification, which identifies a separate document, 423 a corresponding normative reference to that document SHOULD appear in 424 the Normative References section. The reference SHOULD correspond to 425 the specific document version actually used within the specification. 426 If the reference statement identifies an informative reference, which 427 identifies a separate document, a corresponding informative reference 428 to that document MAY appear in the Informative References section. 430 4.9. Validation Tools 432 All modules need to be validated before submission in an Internet 433 Draft. The 'pyang' YANG compiler is freely available from github: 435 https://github.com/mbj4668/pyang 437 If the 'pyang' compiler is used, then the "--ietf" command line 438 option SHOULD be used to identify any IETF guideline issues. 440 5. YANG Usage Guidelines 442 In general, modules in IETF Standards Track specifications MUST 443 comply with all syntactic and semantic requirements of YANG 444 [RFC6020]. The guidelines in this section are intended to supplement 445 the YANG specification, which is intended to define a minimum set of 446 conformance requirements. 448 In order to promote interoperability and establish a set of practices 449 based on previous experience, the following sections establish usage 450 guidelines for specific YANG constructs. 452 Only guidelines that clarify or restrict the minimum conformance 453 requirements are included here. 455 5.1. Module Naming Conventions 457 Modules contained in Standards Track documents SHOULD be named 458 according to the guidelines in the IANA Considerations section of 459 [RFC6020]. 461 A distinctive word or acronym (e.g., protocol name or working group 462 acronym) SHOULD be used in the module name. If new definitions are 463 being defined to extend one or more existing modules, then the same 464 word or acronym should be reused, instead of creating a new one. 466 All published module names MUST be unique. For a YANG module 467 published in an RFC, this uniqueness is guaranteed by IANA. For 468 unpublished modules, the authors need to check that no other work in 469 progress is using the same module name. 471 Once a module name is published, it MUST NOT be reused, even if the 472 RFC containing the module is reclassified to 'Historic' status. 474 5.2. Identifiers 476 Identifiers for all YANG identifiers in published modules MUST be 477 between 1 and 64 characters in length. These include any construct 478 specified as an 'identifier-arg-str' token in the ABNF in Section 12 479 of [RFC6020]. 481 5.3. Defaults 483 In general, it is suggested that substatements containing very common 484 default values SHOULD NOT be present. The following substatements 485 are commonly used with the default value, which would make the module 486 difficult to read if used everywhere they are allowed. 488 +--------------+---------------+ 489 | Statement | Default Value | 490 +--------------+---------------+ 491 | config | true | 492 | mandatory | false | 493 | max-elements | unbounded | 494 | min-elements | 0 | 495 | ordered-by | system | 496 | status | current | 497 | yin-element | false | 498 +--------------+---------------+ 500 Statement Defaults 502 5.4. Conditional Statements 504 A module may be conceptually partitioned in several ways, using the 505 'if-feature' and/or 'when' statements. 507 Data model designers need to carefully consider all modularity 508 aspects, including the use of YANG conditional statements. 510 If a data definition is optional, depending on server support for a 511 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 512 be defined to indicate that the NETCONF capability is supported 513 within the data model. 515 If any notification data, or any data definition, for a non- 516 configuration data node is not mandatory, then the server may or may 517 not be required to return an instance of this data node. If any 518 conditional requirements exist for returning the data node in a 519 notification payload or retrieval request, they MUST be documented 520 somewhere. For example, a 'when' or 'if-feature' statement could 521 apply to the data node, or the conditional requirements could be 522 explained in a 'description' statement within the data node or one of 523 its ancestors (if any). 525 If any 'if-feature' statements apply to a list node, then the same 526 'if-feature' statements MUST apply to any key leaf nodes for the 527 list. There MUST NOT be any 'if-feature' statements applied to any 528 key leaf that do not also apply to the parent list node. 530 There SHOULD NOT be any 'when' statements applied to a key leaf node. 531 It is possible that a 'when' statement for an ancestor node of a key 532 leaf will have the exact node-set result as the key leaf. In such as 533 case, the 'when' statement for the key leaf is redundant and SHOULD 534 be avoided. 536 5.5. XPath Usage 538 This section describes guidelines for using the XML Path Language 539 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 541 5.5.1. Function Library 543 The 'position' and 'last' functions SHOULD NOT be used. This applies 544 to implicit use of the 'position' function as well (e.g., 545 '//chapter[42]'). A server is only required to maintain the relative 546 XML document order of all instances of a particular user-ordered list 547 or leaf-list. The 'position' and 'last' functions MAY be used if 548 they are evaluated in a context where the context node is a user- 549 ordered 'list' or 'leaf-list'. 551 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 552 present in YANG documents so this function has no meaning. The YANG 553 compiler SHOULD return an empty string for this function. 555 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 556 Expanded names in XPath are different than YANG. A specific 557 canonical representation of a YANG expanded name does not exist. 559 The 'lang' function SHOULD NOT be used. This function does not apply 560 to YANG because there is no 'lang' attribute set with the document. 561 The YANG compiler SHOULD return 'false' for this function. 563 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 564 functions SHOULD NOT be used if the argument is a node-set. If so, 565 the function result will be determined by the document order of the 566 node-set. Since this order can be different on each server, the 567 function results can also be different. Any function call that 568 implicitly converts a node-set to a string will also have this issue. 570 The 'local-name' function SHOULD NOT be used to reference local names 571 outside of the YANG module defining the must or when expression 572 containing the 'local-name' function. Example of a local-name 573 function that should not be used: 575 /*[local-name()='foo'] 577 5.5.2. Axes 579 The 'attribute' and 'namespace' axes are not supported in YANG, and 580 MAY be empty in a NETCONF server implementation. 582 The 'preceding', and 'following' axes SHOULD NOT be used. These 583 constructs rely on XML document order within a NETCONF server 584 configuration database, which may not be supported consistently or 585 produce reliable results across implementations. Predicate 586 expressions based on static node properties (e.g., element name or 587 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 588 'preceding' and 'following' axes MAY be used if document order is not 589 relevant to the outcome of the expression (e.g., check for global 590 uniqueness of a parameter value). 592 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 593 however they MAY be used if document order is not relevant to the 594 outcome of the expression. 596 A server is only required to maintain the relative XML document order 597 of all instances of a particular user-ordered list or leaf-list. The 598 'preceding-sibling' and 'following-sibling' axes MAY be used if they 599 are evaluated in a context where the context node is a user-ordered 600 'list' or 'leaf-list'. 602 5.5.3. Types 604 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 605 be used within numeric or boolean expressions. There are boundary 606 conditions in which the translation from the YANG 64-bit type to an 607 XPath number can cause incorrect results. Specifically, an XPath 608 'double' precision floating point number cannot represent very large 609 positive or negative 64-bit numbers because it only provides a total 610 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 611 used in numeric expressions if the value can be represented with no 612 more than 53 bits of precision. 614 Data modelers need to be careful not to confuse the YANG value space 615 and the XPath value space. The data types are not the same in both, 616 and conversion between YANG and XPath data types SHOULD be considered 617 carefully. 619 Explicit XPath data type conversions MAY be used (e.g., 'string', 620 'boolean', or 'number' functions), instead of implicit XPath data 621 type conversions. 623 XPath expressions that contain a literal value representing a YANG 624 identity SHOULD always include the declared prefix of the module 625 where the identity is defined. 627 XPath expressions for 'when' statements SHOULD NOT reference the 628 context node or any descendant nodes of the context node. They MAY 629 reference descendant nodes if the 'when' statement is contained 630 within an 'augment' statement, and the referenced nodes are not 631 defined within the 'augment' statement. 633 Example: 635 augment "/rt:active-route/rt:input/rt:destination-address" { 636 when "rt:address-family='v4ur:ipv4-unicast'" { 637 description 638 "This augment is valid only for IPv4 unicast."; 639 } 640 // nodes defined here within the augment-stmt 641 // cannot be referenced in the when-stmt 642 } 644 5.5.4. Wildcards 646 It is possible to construct XPath expressions that will evaluate 647 differently when combined with several modules within a server 648 implementation, then when evaluated within the single module. This 649 is due to augmenting nodes from other modules. 651 Wildcard expansion is done within a server against all the nodes from 652 all namespaces, so it is possible for a 'must' or 'when' expression 653 that uses the '*' operator will always evaluate to false if processed 654 within a single YANG module. In such cases, the 'description' 655 statement SHOULD clarify that augmenting objects are expected to 656 match the wildcard expansion. 658 when /foo/services/*/active { 659 description 660 "No services directly defined in this module. 661 Matches objects that have augmented the services container."; 662 } 664 5.6. Lifecycle Management 666 The status statement MUST be present if its value is 'deprecated' or 667 'obsolete'. The status SHOULD NOT be changed from 'current' directly 668 to 'obsolete'. An object SHOULD be available for at least one year 669 with 'deprecated' status before it is changed to 'obsolete'. 671 The module or submodule name MUST NOT be changed, once the document 672 containing the module or submodule is published. 674 The module namespace URI value MUST NOT be changed, once the document 675 containing the module is published. 677 The revision-date substatement within the imports statement SHOULD be 678 present if any groupings are used from the external module. 680 The revision-date substatement within the include statement SHOULD be 681 present if any groupings are used from the external submodule. 683 If submodules are used, then the document containing the main module 684 MUST be updated so that the main module revision date is equal or 685 more recent than the revision date of any submodule that is (directly 686 or indirectly) included by the main module. 688 5.7. Module Header, Meta, and Revision Statements 690 For published modules, the namespace MUST be a globally unique URI, 691 as defined in [RFC3986]. This value is usually assigned by the IANA. 693 The organization statement MUST be present. If the module is 694 contained in a document intended for Standards Track status, then the 695 organization SHOULD be the IETF working group chartered to write the 696 document. 698 The contact statement MUST be present. If the module is contained in 699 a document intended for Standards Track status, then the working 700 group web and mailing information MUST be present, and the main 701 document author or editor contact information SHOULD be present. If 702 additional authors or editors exist, their contact information MAY be 703 present. In addition, the Area Director and other contact 704 information MAY be present. 706 The description statement MUST be present. The appropriate IETF 707 Trust Copyright text MUST be present, as described in Section 4.1. 709 If the module relies on information contained in other documents, 710 which are not the same documents implied by the import statements 711 present in the module, then these documents MUST be identified in the 712 reference statement. 714 A revision statement MUST be present for each published version of 715 the module. The revision statement MUST have a reference 716 substatement. It MUST identify the published document that contains 717 the module. Modules are often extracted from their original 718 documents, and it is useful for developers and operators to know how 719 to find the original source document in a consistent manner. The 720 revision statement MAY have a description substatement. 722 Each new revision MUST include a revision date that is higher than 723 any other revision date in the module. The revision date does not 724 need to be updated if the module contents do not change in the new 725 document revision. 727 It is acceptable to reuse the same revision statement within 728 unpublished versions (i.e., Internet-Drafts), but the revision date 729 MUST be updated to a higher value each time the Internet-Draft is re- 730 posted. 732 5.8. Namespace Assignments 734 It is RECOMMENDED that only valid YANG modules be included in 735 documents, whether or not they are published yet. This allows: 737 o the module to compile correctly instead of generating disruptive 738 fatal errors. 740 o early implementors to use the modules without picking a random 741 value for the XML namespace. 743 o early interoperability testing since independent implementations 744 will use the same XML namespace value. 746 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 747 provided for the namespace statement in a YANG module. A value 748 SHOULD be selected that is not likely to collide with other YANG 749 namespaces. Standard module names, prefixes, and URI strings already 750 listed in the YANG Module Registry MUST NOT be used. 752 A standard namespace statement value SHOULD have the following form: 754 : 756 The following URN prefix string SHOULD be used for published and 757 unpublished YANG modules: 759 urn:ietf:params:xml:ns:yang: 761 The following example URNs would be valid namespace statement values 762 for Standards Track modules: 764 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 766 urn:ietf:params:xml:ns:yang:ietf-netconf-state 768 urn:ietf:params:xml:ns:yang:ietf-netconf 770 Note that a different URN prefix string SHOULD be used for non- 771 Standards-Track modules. The string SHOULD be selected according to 772 the guidelines in [RFC6020]. 774 The following examples of non-Standards-Track modules are only 775 suggestions. There are no guidelines for this type of URN in this 776 document: 778 http://example.com/ns/example-interfaces 780 http://example.com/ns/example-system 782 5.9. Top-Level Data Definitions 784 The top-level data organization SHOULD be considered carefully, in 785 advance. Data model designers need to consider how the functionality 786 for a given protocol or protocol family will grow over time. 788 The separation of configuration data and operational state SHOULD be 789 considered carefully. It is often useful to define separate top- 790 level containers for configuration and non-configuration data. 792 The number of top-level data nodes within a module SHOULD be 793 minimized. It is often useful to retrieve related information within 794 a single subtree. If data is too distributed, is becomes difficult 795 to retrieve all at once. 797 The names and data organization SHOULD reflect persistent 798 information, such as the name of a protocol. The name of the working 799 group SHOULD NOT be used because this may change over time. 801 A mandatory database data definition is defined as a node that a 802 client must provide for the database to be valid. The server is not 803 required to provide a value. 805 Top-level database data definitions MUST NOT be mandatory. If a 806 mandatory node appears at the top level, it will immediately cause 807 the database to be invalid. This can occur when the server boots or 808 when a module is loaded dynamically at runtime. 810 5.10. Data Types 812 Selection of an appropriate data type (i.e., built-in type, existing 813 derived type, or new derived type) is very subjective, and therefore 814 few requirements can be specified on that subject. 816 Data model designers SHOULD use the most appropriate built-in data 817 type for the particular application. 819 If extensibility of enumerated values is required, then the 820 'identityref' data type SHOULD be used instead of an enumeration or 821 other built-in type. 823 For string data types, if a machine-readable pattern can be defined 824 for the desired semantics, then one or more pattern statements SHOULD 825 be present. A single quoted string SHOULD be used to specify the 826 pattern, since a double-quoted string can modify the content. 828 For string data types, if the length of the string is required to be 829 bounded in all implementations, then a length statement MUST be 830 present. 832 For numeric data types, if the values allowed by the intended 833 semantics are different than those allowed by the unbounded intrinsic 834 data type (e.g., 'int32'), then a range statement SHOULD be present. 836 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 837 'int64') SHOULD NOT be used unless negative values are allowed for 838 the desired semantics. 840 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 841 or 'bit' SHOULD be documented. A separate description statement 842 (within each 'enum' or 'bit' statement) SHOULD be present. 844 5.11. Reusable Type Definitions 846 If an appropriate derived type exists in any standard module, such as 847 [RFC6991], then it SHOULD be used instead of defining a new derived 848 type. 850 If an appropriate units identifier can be associated with the desired 851 semantics, then a units statement SHOULD be present. 853 If an appropriate default value can be associated with the desired 854 semantics, then a default statement SHOULD be present. 856 If a significant number of derived types are defined, and it is 857 anticipated that these data types will be reused by multiple modules, 858 then these derived types SHOULD be contained in a separate module or 859 submodule, to allow easier reuse without unnecessary coupling. 861 The description statement MUST be present. 863 If the type definition semantics are defined in an external document 864 (other than another YANG module indicated by an import statement), 865 then the reference statement MUST be present. 867 5.12. Data Definitions 869 The description statement MUST be present in the following YANG 870 statements: 872 o anyxml 874 o augment 876 o choice 878 o container 880 o extension 882 o feature 884 o grouping 886 o identity 888 o leaf 890 o leaf-list 892 o list 894 o notification 896 o rpc 898 o typedef 900 If the data definition semantics are defined in an external document, 901 (other than another YANG module indicated by an import statement), 902 then a reference statement MUST be present. 904 The 'anyxml' construct may be useful to represent an HTML banner 905 containing markup elements, such as '<b>' and '</b>', and 906 MAY be used in such cases. However, this construct SHOULD NOT be 907 used if other YANG data node types can be used instead to represent 908 the desired syntax and semantics. 910 It has been found that the 'anyxml' statement is not implemented 911 consistently across all servers. It is possible that mixed mode XML 912 will not be supported, or configuration anyxml nodes will not 913 supported. 915 If there are referential integrity constraints associated with the 916 desired semantics that can be represented with XPath, then one or 917 more 'must' statements SHOULD be present. 919 For list and leaf-list data definitions, if the number of possible 920 instances is required to be bounded for all implementations, then the 921 max-elements statements SHOULD be present. 923 If any 'must' or 'when' statements are used within the data 924 definition, then the data definition description statement SHOULD 925 describe the purpose of each one. 927 5.13. Operation Definitions 929 If the operation semantics are defined in an external document (other 930 than another YANG module indicated by an import statement), then a 931 reference statement MUST be present. 933 If the operation impacts system behavior in some way, it SHOULD be 934 mentioned in the description statement. 936 If the operation is potentially harmful to system behavior in some 937 way, it MUST be mentioned in the Security Considerations section of 938 the document. 940 5.14. Notification Definitions 942 The description statement MUST be present. 944 If the notification semantics are defined in an external document 945 (other than another YANG module indicated by an import statement), 946 then a reference statement MUST be present. 948 If the notification refers to a specific resource instance, then this 949 instance SHOULD be identified in the notification data. This is 950 usually done by including 'leafref' leaf nodes with the key leaf 951 values for the resource instance. For example: 953 notification interface-up { 954 description "Sent when an interface is activated."; 955 leaf name { 956 type leafref { 957 path "/if:interfaces/if:interface/if:name"; 958 } 959 } 960 } 962 Note that there are no formal YANG statements to identify any data 963 node resources associated with a notification. The description 964 statement for the notification SHOULD specify if and how the 965 notification identifies any data node resources associated with the 966 specific event. 968 5.15. Feature Definitions 970 The YANG "feature" statement is used to define a label for a set of 971 optional functionality within a module. The "if-feature" statement 972 is used in the YANG statements associated with a feature. 974 The set of YANG features available in a module should be considered 975 carefully. The description-stmt within a feature-stmt MUST specify 976 any interactions with other features. 978 If there is a large set of objects associated with a YANG feature, 979 then consider moving those objects to a separate module, instead of 980 using a YANG feature. Note that the set of features within a module 981 is easily discovered by the reader, but the set of related modules 982 within the entire YANG library is not as easy to identity. Module 983 names with a common prefix can help readers identity the set of 984 related modules, but this assumes the reader will have discovered and 985 installed all the relevant modules. 987 If one feature requires implementation of another feature, then an 988 "if-feature" statement SHOULD be used in the dependent "feature" 989 statement. 991 For example, feature2 requires implementation of feature1: 993 feature feature1 { 994 description "Some protocol feature"; 995 } 997 feature feature2 { 998 if-feature "feature1"; 999 description "Another protocol feature"; 1000 } 1002 5.16. Data Correlation 1004 Data can be correlated in various ways, using common data types, 1005 common data naming, and common data organization. There are several 1006 ways to extend the functionality of a module, based on the degree of 1007 coupling between the old and new functionality: 1009 o inline: update the module with new protocol-accessible objects. 1010 The naming and data organization of the original objects is used. 1011 The new objects are in the original module namespace. 1013 o augment: create a new module with new protocol-accessible objects 1014 that augment the original data structure. The naming and data 1015 organization of the original objects is used. The new objects are 1016 in the new module namespace. 1018 o mirror: create new objects in a new module or the original module, 1019 except use new a naming scheme and data location. The naming can 1020 be coupled in different ways. Tight coupling is achieved with a 1021 "leafref" data type. This method SHOULD be used. If the new data 1022 instances are not limited to the values in use in the original 1023 data structure, then the "require-instance" sub-statement MUST be 1024 set to "false". Loose coupling is achieved by using key leafs 1025 with the same data type as the original data structure. 1027 It is sometimes useful to separate configuration and operational 1028 state, so that they do not not even share the exact same naming 1029 characteristics. The correlation between configuration the 1030 operational state data that is affected by changes in configuration 1031 is a complex problem. There may not be a simple 1:1 relationship 1032 between a configuration data node and an operational data node. 1033 Further work is needed in YANG to clarify this relationship. 1034 Protocol work may also be needed to allow a client to retrieve this 1035 type of information from a server. At this time the best practice is 1036 to clearly document any relationship to other data structures in the 1037 "description" statement. 1039 6. IANA Considerations 1041 This document registers one URI in the IETF XML registry [RFC3688]. 1043 The following registration has been made: 1045 URI: urn:ietf:params:xml:ns:yang:ietf-template 1047 Registrant Contact: The NETMOD WG of the IETF. 1049 XML: N/A, the requested URI is an XML namespace. 1051 Per this document, the following assignment has been made in the YANG 1052 Module Names Registry for the YANG module template in Appendix C. 1054 +-----------+-------------------------------------------+ 1055 | Field | Value | 1056 +-----------+-------------------------------------------+ 1057 | Name | ietf-template | 1058 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 1059 | Prefix | temp | 1060 | Reference | RFC XXXX | 1061 +-----------+-------------------------------------------+ 1063 YANG Registry Assignment 1065 7. Security Considerations 1067 This document defines documentation guidelines for NETCONF content 1068 defined with the YANG data modeling language. The guidelines for how 1069 to write a Security Considerations section for a YANG module are 1070 defined in the online document 1072 http://trac.tools.ietf.org/area/ops/trac/wiki/ 1073 yang-security-guidelines 1075 This document does not introduce any new or increased security risks 1076 into the management system. 1078 The following section contains the security considerations template 1079 dated 2010-06-16. Be sure to check the webpage at the URL listed 1080 above in case there is a more recent version available. 1082 Each specification that defines one or more YANG modules MUST contain 1083 a section that discusses security considerations relevant to those 1084 modules. This section MUST be patterned after the latest approved 1085 template (available at 1087 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 1089 In particular, writable data nodes that could be especially 1090 disruptive if abused MUST be explicitly listed by name and the 1091 associated security risks MUST be spelled out. 1093 Similarly, readable data nodes that contain especially sensitive 1094 information or that raise significant privacy concerns MUST be 1095 explicitly listed by name and the reasons for the sensitivity/privacy 1096 concerns MUST be explained. 1098 Further, if new RPC operations have been defined, then the security 1099 considerations of each new RPC operation MUST be explained. 1101 7.1. Security Considerations Section Template 1103 X. Security Considerations 1105 The YANG module defined in this memo is designed to be accessed via 1106 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1107 secure transport layer and the mandatory-to-implement secure 1108 transport is SSH [RFC6242]. 1110 -- if you have any writable data nodes (those are all the 1111 -- "config true" nodes, and remember, that is the default) 1112 -- describe their specific sensitivity or vulnerability. 1114 There are a number of data nodes defined in this YANG module which 1115 are writable/creatable/deletable (i.e., config true, which is the 1116 default). These data nodes may be considered sensitive or vulnerable 1117 in some network environments. Write operations (e.g., edit-config) 1118 to these data nodes without proper protection can have a negative 1119 effect on network operations. These are the subtrees and data nodes 1120 and their sensitivity/vulnerability: 1122 1124 -- for all YANG modules you must evaluate whether any readable data 1125 -- nodes (those are all the "config false" nodes, but also all other 1126 -- nodes, because they can also be read via operations like get or 1127 -- get-config) are sensitive or vulnerable (for instance, if they 1128 -- might reveal customer information or violate personal privacy 1129 -- laws such as those of the European Union if exposed to 1130 -- unauthorized parties) 1132 Some of the readable data nodes in this YANG module may be considered 1133 sensitive or vulnerable in some network environments. It is thus 1134 important to control read access (e.g., via get, get-config, or 1135 notification) to these data nodes. These are the subtrees and data 1136 nodes and their sensitivity/vulnerability: 1138 1140 -- if your YANG module has defined any rpc operations 1141 -- describe their specific sensitivity or vulnerability. 1143 Some of the RPC operations in this YANG module may be considered 1144 sensitive or vulnerable in some network environments. It is thus 1145 important to control access to these operations. These are the 1146 operations and their sensitivity/vulnerability: 1148 1150 8. Acknowledgments 1152 The structure and contents of this document are adapted from 1153 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 1155 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 1156 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 1157 contributions to this document. 1159 9. Changes Since RFC 6087 1161 The following changes have been made to the guidelines published in 1162 [RFC6087]: 1164 o Updated NETCONF reference from RFC 4741 to RFC 6241 1166 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 1168 o Updated YANG Types reference from RFC 6021 to RFC 6991 1170 o Updated obsolete URLs for IETF resources 1172 o Changed top-level data node guideline 1174 o Clarified XPath usage for a literal value representing a YANG 1175 identity 1177 o Clarified XPath usage for a when-stmt 1179 o Clarified XPath usage for 'proceeding-sibling' and 1180 'following-sibling' axes 1182 o Added terminology guidelines 1184 o Added YANG tree diagram definition and guideline 1186 o Updated XPath guidelines for type conversions and function library 1187 usage. 1189 o Updated data types section 1191 o Updated notifications section 1193 o Clarified conditional key leaf nodes 1195 o Clarify usage of 'uint64' and 'int64' data types 1197 o Added text on YANG feature usage 1199 10. References 1201 10.1. Normative References 1203 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1204 Requirement Levels", BCP 14, RFC 2119, March 1997. 1206 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1207 RFC 2223, October 1997. 1209 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1210 January 2004. 1212 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1213 Resource Identifier (URI): Generic Syntax", STD 66, 1214 RFC 3986, January 2005. 1216 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 1217 to the IETF Trust", BCP 78, RFC 5378, November 2008. 1219 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 1220 and Boilerplates", RFC 5741, December 2009. 1222 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1223 Network Configuration Protocol (NETCONF)", RFC 6020, 1224 October 2010. 1226 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1227 and A. Bierman, Ed., "Network Configuration Protocol 1228 (NETCONF)", RFC 6241, June 2011. 1230 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1231 July 2013. 1233 [W3C.REC-xpath-19991116] 1234 Clark, J. and S. DeRose, "XML Path Language (XPath) 1235 Version 1.0", World Wide Web Consortium 1236 Recommendation REC-xpath-19991116, November 1999, 1237 . 1239 10.2. Informative References 1241 [RFC-STYLE] 1242 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 1243 Style", September 2009, 1244 . 1246 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1247 Documents", BCP 111, RFC 4181, September 2005. 1249 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1250 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1251 May 2008. 1253 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 1254 Data Model Documents", RFC 6087, January 2011. 1256 Appendix A. Change Log 1258 -- RFC Ed.: remove this section before publication. 1260 A.1. 00 to 01 1262 All issues from the issue tracker have been addressed. 1264 https://github.com/netmod-wg/rfc6087bis/issues 1266 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 1267 can use an Informative reference to this RFC for tree diagrams. 1268 Updated guidelines to reference this RFC when tree diagrams are 1269 used 1271 o Issue 2: XPath function restrictions: Added paragraphs in XPath 1272 usage section for 'id', 'namespace-uri', 'name', and 'lang' 1273 functions 1275 o Issue 3: XPath function document order issues: Added paragraph in 1276 XPath usage section about node-set ordering for 'local-name', 1277 'namespace-uri', 'name', 'string' and 'number' functions. Also 1278 any function that implicitly converts a node-set to a string. 1280 o Issue 4: XPath preceding-sibling and following-sibling: Checked 1281 and text in XPath usage section already has proposed text from 1282 Lada. 1284 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 1285 exception and example in XPath Usage section for augmented nodes. 1287 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 1288 to 'numeric and boolean expressions' 1290 o Issue 7: XPath module containment: Added sub-section on XPath 1291 wildcards 1293 o Issue 8: status-stmt usage: Added text to Lifecycle Management 1294 section about transitioning from active to deprecated and then to 1295 obsolete. 1297 o Issue 9: resource identification in notifications: Add text to 1298 Notifications section about identifying resources and using the 1299 leafref data type. 1301 o Issue 10: single quoted strings: Added text to Data Types section 1302 about using a single-quoted string for patterns. 1304 Appendix B. Module Review Checklist 1306 This section is adapted from RFC 4181. 1308 The purpose of a YANG module review is to review the YANG module both 1309 for technical correctness and for adherence to IETF documentation 1310 requirements. The following checklist may be helpful when reviewing 1311 an Internet-Draft: 1313 o I-D Boilerplate -- verify that the draft contains the required 1314 Internet-Draft boilerplate (see 1315 http://www.ietf.org/id-info/guidelines.html), including the 1316 appropriate statement to permit publication as an RFC, and that 1317 I-D boilerplate does not contain references or section numbers. 1319 o Abstract -- verify that the abstract does not contain references, 1320 that it does not have a section number, and that its content 1321 follows the guidelines in 1322 http://www.ietf.org/id-info/guidelines.html. 1324 o Copyright Notice -- verify that the draft has the appropriate text 1325 regarding the rights that document contributers provide to the 1326 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 1327 copyright notice at the beginning of the document. The IETF Trust 1328 Legal Provisions (TLP) can be found at: 1330 http://trustee.ietf.org/license-info/ 1332 o Security Considerations section -- verify that the draft uses the 1333 latest approved template from the OPS area website (http:// 1334 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 1335 and that the guidelines therein have been followed. 1337 o IANA Considerations section -- this section must always be 1338 present. For each module within the document, ensure that the 1339 IANA Considerations section contains entries for the following 1340 IANA registries: 1342 XML Namespace Registry: Register the YANG module namespace. 1344 YANG Module Registry: Register the YANG module name, prefix, 1345 namespace, and RFC number, according to the rules specified 1346 in [RFC6020]. 1348 o References -- verify that the references are properly divided 1349 between normative and informative references, that RFC 2119 is 1350 included as a normative reference if the terminology defined 1351 therein is used in the document, that all references required by 1352 the boilerplate are present, that all YANG modules containing 1353 imported items are cited as normative references, and that all 1354 citations point to the most current RFCs unless there is a valid 1355 reason to do otherwise (for example, it is OK to include an 1356 informative reference to a previous version of a specification to 1357 help explain a feature included for backward compatibility). Be 1358 sure citations for all imported modules are present somewhere in 1359 the document text (outside the YANG module). 1361 o License -- verify that the draft contains the Simplified BSD 1362 License in each YANG module or submodule. Some guidelines related 1363 to this requirement are described in Section 4.1. Make sure that 1364 the correct year is used in all copyright dates. Use the approved 1365 text from the latest Trust Legal Provisions (TLP) document, which 1366 can be found at: 1368 http://trustee.ietf.org/license-info/ 1370 o Other Issues -- check for any issues mentioned in 1371 http://www.ietf.org/id-info/checklist.html that are not covered 1372 elsewhere. 1374 o Technical Content -- review the actual technical content for 1375 compliance with the guidelines in this document. The use of a 1376 YANG module compiler is recommended when checking for syntax 1377 errors. A list of freely available tools and other information 1378 can be found at: 1380 http://trac.tools.ietf.org/wg/netconf/trac/wiki 1382 Checking for correct syntax, however, is only part of the job. 1383 It is just as important to actually read the YANG module document 1384 from the point of view of a potential implementor. It is 1385 particularly important to check that description statements are 1386 sufficiently clear and unambiguous to allow interoperable 1387 implementations to be created. 1389 Appendix C. YANG Module Template 1391 file "ietf-template@2010-05-18.yang" 1393 module ietf-template { 1395 // replace this string with a unique namespace URN value 1396 namespace 1397 "urn:ietf:params:xml:ns:yang:ietf-template"; 1399 // replace this string, and try to pick a unique prefix 1400 prefix "temp"; 1402 // import statements here: e.g., 1403 // import ietf-yang-types { prefix yang; } 1404 // import ietf-inet-types { prefix inet; } 1406 // identify the IETF working group if applicable 1407 organization 1408 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 1410 // update this contact statement with your info 1411 contact 1412 "WG Web: 1413 WG List: 1415 WG Chair: your-WG-chair 1416 1418 Editor: your-name 1419 "; 1421 // replace the first sentence in this description statement. 1422 // replace the copyright notice with the most recent 1423 // version, if it has been updated since the publication 1424 // of this document 1425 description 1426 "This module defines a template for other YANG modules. 1428 Copyright (c) IETF Trust and the persons 1429 identified as authors of the code. All rights reserved. 1431 Redistribution and use in source and binary forms, with or 1432 without modification, is permitted pursuant to, and subject 1433 to the license terms contained in, the Simplified BSD License 1434 set forth in Section 4.c of the IETF Trust's Legal Provisions 1435 Relating to IETF Documents 1436 (http://trustee.ietf.org/license-info). 1438 This version of this YANG module is part of RFC XXXX; see 1439 the RFC itself for full legal notices."; 1441 // RFC Ed.: replace XXXX with actual RFC number and remove 1442 // this note 1444 reference "RFC XXXX"; 1446 // RFC Ed.: remove this note 1447 // Note: extracted from RFC XXXX 1449 // replace '2010-05-18' with the module publication date 1450 // The format is (year-month-day) 1451 revision "2010-05-18" { 1452 description 1453 "Initial version"; 1454 } 1456 // extension statements 1458 // feature statements 1460 // identity statements 1462 // typedef statements 1464 // grouping statements 1466 // data definition statements 1468 // augment statements 1470 // rpc statements 1472 // notification statements 1474 // DO NOT put deviation statements in a published module 1476 } 1478 1480 Author's Address 1482 Andy Bierman 1483 YumaWorks 1485 Email: andy@yumaworks.com