idnits 2.17.1 draft-ietf-netmod-rfc6087bis-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2015) is 3209 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 319, but not defined == Missing Reference: 'RFC6242' is mentioned on line 1723, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-06 ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 6087 (Obsoleted by RFC 8407) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track July 6, 2015 5 Expires: January 7, 2016 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-04 10 Abstract 12 This memo provides guidelines for authors and reviewers of Standards 13 Track specifications containing YANG data model modules. Applicable 14 portions may be used as a basis for reviews of other YANG data model 15 documents. Recommendations and procedures are defined, which are 16 intended to increase interoperability and usability of Network 17 Configuration Protocol (NETCONF) implementations that utilize YANG 18 data model modules. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 7, 2016. 37 Copyright Notice 39 Copyright (c) 2015 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 57 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 58 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 61 4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 62 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 63 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 64 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 65 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 66 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 67 4.6. Security Considerations Section . . . . . . . . . . . . . 10 68 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 69 4.7.1. Documents that Create a New Namespace . . . . . . . . 11 70 4.7.2. Documents that Extend an Existing Namespace . . . . . 11 71 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 11 72 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 73 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 12 74 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 75 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 76 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15 78 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15 79 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 16 81 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 17 82 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 17 83 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 18 84 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 18 85 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 19 86 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 20 87 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 20 88 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 21 89 5.8. Module Header, Meta, and Revision Statements . . . . . . . 22 90 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 23 91 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 24 92 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 24 93 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 25 94 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 25 95 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26 97 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27 98 5.13. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28 99 5.14. Operation Definitions . . . . . . . . . . . . . . . . . . 29 100 5.15. Notification Definitions . . . . . . . . . . . . . . . . . 29 101 5.16. Feature Definitions . . . . . . . . . . . . . . . . . . . 30 102 5.17. Augment Statements . . . . . . . . . . . . . . . . . . . . 31 103 5.17.1. Conditional Augment Statements . . . . . . . . . . . . 31 104 5.17.2. Conditionally Mandatory Data Definition Statements . . 31 105 5.18. Deviation Statements . . . . . . . . . . . . . . . . . . . 33 106 5.19. Data Correlation . . . . . . . . . . . . . . . . . . . . . 33 107 5.20. Operational State . . . . . . . . . . . . . . . . . . . . 34 108 5.21. Performance Considerations . . . . . . . . . . . . . . . . 37 109 5.22. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 37 110 5.22.1. Importing Multiple Revisions . . . . . . . . . . . . . 37 111 5.22.2. Using Feature Logic . . . . . . . . . . . . . . . . . 38 112 5.22.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 38 113 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 114 7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 115 7.1. Security Considerations Section Template . . . . . . . . . 40 116 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 117 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 43 118 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 119 10.1. Normative References . . . . . . . . . . . . . . . . . . . 44 120 10.2. Informative References . . . . . . . . . . . . . . . . . . 44 121 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 46 122 A.1. 03 ot 04 . . . . . . . . . . . . . . . . . . . . . . . . . 46 123 A.2. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 46 124 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 46 125 A.4. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 46 126 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 48 127 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 50 128 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 52 130 1. Introduction 132 The standardization of network configuration interfaces for use with 133 the Network Configuration Protocol [RFC6241] requires a modular set 134 of data models, which can be reused and extended over time. 136 This document defines a set of usage guidelines for Standards Track 137 documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG 138 is used to define the data structures, protocol operations, and 139 notification content used within a NETCONF server. A server that 140 supports a particular YANG module will support client NETCONF 141 operation requests, as indicated by the specific content defined in 142 the YANG module. 144 This document is similar to the Structure of Management Information 145 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 146 and structure. However, since that document was written a decade 147 after SMIv2 modules had been in use, it was published as a 'Best 148 Current Practice' (BCP). This document is not a BCP, but rather an 149 informational reference, intended to promote consistency in documents 150 containing YANG modules. 152 Many YANG constructs are defined as optional to use, such as the 153 description statement. However, in order to maximize 154 interoperability of NETCONF implementations utilizing YANG data 155 models, it is desirable to define a set of usage guidelines that may 156 require a higher level of compliance than the minimum level defined 157 in the YANG specification. 159 In addition, YANG allows constructs such as infinite length 160 identifiers and string values, or top-level mandatory nodes, that a 161 compliant server is not required to support. Only constructs that 162 all servers are required to support can be used in IETF YANG modules. 164 This document defines usage guidelines related to the NETCONF 165 operations layer and NETCONF content layer, as defined in [RFC6241]. 166 These guidelines are intended to be used by authors and reviewers to 167 improve the readability and interoperability of published YANG data 168 models. 170 Note that this document is not a YANG tutorial and the reader is 171 expected to know the YANG data modeling language before using this 172 document. 174 2. Terminology 176 2.1. Requirements Notation 178 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 179 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 180 document are to be interpreted as described in [RFC2119]. 182 RFC 2119 language is used here to express the views of the NETMOD 183 working group regarding content for YANG modules. YANG modules 184 complying with this document will treat the RFC 2119 terminology as 185 if it were describing best current practices. 187 2.2. NETCONF Terms 189 The following terms are defined in [RFC6241] and are not redefined 190 here: 192 o capabilities 194 o client 196 o operation 198 o server 200 2.3. YANG Terms 202 The following terms are defined in [I-D.ietf-netmod-rfc6020bis] and 203 are not redefined here: 205 o data node 207 o module 209 o namespace 211 o submodule 213 o version 215 o YANG 217 o YIN 219 Note that the term 'module' may be used as a generic term for a YANG 220 module or submodule. When describing properties that are specific to 221 submodules, the term 'submodule' is used instead. 223 2.4. Terms 225 The following terms are used throughout this document: 227 o published: A stable release of a module or submodule, usually 228 contained in an RFC. 230 o unpublished: An unstable release of a module or submodule, usually 231 contained in an Internet-Draft. 233 3. YANG Tree Diagrams 235 YANG tree diagrams provide a concise representation of a YANG module 236 to help readers understand the module structure. 238 The meaning of the symbols in YANG tree diagrams is as follows: 240 o Brackets "[" and "]" enclose list keys. 242 o Abbreviations before data node names: "rw" means configuration 243 (read-write) and "ro" state data (read-only). 245 o Symbols after data node names: "?" means an optional node, "!" 246 means a presence container, and "*" denotes a list and leaf-list. 248 o Parentheses enclose choice and case nodes, and case nodes are also 249 marked with a colon (":"). 251 o Ellipsis ("...") stands for contents of subtrees that are not 252 shown. 254 4. General Documentation Guidelines 256 YANG data model modules under review are likely to be contained in 257 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 258 followed. The RFC Editor provides guidelines for authors of RFCs, 259 which are first published as Internet-Drafts. These guidelines 260 should be followed and are defined in [RFC2223] and updated in 261 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 263 The following sections MUST be present in an Internet-Draft 264 containing a module: 266 o Narrative sections 268 o Definitions section 270 o Security Considerations section 272 o IANA Considerations section 274 o References section 276 4.1. Module Copyright 278 The module description statement MUST contain a reference to the 279 latest approved IETF Trust Copyright statement, which is available 280 online at: 282 http://trustee.ietf.org/license-info/ 284 Each YANG module or submodule contained within an Internet-Draft or 285 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 287 component. 289 The "" tag SHOULD be followed by a string identifying 290 the file name specified in Section 5.2 of 291 [I-D.ietf-netmod-rfc6020bis]. The following example is for the 292 '2010-01-18' revision of the 'ietf-foo' module: 294 file "ietf-foo@2010-01-18.yang" 295 module ietf-foo { 296 // ... 297 revision 2010-01-18 { 298 description "Latest revision"; 299 reference "RFC XXXX"; 300 } 301 // ... 302 } 303 305 Note that this convention MUST NOT be used for example modules or 306 module fragments. 308 4.2. Terminology Section 310 A terminology section MUST be present if any terms are defined in the 311 document or if any terms are imported from other documents. 313 If YANG tree diagrams are used, then a sub-section explaining the 314 YANG tree diagram syntax MUST be present, containing the following 315 text: 317 A simplified graphical representation of the data model is used in 318 this document. The meaning of the symbols in these diagrams is 319 defined in [RFCXXXX]. 321 -- RFC Editor: Replace XXXX with RFC number and remove note 323 4.3. Tree Diagrams 325 YANG tree diagrams provide a concise representation of a YANG module, 326 and SHOULD be included to help readers understand YANG module 327 structure. Tree diagrams MAY be split into sections to correspond to 328 document structure. 330 The following example shows a simple YANG tree diagram: 332 +--rw top-level-config-container 333 | +--rw config-list* [key-name] 334 | +--rw key-name string 335 | +--rw optional-parm? string 336 | +--rw mandatory-parm identityref 337 | +--ro read-only-leaf string 338 +--ro top-level-nonconfig-container 339 +--ro nonconfig-list* [name] 340 +--ro name string 341 +--ro type string 343 4.4. Narrative Sections 345 The narrative part MUST include an overview section that describes 346 the scope and field of application of the module(s) defined by the 347 specification and that specifies the relationship (if any) of these 348 modules to other standards, particularly to standards containing 349 other YANG modules. The narrative part SHOULD include one or more 350 sections to briefly describe the structure of the modules defined in 351 the specification. 353 If the module(s) defined by the specification imports definitions 354 from other modules (except for those defined in the 355 [I-D.ietf-netmod-rfc6020bis] or [RFC6991] documents), or are always 356 implemented in conjunction with other modules, then those facts MUST 357 be noted in the overview section, as MUST be noted any special 358 interpretations of definitions in other modules. 360 4.5. Definitions Section 362 This section contains the module(s) defined by the specification. 363 These modules MUST be written using the YANG syntax defined in 364 [I-D.ietf-netmod-rfc6020bis]. A YIN syntax version of the module MAY 365 also be present in the document. There MAY also be other types of 366 modules present in the document, such as SMIv2, which are not 367 affected by these guidelines. 369 See Section 5 for guidelines on YANG usage. 371 4.6. Security Considerations Section 373 Each specification that defines one or more modules MUST contain a 374 section that discusses security considerations relevant to those 375 modules. 377 This section MUST be patterned after the latest approved template 378 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 379 yang-security-guidelines). Section 7.1 contains the security 380 considerations template dated 2013-05-08. Authors MUST check the 381 webpage at the URL listed above in case there is a more recent 382 version available. 384 In particular: 386 o Writable data nodes that could be especially disruptive if abused 387 MUST be explicitly listed by name and the associated security 388 risks MUST be explained. 390 o Readable data nodes that contain especially sensitive information 391 or that raise significant privacy concerns MUST be explicitly 392 listed by name and the reasons for the sensitivity/privacy 393 concerns MUST be explained. 395 o Operations (i.e., YANG 'rpc' statements) that are potentially 396 harmful to system behavior or that raise significant privacy 397 concerns MUST be explicitly listed by name and the reasons for the 398 sensitivity/privacy concerns MUST be explained. 400 4.7. IANA Considerations Section 402 In order to comply with IESG policy as set forth in 403 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 404 is submitted to the IESG for publication MUST contain an IANA 405 Considerations section. The requirements for this section vary 406 depending on what actions are required of the IANA. If there are no 407 IANA considerations applicable to the document, then the IANA 408 Considerations section stating that there are no actions is removed 409 by the RFC Editor before publication. Refer to the guidelines in 410 [RFC5226] for more details. 412 4.7.1. Documents that Create a New Namespace 414 If an Internet-Draft defines a new namespace that is to be 415 administered by the IANA, then the document MUST include an IANA 416 Considerations section that specifies how the namespace is to be 417 administered. 419 Specifically, if any YANG module namespace statement value contained 420 in the document is not already registered with IANA, then a new YANG 421 Namespace registry entry MUST be requested from the IANA. The 422 [I-D.ietf-netmod-rfc6020bis] specification includes the procedure for 423 this purpose in its IANA Considerations section. 425 4.7.2. Documents that Extend an Existing Namespace 427 It is possible to extend an existing namespace using a YANG submodule 428 that belongs to an existing module already administered by IANA. In 429 this case, the document containing the main module MUST be updated to 430 use the latest revision of the submodule. 432 4.8. Reference Sections 434 For every import or include statement that appears in a module 435 contained in the specification, which identifies a module in a 436 separate document, a corresponding normative reference to that 437 document MUST appear in the Normative References section. The 438 reference MUST correspond to the specific module version actually 439 used within the specification. 441 For every normative reference statement that appears in a module 442 contained in the specification, which identifies a separate document, 443 a corresponding normative reference to that document SHOULD appear in 444 the Normative References section. The reference SHOULD correspond to 445 the specific document version actually used within the specification. 446 If the reference statement identifies an informative reference, which 447 identifies a separate document, a corresponding informative reference 448 to that document MAY appear in the Informative References section. 450 4.9. Validation Tools 452 All modules need to be validated before submission in an Internet 453 Draft. The 'pyang' YANG compiler is freely available from github: 455 https://github.com/mbj4668/pyang 457 If the 'pyang' compiler is used, then the "--ietf" command line 458 option SHOULD be used to identify any IETF guideline issues. 460 4.10. Module Extraction Tools 462 A version of 'rfcstrip' is available which will extract YANG modules 463 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 464 YANG module extraction is freely available: 466 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 468 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 470 can be extracted correctly. 472 5. YANG Usage Guidelines 474 In general, modules in IETF Standards Track specifications MUST 475 comply with all syntactic and semantic requirements of YANG 476 [I-D.ietf-netmod-rfc6020bis]. The guidelines in this section are 477 intended to supplement the YANG specification, which is intended to 478 define a minimum set of conformance requirements. 480 In order to promote interoperability and establish a set of practices 481 based on previous experience, the following sections establish usage 482 guidelines for specific YANG constructs. 484 Only guidelines that clarify or restrict the minimum conformance 485 requirements are included here. 487 5.1. Module Naming Conventions 489 Modules contained in Standards Track documents SHOULD be named 490 according to the guidelines in the IANA Considerations section of 491 [I-D.ietf-netmod-rfc6020bis]. 493 A distinctive word or acronym (e.g., protocol name or working group 494 acronym) SHOULD be used in the module name. If new definitions are 495 being defined to extend one or more existing modules, then the same 496 word or acronym should be reused, instead of creating a new one. 498 All published module names MUST be unique. For a YANG module 499 published in an RFC, this uniqueness is guaranteed by IANA. For 500 unpublished modules, the authors need to check that no other work in 501 progress is using the same module name. 503 Once a module name is published, it MUST NOT be reused, even if the 504 RFC containing the module is reclassified to 'Historic' status. 506 5.2. Prefixes 508 All YANG definitions are scoped by the module containing the 509 definition being referenced. This allows definitions from multiple 510 modules to be used, even if the names are not unique. In the example 511 below, the identifier "foo" is used in all 3 modules: 513 module example-foo { 514 namespace "http://example.com/ns/foo"; 515 prefix f; 517 container foo; 518 } 520 module example-bar { 521 namespace "http://example.com/ns/bar"; 522 prefix b; 524 typedef foo { type uint32; } 525 } 527 module example-one { 528 namespace "http://example.com/ns/one"; 529 prefix one; 530 import example-foo { prefix f; } 531 import example-bar { prefix b; } 533 augment "/f:foo" { 534 leaf foo { type b:foo; } 535 } 536 } 538 YANG defines the following rules for prefix usage: 540 o Prefixes are never allowed for built in data types and YANG 541 keywords. 543 o A prefix MUST be used for any external statement (i.e., a 544 statement defined with the YANG "extension" statement) 546 o The proper module prefix MUST be used for all identifiers imported 547 from other modules 549 o The proper module prefix MUST be used for all identifiers included 550 from a submodule. 552 The following guidelines apply to prefix usage of the current (local) 553 module: 555 o The local module prefix SHOULD be used instead of no prefix in all 556 path expressions. 558 o The local module prefix MUST be used instead of no prefix in all 559 "default" statements for an "identityref" or "instance-identifier" 560 data type 562 o The lcaol module prefix MAY be used for references to typedefs, 563 groupings, extensions, features, and identities defined in the 564 module. 566 5.3. Identifiers 568 Identifiers for all YANG identifiers in published modules MUST be 569 between 1 and 64 characters in length. These include any construct 570 specified as an 'identifier-arg-str' token in the ABNF in Section 13 571 of [I-D.ietf-netmod-rfc6020bis]. 573 5.3.1. Identifier Naming Conventions 575 Identifiers SHOULD follow a consistent naming pattern throughout the 576 module. Only lower-case letters, numbers, and dashes SHOULD be used 577 in identifier names. Upper-case characters and the underscore 578 character MAY be used if the identifier represents a well-known value 579 that uses these characters. 581 Identifiers SHOULD include complete words and/or well-known acronyms 582 or abbreviations. Child nodes within a container or list SHOULD NOT 583 replicate the parent identifier. YANG identifiers are hierarchical 584 and are only meant to be unique within the the set of sibling nodes 585 defined in the same module namespace. 587 It is permissible to use common identifiers such as "name" or "id" in 588 data definition statements, especially if these data nodes share a 589 common data type. 591 Identifiers SHOULD NOT carry any special semantics that identify data 592 modelling properties. Only YANG statements and YANG extension 593 statements are designed to convey machine readable data modelling 594 properties. For example, naming an object "config" or "state" does 595 not change whether it is configuration data or state data. Only 596 defined YANG statements or YANG extension statements can be used to 597 assign semantics in a machine readable format in YANG. 599 5.4. Defaults 601 In general, it is suggested that substatements containing very common 602 default values SHOULD NOT be present. The following substatements 603 are commonly used with the default value, which would make the module 604 difficult to read if used everywhere they are allowed. 606 +--------------+---------------+ 607 | Statement | Default Value | 608 +--------------+---------------+ 609 | config | true | 610 | mandatory | false | 611 | max-elements | unbounded | 612 | min-elements | 0 | 613 | ordered-by | system | 614 | status | current | 615 | yin-element | false | 616 +--------------+---------------+ 618 Statement Defaults 620 5.5. Conditional Statements 622 A module may be conceptually partitioned in several ways, using the 623 'if-feature' and/or 'when' statements. 625 Data model designers need to carefully consider all modularity 626 aspects, including the use of YANG conditional statements. 628 If a data definition is optional, depending on server support for a 629 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 630 be defined to indicate that the NETCONF capability is supported 631 within the data model. 633 If any notification data, or any data definition, for a non- 634 configuration data node is not mandatory, then the server may or may 635 not be required to return an instance of this data node. If any 636 conditional requirements exist for returning the data node in a 637 notification payload or retrieval request, they MUST be documented 638 somewhere. For example, a 'when' or 'if-feature' statement could 639 apply to the data node, or the conditional requirements could be 640 explained in a 'description' statement within the data node or one of 641 its ancestors (if any). 643 If any 'if-feature' statements apply to a list node, then the same 644 'if-feature' statements MUST apply to any key leaf nodes for the 645 list. There MUST NOT be any 'if-feature' statements applied to any 646 key leaf that do not also apply to the parent list node. 648 There SHOULD NOT be any 'when' statements applied to a key leaf node. 649 It is possible that a 'when' statement for an ancestor node of a key 650 leaf will have the exact node-set result as the key leaf. In such a 651 case, the 'when' statement for the key leaf is redundant and SHOULD 652 be avoided. 654 5.6. XPath Usage 656 This section describes guidelines for using the XML Path Language 657 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 659 5.6.1. XPath Evaluation Contexts 661 YANG defines 5 separate contexts for evaluation of XPath statements: 663 1) The "running" datastore: collection of all YANG configuration data 664 nodes. The document root is the conceptual container, (e.g., 665 "config" in the "edit-config" operation), which is the parent of all 666 top-level data definition statements with a "config" statement value 667 of "true". 669 2) State data + the "running" datastore: collection of all YANG data 670 nodes. The document root is the conceptual container, parent of all 671 top-level data definition statements. 673 3) Notification: an event notification document. The document root 674 is the notification element. 676 4) RPC Input: The document root is the conceptual "input" node, which 677 is the parent of all RPC input parameter definitions. 679 5) RPC Output: The document root is the conceptual "output" node, 680 which is the parent of all RPC output parameter definitions. 682 Note that these XPath contexts cannot be mixed. For example, a 683 "when" statement in a notification context cannot reference 684 configuration data. 686 notification foo { 687 leaf mtu { 688 // NOT OK because when-stmt context is this notification 689 when "/if:interfaces/if:interface[name='eth0']"; 690 type leafref { 691 // OK because path-stmt has a different context 692 path "/if:interfaces/if:interface/if:mtu"; 693 } 694 } 695 } 697 It is especially important to consider the XPath evaluation context 698 for XPath expressions defined in groupings. An XPath expression 699 defined in a grouping may not be portable, meaning it cannot be used 700 in multiple contexts and produce proper results. 702 If the XPath expressions defined in a grouping are intended for a 703 particular context, then this context SHOULD be identified in the 704 "description" statement for the grouping. 706 5.6.2. Function Library 708 The 'position' and 'last' functions SHOULD NOT be used. This applies 709 to implicit use of the 'position' function as well (e.g., 710 '//chapter[42]'). A server is only required to maintain the relative 711 XML document order of all instances of a particular user-ordered list 712 or leaf-list. The 'position' and 'last' functions MAY be used if 713 they are evaluated in a context where the context node is a user- 714 ordered 'list' or 'leaf-list'. 716 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 717 present in YANG documents so this function has no meaning. The YANG 718 compiler SHOULD return an empty string for this function. 720 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 721 Expanded names in XPath are different than YANG. A specific 722 canonical representation of a YANG expanded name does not exist. 724 The 'lang' function SHOULD NOT be used. This function does not apply 725 to YANG because there is no 'lang' attribute set with the document. 726 The YANG compiler SHOULD return 'false' for this function. 728 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 729 functions SHOULD NOT be used if the argument is a node-set. If so, 730 the function result will be determined by the document order of the 731 node-set. Since this order can be different on each server, the 732 function results can also be different. Any function call that 733 implicitly converts a node-set to a string will also have this issue. 735 The 'local-name' function SHOULD NOT be used to reference local names 736 outside of the YANG module defining the must or when expression 737 containing the 'local-name' function. Example of a local-name 738 function that should not be used: 740 /*[local-name()='foo'] 742 5.6.3. Axes 744 The 'attribute' and 'namespace' axes are not supported in YANG, and 745 MAY be empty in a NETCONF server implementation. 747 The 'preceding', and 'following' axes SHOULD NOT be used. These 748 constructs rely on XML document order within a NETCONF server 749 configuration database, which may not be supported consistently or 750 produce reliable results across implementations. Predicate 751 expressions based on static node properties (e.g., element name or 752 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 753 'preceding' and 'following' axes MAY be used if document order is not 754 relevant to the outcome of the expression (e.g., check for global 755 uniqueness of a parameter value). 757 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 758 however they MAY be used if document order is not relevant to the 759 outcome of the expression. 761 A server is only required to maintain the relative XML document order 762 of all instances of a particular user-ordered list or leaf-list. The 763 'preceding-sibling' and 'following-sibling' axes MAY be used if they 764 are evaluated in a context where the context node is a user-ordered 765 'list' or 'leaf-list'. 767 5.6.4. Types 769 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 770 be used within numeric or boolean expressions. There are boundary 771 conditions in which the translation from the YANG 64-bit type to an 772 XPath number can cause incorrect results. Specifically, an XPath 773 'double' precision floating point number cannot represent very large 774 positive or negative 64-bit numbers because it only provides a total 775 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 776 used in numeric expressions if the value can be represented with no 777 more than 53 bits of precision. 779 Data modelers need to be careful not to confuse the YANG value space 780 and the XPath value space. The data types are not the same in both, 781 and conversion between YANG and XPath data types SHOULD be considered 782 carefully. 784 Explicit XPath data type conversions MAY be used (e.g., 'string', 785 'boolean', or 'number' functions), instead of implicit XPath data 786 type conversions. 788 XPath expressions that contain a literal value representing a YANG 789 identity SHOULD always include the declared prefix of the module 790 where the identity is defined. 792 XPath expressions for 'when' statements SHOULD NOT reference the 793 context node or any descendant nodes of the context node. They MAY 794 reference descendant nodes if the 'when' statement is contained 795 within an 'augment' statement, and the referenced nodes are not 796 defined within the 'augment' statement. 798 Example: 800 augment "/rt:active-route/rt:input/rt:destination-address" { 801 when "rt:address-family='v4ur:ipv4-unicast'" { 802 description 803 "This augment is valid only for IPv4 unicast."; 804 } 805 // nodes defined here within the augment-stmt 806 // cannot be referenced in the when-stmt 807 } 809 5.6.5. Wildcards 811 It is possible to construct XPath expressions that will evaluate 812 differently when combined with several modules within a server 813 implementation, then when evaluated within the single module. This 814 is due to augmenting nodes from other modules. 816 Wildcard expansion is done within a server against all the nodes from 817 all namespaces, so it is possible for a 'must' or 'when' expression 818 that uses the '*' operator will always evaluate to false if processed 819 within a single YANG module. In such cases, the 'description' 820 statement SHOULD clarify that augmenting objects are expected to 821 match the wildcard expansion. 823 when /foo/services/*/active { 824 description 825 "No services directly defined in this module. 826 Matches objects that have augmented the services container."; 827 } 829 5.6.6. Boolean Expressions 831 The YANG "must" and "when" statements use an XPath boolean expression 832 to define the test condition for the statement. It is important to 833 specify these expressions in a way that will not cause inadvertent 834 changes in the result if the objects referenced in the expression are 835 updated in future revisions of the module. 837 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 838 to "one" or "three": 840 leaf foo1 { 841 type enumeration { 842 enum one; 843 enum two; 844 enum three; 845 } 846 } 848 leaf foo2 { 849 // INCORRECT 850 must "/f:foo1 != 'two'"; 851 type string; 852 } 854 leaf foo2 { 855 // CORRECT 856 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 857 type string; 858 } 860 In the next revision of the module, leaf "foo1" is extended with a 861 nem enum named "four": 863 leaf foo1 { 864 type enumeration { 865 enum one; 866 enum two; 867 enum three; 868 enum four; 869 } 870 } 872 Now the first XPath expression will allow the enum "four" to be 873 accepted in addition to the "one" and "three" enum values. 875 5.7. Lifecycle Management 877 The status statement MUST be present if its value is 'deprecated' or 878 'obsolete'. The status SHOULD NOT be changed from 'current' directly 879 to 'obsolete'. An object SHOULD be available for at least one year 880 with 'deprecated' status before it is changed to 'obsolete'. 882 The module or submodule name MUST NOT be changed, once the document 883 containing the module or submodule is published. 885 The module namespace URI value MUST NOT be changed, once the document 886 containing the module is published. 888 The revision-date substatement within the imports statement SHOULD be 889 present if any groupings are used from the external module. 891 The revision-date substatement within the include statement SHOULD be 892 present if any groupings are used from the external submodule. 894 If submodules are used, then the document containing the main module 895 MUST be updated so that the main module revision date is equal or 896 more recent than the revision date of any submodule that is (directly 897 or indirectly) included by the main module. 899 5.8. Module Header, Meta, and Revision Statements 901 For published modules, the namespace MUST be a globally unique URI, 902 as defined in [RFC3986]. This value is usually assigned by the IANA. 904 The organization statement MUST be present. If the module is 905 contained in a document intended for Standards Track status, then the 906 organization SHOULD be the IETF working group chartered to write the 907 document. 909 The contact statement MUST be present. If the module is contained in 910 a document intended for Standards Track status, then the working 911 group web and mailing information MUST be present, and the main 912 document author or editor contact information SHOULD be present. If 913 additional authors or editors exist, their contact information MAY be 914 present. In addition, the Area Director and other contact 915 information MAY be present. 917 The description statement MUST be present. The appropriate IETF 918 Trust Copyright text MUST be present, as described in Section 4.1. 920 If the module relies on information contained in other documents, 921 which are not the same documents implied by the import statements 922 present in the module, then these documents MUST be identified in the 923 reference statement. 925 A revision statement MUST be present for each published version of 926 the module. The revision statement MUST have a reference 927 substatement. It MUST identify the published document that contains 928 the module. Modules are often extracted from their original 929 documents, and it is useful for developers and operators to know how 930 to find the original source document in a consistent manner. The 931 revision statement MAY have a description substatement. 933 Each new revision MUST include a revision date that is higher than 934 any other revision date in the module. The revision date does not 935 need to be updated if the module contents do not change in the new 936 document revision. 938 It is acceptable to reuse the same revision statement within 939 unpublished versions (i.e., Internet-Drafts), but the revision date 940 MUST be updated to a higher value each time the Internet-Draft is re- 941 posted. 943 5.9. Namespace Assignments 945 It is RECOMMENDED that only valid YANG modules be included in 946 documents, whether or not they are published yet. This allows: 948 o the module to compile correctly instead of generating disruptive 949 fatal errors. 951 o early implementors to use the modules without picking a random 952 value for the XML namespace. 954 o early interoperability testing since independent implementations 955 will use the same XML namespace value. 957 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 958 provided for the namespace statement in a YANG module. A value 959 SHOULD be selected that is not likely to collide with other YANG 960 namespaces. Standard module names, prefixes, and URI strings already 961 listed in the YANG Module Registry MUST NOT be used. 963 A standard namespace statement value SHOULD have the following form: 965 : 967 The following URN prefix string SHOULD be used for published and 968 unpublished YANG modules: 970 urn:ietf:params:xml:ns:yang: 972 The following example URNs would be valid namespace statement values 973 for Standards Track modules: 975 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 977 urn:ietf:params:xml:ns:yang:ietf-netconf-state 979 urn:ietf:params:xml:ns:yang:ietf-netconf 981 Note that a different URN prefix string SHOULD be used for non- 982 Standards-Track modules. The string SHOULD be selected according to 983 the guidelines in [I-D.ietf-netmod-rfc6020bis]. 985 The following examples are for non-Standards-Track modules. The 986 domain "example.com" SHOULD be used in all namespace URIs for example 987 modules. 989 http://example.com/ns/example-interfaces 991 http://example.com/ns/example-system 993 5.10. Top-Level Data Definitions 995 The top-level data organization SHOULD be considered carefully, in 996 advance. Data model designers need to consider how the functionality 997 for a given protocol or protocol family will grow over time. 999 The separation of configuration data and operational state SHOULD be 1000 considered carefully. It is often useful to define separate top- 1001 level containers for configuration and non-configuration data. 1003 The number of top-level data nodes within a module SHOULD be 1004 minimized. It is often useful to retrieve related information within 1005 a single subtree. If data is too distributed, is becomes difficult 1006 to retrieve all at once. 1008 The names and data organization SHOULD reflect persistent 1009 information, such as the name of a protocol. The name of the working 1010 group SHOULD NOT be used because this may change over time. 1012 A mandatory database data definition is defined as a node that a 1013 client must provide for the database to be valid. The server is not 1014 required to provide a value. 1016 Top-level database data definitions MUST NOT be mandatory. If a 1017 mandatory node appears at the top level, it will immediately cause 1018 the database to be invalid. This can occur when the server boots or 1019 when a module is loaded dynamically at runtime. 1021 5.11. Data Types 1023 Selection of an appropriate data type (i.e., built-in type, existing 1024 derived type, or new derived type) is very subjective, and therefore 1025 few requirements can be specified on that subject. 1027 Data model designers SHOULD use the most appropriate built-in data 1028 type for the particular application. 1030 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1031 'int64') SHOULD NOT be used unless negative values are allowed for 1032 the desired semantics. 1034 5.11.1. Fixed Value Extensibility 1036 If the set of values is fixed and the data type contents are 1037 controlled by a single naming authority, then an enumeration data 1038 type SHOULD be used. 1040 leaf foo { 1041 type enumeration { 1042 enum one; 1043 enum two; 1044 } 1045 } 1047 If extensibility of enumerated values is required, then the 1048 'identityref' data type SHOULD be used instead of an enumeration or 1049 other built-in type. 1051 identity foo-type { 1052 description "Base for the extensible type"; 1053 } 1055 identity one { 1056 base f:foo-type; 1057 } 1058 identity two { 1059 base f:foo-type; 1060 } 1062 leaf foo { 1063 type identityref { 1064 base f:foo-type; 1065 } 1066 } 1068 Note that any module can declare an identity with base "foo-type" 1069 that is valid for the "foo" leaf. Identityref values are considered 1070 to be qualified names. 1072 5.11.2. Patterns and Ranges 1074 For string data types, if a machine-readable pattern can be defined 1075 for the desired semantics, then one or more pattern statements SHOULD 1076 be present. A single quoted string SHOULD be used to specify the 1077 pattern, since a double-quoted string can modify the content. 1079 The following typedef from [RFC6991] demonstrates the proper use of 1080 the "pattern" statement: 1082 typedef ipv4-address-no-zone { 1083 type inet:ipv4-address { 1084 pattern '[0-9\.]*'; 1085 } 1086 ... 1087 } 1089 For string data types, if the length of the string is required to be 1090 bounded in all implementations, then a length statement MUST be 1091 present. 1093 The following typedef from [RFC6991] demonstrates the proper use of 1094 the "length" statement: 1096 typedef yang-identifier { 1097 type string { 1098 length "1..max"; 1099 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1100 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1101 } 1102 ... 1103 } 1105 For numeric data types, if the values allowed by the intended 1106 semantics are different than those allowed by the unbounded intrinsic 1107 data type (e.g., 'int32'), then a range statement SHOULD be present. 1109 The following typedef from [RFC6991] demonstrates the proper use of 1110 the "range" statement: 1112 typedef dscp { 1113 type uint8 { 1114 range "0..63"; 1115 } 1116 ... 1117 } 1119 5.11.3. Enumerations and Bits 1121 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1122 or 'bit' SHOULD be documented. A separate description statement 1123 (within each 'enum' or 'bit' statement) SHOULD be present. 1125 leaf foo { 1126 // INCORRECT 1127 type enumeration { 1128 enum one; 1129 enum two; 1130 } 1131 description 1132 "The foo enum... 1133 one: The first enum 1134 two: The second enum"; 1135 } 1137 leaf foo { 1138 // CORRECT 1139 type enumeration { 1140 enum one { 1141 description "The first enum"; 1142 } 1143 enum two { 1144 description "The second enum"; 1145 } 1146 } 1147 description 1148 "The foo enum... "; 1149 } 1151 5.12. Reusable Type Definitions 1153 If an appropriate derived type exists in any standard module, such as 1154 [RFC6991], then it SHOULD be used instead of defining a new derived 1155 type. 1157 If an appropriate units identifier can be associated with the desired 1158 semantics, then a units statement SHOULD be present. 1160 If an appropriate default value can be associated with the desired 1161 semantics, then a default statement SHOULD be present. 1163 If a significant number of derived types are defined, and it is 1164 anticipated that these data types will be reused by multiple modules, 1165 then these derived types SHOULD be contained in a separate module or 1166 submodule, to allow easier reuse without unnecessary coupling. 1168 The description statement MUST be present. 1170 If the type definition semantics are defined in an external document 1171 (other than another YANG module indicated by an import statement), 1172 then the reference statement MUST be present. 1174 5.13. Data Definitions 1176 The description statement MUST be present in the following YANG 1177 statements: 1179 o anyxml 1181 o augment 1183 o choice 1185 o container 1187 o extension 1189 o feature 1191 o grouping 1193 o identity 1195 o leaf 1197 o leaf-list 1199 o list 1201 o notification 1203 o rpc 1205 o typedef 1207 If the data definition semantics are defined in an external document, 1208 (other than another YANG module indicated by an import statement), 1209 then a reference statement MUST be present. 1211 The 'anyxml' construct may be useful to represent an HTML banner 1212 containing markup elements, such as '<b>' and '</b>', and 1213 MAY be used in such cases. However, this construct SHOULD NOT be 1214 used if other YANG data node types can be used instead to represent 1215 the desired syntax and semantics. 1217 It has been found that the 'anyxml' statement is not implemented 1218 consistently across all servers. It is possible that mixed mode XML 1219 will not be supported, or configuration anyxml nodes will not 1220 supported. 1222 If there are referential integrity constraints associated with the 1223 desired semantics that can be represented with XPath, then one or 1224 more 'must' statements SHOULD be present. 1226 For list and leaf-list data definitions, if the number of possible 1227 instances is required to be bounded for all implementations, then the 1228 max-elements statements SHOULD be present. 1230 If any 'must' or 'when' statements are used within the data 1231 definition, then the data definition description statement SHOULD 1232 describe the purpose of each one. 1234 5.14. Operation Definitions 1236 If the operation semantics are defined in an external document (other 1237 than another YANG module indicated by an import statement), then a 1238 reference statement MUST be present. 1240 If the operation impacts system behavior in some way, it SHOULD be 1241 mentioned in the description statement. 1243 If the operation is potentially harmful to system behavior in some 1244 way, it MUST be mentioned in the Security Considerations section of 1245 the document. 1247 5.15. Notification Definitions 1249 The description statement MUST be present. 1251 If the notification semantics are defined in an external document 1252 (other than another YANG module indicated by an import statement), 1253 then a reference statement MUST be present. 1255 If the notification refers to a specific resource instance, then this 1256 instance SHOULD be identified in the notification data. This is 1257 usually done by including 'leafref' leaf nodes with the key leaf 1258 values for the resource instance. For example: 1260 notification interface-up { 1261 description "Sent when an interface is activated."; 1262 leaf name { 1263 type leafref { 1264 path "/if:interfaces/if:interface/if:name"; 1265 } 1266 } 1267 } 1269 Note that there are no formal YANG statements to identify any data 1270 node resources associated with a notification. The description 1271 statement for the notification SHOULD specify if and how the 1272 notification identifies any data node resources associated with the 1273 specific event. 1275 5.16. Feature Definitions 1277 The YANG "feature" statement is used to define a label for a set of 1278 optional functionality within a module. The "if-feature" statement 1279 is used in the YANG statements associated with a feature. 1281 The set of YANG features available in a module should be considered 1282 carefully. The description-stmt within a feature-stmt MUST specify 1283 any interactions with other features. 1285 If there is a large set of objects associated with a YANG feature, 1286 then consider moving those objects to a separate module, instead of 1287 using a YANG feature. Note that the set of features within a module 1288 is easily discovered by the reader, but the set of related modules 1289 within the entire YANG library is not as easy to identity. Module 1290 names with a common prefix can help readers identity the set of 1291 related modules, but this assumes the reader will have discovered and 1292 installed all the relevant modules. 1294 Another consideration for deciding whether to create a new module or 1295 add a YANG feature is the stability of the module in question. It 1296 may be desirable to have a stable base module that is not changed 1297 frequently. If new functionality is placed in a separate module, 1298 then the base module does not need to be republished. If it is 1299 designed as a YANG feature then the module will need to be 1300 republished. 1302 If one feature requires implementation of another feature, then an 1303 "if-feature" statement SHOULD be used in the dependent "feature" 1304 statement. 1306 For example, feature2 requires implementation of feature1: 1308 feature feature1 { 1309 description "Some protocol feature"; 1310 } 1312 feature feature2 { 1313 if-feature "feature1"; 1314 description "Another protocol feature"; 1315 } 1317 5.17. Augment Statements 1319 The YANG "augment" statement is used to define a set of data 1320 definition statements that will be added as child nodes of a target 1321 data node. The module namespace for these data nodes will be the 1322 augmenting module, not the augmented module. 1324 A top-level "augment" statement SHOULD NOT be used if the target data 1325 node is in the same module or submodule as the evaluated "augment" 1326 statement. The data definition statements SHOULD be added inline 1327 instead. 1329 5.17.1. Conditional Augment Statements 1331 The "augment" statement is often used together with the "when" 1332 statement and/or "if-feature" statement to make the augmentation 1333 conditional on some portion of the data model. 1335 The following example from [RFC7223] shows how a conditional 1336 container called "ethernet" is added to the "interface" list only for 1337 entries of the type "ethernetCsmacd". 1339 augment "/if:interfaces/if:interface" { 1340 when "if:type = 'ianaift:ethernetCsmacd'"; 1342 container ethernet { 1343 leaf duplex { 1344 ... 1345 } 1346 } 1347 } 1349 5.17.2. Conditionally Mandatory Data Definition Statements 1351 YANG has very specific rules about how configuration data can be 1352 updated in new releases of a module. These rules allow an "old 1353 client" to continue interoperating with a "new server". 1355 If data nodes are added to an existing entry, the old client MUST NOT 1356 be required to provide any mandatory parameters that were not in the 1357 original module definition. 1359 It is possible to add conditional augment statements such that the 1360 old client would not know about the new condition, and would not 1361 specify the new condition. The conditional augment statement can 1362 contain mandatory objects only if the condition is false unless 1363 explicitly requested by the client. 1365 Only a conditional augment statement that uses the "when" statement 1366 form of condition can be used in this manner. The YANG features 1367 enabled on the server cannot be controlled by the client in any way, 1368 so it is not safe to add mandatory augmenting data nodes based on the 1369 "if-feature" statement. 1371 The XPath "when" statement condition MUST NOT reference data outside 1372 of target data node because the client does not have any control over 1373 this external data. 1375 In the following dummy example, it is OK to augment the "interface" 1376 entry with "mandatory-leaf" because the augmentation depends on 1377 support for "some-new-iftype". The old client does not know about 1378 this type so it would never select this type, and therefore not be 1379 adding a mandatory data node. 1381 module my-module { 1382 ... 1384 identity some-new-iftype { 1385 base iana:iana-interface-type; 1386 } 1388 augment "/if:interfaces/if:interface" { 1389 when "if:type = 'mymod:some-new-iftype'"; 1391 leaf mandatory-leaf { 1392 mandatory true; 1393 ... 1394 } 1395 } 1396 } 1398 Note that this practice is safe only for creating data resources. It 1399 is not safe for replacing or modifying resources if the client does 1400 not know about the new condition. The YANG data model MUST be 1401 packaged in a way that requires the client to be aware of the 1402 mandatory data nodes if it is aware of the condition for this data. 1403 In the example above, the "some-new-iftype" identity is defined in 1404 the same module as the "mandatory-leaf" data definition statement. 1406 This practice is not safe for identities defined in a common module 1407 such as "iana-if-type" because the client is not required to know 1408 about "my-module" just because it knows about the "iana-if-type" 1409 module. 1411 5.18. Deviation Statements 1413 The YANG "deviation" statement cannot appear in IETF YANG modules, 1414 but it can be useful for documenting server capabilities. Deviation 1415 statements are not reusable and typically not shared across all 1416 platforms. 1418 There are several reasons that deviations might be needed in an 1419 implementation, e.g., an object cannot be supported on all platforms, 1420 or feature delivery is done in multiple development phases. 1422 It is suggested that deviation statements be defined in separate 1423 modules from regular YANG definitions. This allows the deviations to 1424 be platform-specific and/or temporary. 1426 The "max-elements" statement is intended to describe an architectural 1427 limit to the number of list entries. It is not intended to describe 1428 platform limitations. It is better to use a "deviation" statement 1429 for the platforms that have a hard resource limit. 1431 Example documenting platform resource limits: 1433 Wrong: (max-elements in the list itself) 1435 container backups { 1436 list backup { 1437 ... 1438 max-elements 10; 1439 ... 1440 } 1441 } 1443 Correct: (max-elements in a deviation) 1445 deviation /bk:backups/bk:backup { 1446 deviate add { 1447 max-elements 10; 1448 } 1449 } 1451 5.19. Data Correlation 1453 Data can be correlated in various ways, using common data types, 1454 common data naming, and common data organization. There are several 1455 ways to extend the functionality of a module, based on the degree of 1456 coupling between the old and new functionality: 1458 o inline: update the module with new protocol-accessible objects. 1459 The naming and data organization of the original objects is used. 1460 The new objects are in the original module namespace. 1462 o augment: create a new module with new protocol-accessible objects 1463 that augment the original data structure. The naming and data 1464 organization of the original objects is used. The new objects are 1465 in the new module namespace. 1467 o mirror: create new objects in a new module or the original module, 1468 except use new a naming scheme and data location. The naming can 1469 be coupled in different ways. Tight coupling is achieved with a 1470 "leafref" data type, with the "require-instance" sub-statement set 1471 to "true". This method SHOULD be used. 1473 If the new data instances are not limited to the values in use in the 1474 original data structure, then the "require-instance" sub-statement 1475 MUST be set to "false". Loose coupling is achieved by using key 1476 leafs with the same data type as the original data structure. This 1477 has the same semantics as setting the "require-instance" sub- 1478 statement to "false". 1480 It is sometimes useful to separate configuration and operational 1481 state, so that they do not not even share the exact same naming 1482 characteristics. The correlation between configuration the 1483 operational state data that is affected by changes in configuration 1484 is a complex problem. There may not be a simple 1:1 relationship 1485 between a configuration data node and an operational data node. 1486 Further work is needed in YANG to clarify this relationship. 1487 Protocol work may also be needed to allow a client to retrieve this 1488 type of information from a server. At this time the best practice is 1489 to clearly document any relationship to other data structures in the 1490 "description" statement. 1492 5.20. Operational State 1494 In YANG, any data that has a "config" statement value of "false" 1495 could be considered operational state. The relationship between 1496 configuration (i.e., "config" statement has a value of "true") and 1497 operational state can be complex. 1499 One challenge for client developers is determining if the configured 1500 value is being used, which requires the developer to know which 1501 operational state parameters are associated with the particular 1502 configuration object (or group of objects). 1504 The simplest interaction between configuration and operational state 1505 is "none". For example, the arbitrary administrative name or 1506 sequence number assigned to an access control rule. The configured 1507 value is always the value that is being used by the system. 1509 However, some configuration parameters interact with routing and 1510 other signalling protocols, such that the operational value in use by 1511 the system may not be the same as the configured value. Other 1512 parameters specify the desired state, but environmental and other 1513 factors can cause the actual state to be different. 1515 For example a "temperature" configuration setting only represents the 1516 desired temperature. An operational state parameter is needed that 1517 reports the actual temperature in order to determine if the cooling 1518 system is operating correctly. YANG has no mechanism other than the 1519 "description" statement to associate the desired temperature and the 1520 actual temperature. 1522 Careful consideration needs to be given to the location of 1523 operational state data. It can either be located within the 1524 configuration subtree for which it applies, or it can be located 1525 outside the particular configuration subtree. Placing operation 1526 state within the configuration subtree is appropriate if the 1527 operational values can only exist if the configuration exists. 1529 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1530 are an example of a complex relationship between configuration and 1531 operational state. The operational values can include interface 1532 entries that have been discovered or initialized by the system. An 1533 interface may be in use that has not been configured at all. 1534 Therefore, the operational state for an interface cannot be located 1535 within the configuration for that same interface. 1537 Sometimes the configured value represents some sort of procedure to 1538 be followed, in which the system will select an actual value, based 1539 on protocol negotiation. 1541 leaf duplex-admin-mode { 1542 type enumeration { 1543 enum auto; 1544 enum half; 1545 enum full; 1546 } 1547 } 1549 leaf duplex-oper-mode { 1550 config false; 1551 type enumeration { 1552 enum half; 1553 enum full; 1554 } 1555 } 1557 For example a "duplex" mode configuration may be "auto" to auto- 1558 negotiate the actual value to be used. The operational parameter 1559 will never contain the value "auto". It will always contain the 1560 result of the auto-negotiation, such as "half" or "full". This is 1561 just one way in which the configuration data model is not exactly the 1562 same as the operational data model. Another is if the detailed 1563 properties of the data are different for configured vs. learned 1564 entries. 1566 If all the data model properties are aligned between configuration 1567 and operational data, then it can be useful to define the 1568 configuration parameters within a grouping, and then replicate that 1569 grouping within the operational state portion of the data model. 1571 grouping parms { 1572 // do not use config-stmt in any of the nodes 1573 // placed in this grouping 1574 } 1576 container foo { 1577 uses parms; // these are all config=true by default 1578 state { 1579 config false; // only exists if foo config exists 1580 uses parms; 1581 } 1582 } 1584 Note that this mechanism can also be used if the configuration and 1585 operational state data are in separate sub-trees: 1587 container bar { // bar config can exist without bar-state 1588 config true; 1589 uses parms; 1590 } 1592 container bar-state { // bar-state can exist without bar 1593 config false; 1594 uses parms; 1595 } 1597 The need to replicate objects or define different operational state 1598 objects depends on the data model. It is not possible to define one 1599 approach that will be optimal for all data models. Designers SHOULD 1600 describe the relationship in detail between configuration objects and 1601 any associated operational state objects. The "description" 1602 statements for both the configuration and the operational state 1603 SHOULD be used for this purpose. 1605 5.21. Performance Considerations 1607 It is generally likely that certain YANG statements require more 1608 runtime resources than other statements. Although there are no 1609 performance requirements for YANG validation, the following 1610 information MAY be considered when designing YANG data models: 1612 o Lists are generally more expensive than containers 1614 o "when-stmt" evaluation is generally more expensive than 1615 "if-feature" or "choice" statements 1617 o "must" statement is generally more expensive than "min-entries", 1618 "max-entries", "mandatory", or "unique" statements 1620 o "identityref" leafs are generally more expensive than 1621 "enumeration" leafs 1623 o "leafref" and "instance-identifier" types with "requite-instance" 1624 set to true are generally more expensive than if 1625 "require-instance" is set to false 1627 5.22. YANG 1.1 Guidelines 1629 TODO: need more input on YANG 1.1 guidelines 1631 5.22.1. Importing Multiple Revisions 1633 Standard modules SHOULD NOT import multiple revisions of the same 1634 module into a module. This MAY be done if the authors can 1635 demonstrate that the "avoided" definitions from most recent of the 1636 multiple revisions are somehow broken or harmful to interoperability. 1638 5.22.2. Using Feature Logic 1640 The YANG 1.1 feature logic is much more expressive than YANG 1.0. A 1641 "description" statement SHOULD describe the "if-feature" logic in 1642 text, to help readers understand the module. 1644 YANG features SHOULD be used instead of the "when" statement, if 1645 possible. This reduces server implementation complexity and might 1646 reduce runtime resource requirements as well. 1648 5.22.3. anyxml vs. anydata 1650 The "anyxml" statement MUST NOT be used to represent a conceptual 1651 subtree of YANG data nodes. The "anydata" statment MUST be used for 1652 this purpose. 1654 6. IANA Considerations 1656 This document registers one URI in the IETF XML registry [RFC3688]. 1658 The following registration has been made: 1660 URI: urn:ietf:params:xml:ns:yang:ietf-template 1662 Registrant Contact: The NETMOD WG of the IETF. 1664 XML: N/A, the requested URI is an XML namespace. 1666 Per this document, the following assignment has been made in the YANG 1667 Module Names Registry for the YANG module template in Appendix C. 1669 +-----------+-------------------------------------------+ 1670 | Field | Value | 1671 +-----------+-------------------------------------------+ 1672 | Name | ietf-template | 1673 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 1674 | Prefix | temp | 1675 | Reference | RFC XXXX | 1676 +-----------+-------------------------------------------+ 1678 YANG Registry Assignment 1680 7. Security Considerations 1682 This document defines documentation guidelines for NETCONF content 1683 defined with the YANG data modeling language. The guidelines for how 1684 to write a Security Considerations section for a YANG module are 1685 defined in the online document 1687 http://trac.tools.ietf.org/area/ops/trac/wiki/ 1688 yang-security-guidelines 1690 This document does not introduce any new or increased security risks 1691 into the management system. 1693 The following section contains the security considerations template 1694 dated 2010-06-16. Be sure to check the webpage at the URL listed 1695 above in case there is a more recent version available. 1697 Each specification that defines one or more YANG modules MUST contain 1698 a section that discusses security considerations relevant to those 1699 modules. This section MUST be patterned after the latest approved 1700 template (available at 1702 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 1704 In particular, writable data nodes that could be especially 1705 disruptive if abused MUST be explicitly listed by name and the 1706 associated security risks MUST be spelled out. 1708 Similarly, readable data nodes that contain especially sensitive 1709 information or that raise significant privacy concerns MUST be 1710 explicitly listed by name and the reasons for the sensitivity/privacy 1711 concerns MUST be explained. 1713 Further, if new RPC operations have been defined, then the security 1714 considerations of each new RPC operation MUST be explained. 1716 7.1. Security Considerations Section Template 1718 X. Security Considerations 1720 The YANG module defined in this memo is designed to be accessed via 1721 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1722 secure transport layer and the mandatory-to-implement secure 1723 transport is SSH [RFC6242]. 1725 -- if you have any writable data nodes (those are all the 1726 -- "config true" nodes, and remember, that is the default) 1727 -- describe their specific sensitivity or vulnerability. 1729 There are a number of data nodes defined in this YANG module which 1730 are writable/creatable/deletable (i.e., config true, which is the 1731 default). These data nodes may be considered sensitive or vulnerable 1732 in some network environments. Write operations (e.g., edit-config) 1733 to these data nodes without proper protection can have a negative 1734 effect on network operations. These are the subtrees and data nodes 1735 and their sensitivity/vulnerability: 1737 1739 -- for all YANG modules you must evaluate whether any readable data 1740 -- nodes (those are all the "config false" nodes, but also all other 1741 -- nodes, because they can also be read via operations like get or 1742 -- get-config) are sensitive or vulnerable (for instance, if they 1743 -- might reveal customer information or violate personal privacy 1744 -- laws such as those of the European Union if exposed to 1745 -- unauthorized parties) 1747 Some of the readable data nodes in this YANG module may be considered 1748 sensitive or vulnerable in some network environments. It is thus 1749 important to control read access (e.g., via get, get-config, or 1750 notification) to these data nodes. These are the subtrees and data 1751 nodes and their sensitivity/vulnerability: 1753 1755 -- if your YANG module has defined any rpc operations 1756 -- describe their specific sensitivity or vulnerability. 1758 Some of the RPC operations in this YANG module may be considered 1759 sensitive or vulnerable in some network environments. It is thus 1760 important to control access to these operations. These are the 1761 operations and their sensitivity/vulnerability: 1763 1765 8. Acknowledgments 1767 The structure and contents of this document are adapted from 1768 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 1770 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 1771 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 1772 contributions to this document. 1774 9. Changes Since RFC 6087 1776 The following changes have been made to the guidelines published in 1777 [RFC6087]: 1779 o Updated NETCONF reference from RFC 4741 to RFC 6241 1781 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 1783 o Updated YANG Types reference from RFC 6021 to RFC 6991 1785 o Updated obsolete URLs for IETF resources 1787 o Changed top-level data node guideline 1789 o Clarified XPath usage for a literal value representing a YANG 1790 identity 1792 o Clarified XPath usage for a when-stmt 1794 o Clarified XPath usage for 'proceeding-sibling' and 1795 'following-sibling' axes 1797 o Added terminology guidelines 1799 o Added YANG tree diagram definition and guideline 1801 o Updated XPath guidelines for type conversions and function library 1802 usage. 1804 o Updated data types section 1806 o Updated notifications section 1808 o Clarified conditional key leaf nodes 1810 o Clarify usage of 'uint64' and 'int64' data types 1812 o Added text on YANG feature usage 1814 o Added Identifier Naming Conventions 1816 o Clarified use of mandatory nodes with conditional augmentations 1818 o Clarified namespace and domain conventions for example modules 1820 10. References 1822 10.1. Normative References 1824 [I-D.ietf-netmod-rfc6020bis] 1825 Bjorklund, M., "YANG - A Data Modeling Language for the 1826 Network Configuration Protocol (NETCONF)", 1827 draft-ietf-netmod-rfc6020bis-06 (work in progress), 1828 July 2015. 1830 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1831 Requirement Levels", BCP 14, RFC 2119, March 1997. 1833 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1834 RFC 2223, October 1997. 1836 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1837 January 2004. 1839 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1840 Resource Identifier (URI): Generic Syntax", STD 66, 1841 RFC 3986, January 2005. 1843 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 1844 to the IETF Trust", BCP 78, RFC 5378, November 2008. 1846 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 1847 and Boilerplates", RFC 5741, December 2009. 1849 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1850 and A. Bierman, Ed., "Network Configuration Protocol 1851 (NETCONF)", RFC 6241, June 2011. 1853 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1854 July 2013. 1856 [W3C.REC-xpath-19991116] 1857 Clark, J. and S. DeRose, "XML Path Language (XPath) 1858 Version 1.0", World Wide Web Consortium 1859 Recommendation REC-xpath-19991116, November 1999, 1860 . 1862 10.2. Informative References 1864 [RFC-STYLE] 1865 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 1866 Style", September 2009, 1867 . 1869 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1870 Documents", BCP 111, RFC 4181, September 2005. 1872 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1873 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1874 May 2008. 1876 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 1877 Data Model Documents", RFC 6087, January 2011. 1879 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1880 Management", RFC 7223, May 2014. 1882 Appendix A. Change Log 1884 -- RFC Ed.: remove this section before publication. 1886 A.1. 03 ot 04 1888 o Added sections for deviation statements and performance 1889 considerations 1891 o Added YANG 1.1 section 1893 o Updated YANG reference from 1.0 to 1.1 1895 A.2. 02 to 03 1897 o Updated draft based on github data tracker issues added by Benoit 1898 Clause (Issues 12 - 18) 1900 A.3. 01 to 02 1902 o Updated draft based on mailing list comments. 1904 A.4. 00 to 01 1906 All issues from the issue tracker have been addressed. 1908 https://github.com/netmod-wg/rfc6087bis/issues 1910 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 1911 can use an Informative reference to this RFC for tree diagrams. 1912 Updated guidelines to reference this RFC when tree diagrams are 1913 used 1915 o Issue 2: XPath function restrictions: Added paragraphs in XPath 1916 usage section for 'id', 'namespace-uri', 'name', and 'lang' 1917 functions 1919 o Issue 3: XPath function document order issues: Added paragraph in 1920 XPath usage section about node-set ordering for 'local-name', 1921 'namespace-uri', 'name', 'string' and 'number' functions. Also 1922 any function that implicitly converts a node-set to a string. 1924 o Issue 4: XPath preceding-sibling and following-sibling: Checked 1925 and text in XPath usage section already has proposed text from 1926 Lada. 1928 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 1929 exception and example in XPath Usage section for augmented nodes. 1931 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 1932 to 'numeric and boolean expressions' 1934 o Issue 7: XPath module containment: Added sub-section on XPath 1935 wildcards 1937 o Issue 8: status-stmt usage: Added text to Lifecycle Management 1938 section about transitioning from active to deprecated and then to 1939 obsolete. 1941 o Issue 9: resource identification in notifications: Add text to 1942 Notifications section about identifying resources and using the 1943 leafref data type. 1945 o Issue 10: single quoted strings: Added text to Data Types section 1946 about using a single-quoted string for patterns. 1948 Appendix B. Module Review Checklist 1950 This section is adapted from RFC 4181. 1952 The purpose of a YANG module review is to review the YANG module both 1953 for technical correctness and for adherence to IETF documentation 1954 requirements. The following checklist may be helpful when reviewing 1955 an Internet-Draft: 1957 o I-D Boilerplate -- verify that the draft contains the required 1958 Internet-Draft boilerplate (see 1959 http://www.ietf.org/id-info/guidelines.html), including the 1960 appropriate statement to permit publication as an RFC, and that 1961 I-D boilerplate does not contain references or section numbers. 1963 o Abstract -- verify that the abstract does not contain references, 1964 that it does not have a section number, and that its content 1965 follows the guidelines in 1966 http://www.ietf.org/id-info/guidelines.html. 1968 o Copyright Notice -- verify that the draft has the appropriate text 1969 regarding the rights that document contributers provide to the 1970 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 1971 copyright notice at the beginning of the document. The IETF Trust 1972 Legal Provisions (TLP) can be found at: 1974 http://trustee.ietf.org/license-info/ 1976 o Security Considerations section -- verify that the draft uses the 1977 latest approved template from the OPS area website (http:// 1978 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 1979 and that the guidelines therein have been followed. 1981 o IANA Considerations section -- this section must always be 1982 present. For each module within the document, ensure that the 1983 IANA Considerations section contains entries for the following 1984 IANA registries: 1986 XML Namespace Registry: Register the YANG module namespace. 1988 YANG Module Registry: Register the YANG module name, prefix, 1989 namespace, and RFC number, according to the rules specified 1990 in [I-D.ietf-netmod-rfc6020bis]. 1992 o References -- verify that the references are properly divided 1993 between normative and informative references, that RFC 2119 is 1994 included as a normative reference if the terminology defined 1995 therein is used in the document, that all references required by 1996 the boilerplate are present, that all YANG modules containing 1997 imported items are cited as normative references, and that all 1998 citations point to the most current RFCs unless there is a valid 1999 reason to do otherwise (for example, it is OK to include an 2000 informative reference to a previous version of a specification to 2001 help explain a feature included for backward compatibility). Be 2002 sure citations for all imported modules are present somewhere in 2003 the document text (outside the YANG module). 2005 o License -- verify that the draft contains the Simplified BSD 2006 License in each YANG module or submodule. Some guidelines related 2007 to this requirement are described in Section 4.1. Make sure that 2008 the correct year is used in all copyright dates. Use the approved 2009 text from the latest Trust Legal Provisions (TLP) document, which 2010 can be found at: 2012 http://trustee.ietf.org/license-info/ 2014 o Other Issues -- check for any issues mentioned in 2015 http://www.ietf.org/id-info/checklist.html that are not covered 2016 elsewhere. 2018 o Technical Content -- review the actual technical content for 2019 compliance with the guidelines in this document. The use of a 2020 YANG module compiler is recommended when checking for syntax 2021 errors. A list of freely available tools and other information 2022 can be found at: 2024 http://trac.tools.ietf.org/wg/netconf/trac/wiki 2026 Checking for correct syntax, however, is only part of the job. 2027 It is just as important to actually read the YANG module document 2028 from the point of view of a potential implementor. It is 2029 particularly important to check that description statements are 2030 sufficiently clear and unambiguous to allow interoperable 2031 implementations to be created. 2033 Appendix C. YANG Module Template 2035 file "ietf-template@2010-05-18.yang" 2037 module ietf-template { 2039 // replace this string with a unique namespace URN value 2040 namespace 2041 "urn:ietf:params:xml:ns:yang:ietf-template"; 2043 // replace this string, and try to pick a unique prefix 2044 prefix "temp"; 2046 // import statements here: e.g., 2047 // import ietf-yang-types { prefix yang; } 2048 // import ietf-inet-types { prefix inet; } 2050 // identify the IETF working group if applicable 2051 organization 2052 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 2054 // update this contact statement with your info 2055 contact 2056 "WG Web: 2057 WG List: 2059 WG Chair: your-WG-chair 2060 2062 Editor: your-name 2063 "; 2065 // replace the first sentence in this description statement. 2066 // replace the copyright notice with the most recent 2067 // version, if it has been updated since the publication 2068 // of this document 2069 description 2070 "This module defines a template for other YANG modules. 2072 Copyright (c) IETF Trust and the persons 2073 identified as authors of the code. All rights reserved. 2075 Redistribution and use in source and binary forms, with or 2076 without modification, is permitted pursuant to, and subject 2077 to the license terms contained in, the Simplified BSD License 2078 set forth in Section 4.c of the IETF Trust's Legal Provisions 2079 Relating to IETF Documents 2080 (http://trustee.ietf.org/license-info). 2082 This version of this YANG module is part of RFC XXXX; see 2083 the RFC itself for full legal notices."; 2085 // RFC Ed.: replace XXXX with actual RFC number and remove 2086 // this note 2088 reference "RFC XXXX"; 2090 // RFC Ed.: remove this note 2091 // Note: extracted from RFC XXXX 2093 // replace '2010-05-18' with the module publication date 2094 // The format is (year-month-day) 2095 revision "2010-05-18" { 2096 description 2097 "Initial version"; 2098 } 2100 // extension statements 2102 // feature statements 2104 // identity statements 2106 // typedef statements 2108 // grouping statements 2110 // data definition statements 2112 // augment statements 2114 // rpc statements 2116 // notification statements 2118 // DO NOT put deviation statements in a published module 2120 } 2122 2124 Author's Address 2126 Andy Bierman 2127 YumaWorks 2129 Email: andy@yumaworks.com