idnits 2.17.1 draft-ietf-netmod-rfc6087bis-03.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 (June 12, 2015) is 3239 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 311, but not defined == Missing Reference: 'RFC6242' is mentioned on line 1626, 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) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 3 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 June 12, 2015 5 Expires: December 14, 2015 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-rfc6087bis-03 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 December 14, 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 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. Data Correlation . . . . . . . . . . . . . . . . . . . . . 33 106 5.19. Operational State . . . . . . . . . . . . . . . . . . . . 33 107 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 108 7. Security Considerations . . . . . . . . . . . . . . . . . . . 38 109 7.1. Security Considerations Section Template . . . . . . . . . 38 110 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 40 111 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 41 112 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 113 10.1. Normative References . . . . . . . . . . . . . . . . . . . 42 114 10.2. Informative References . . . . . . . . . . . . . . . . . . 42 115 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44 116 A.1. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 44 117 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 44 118 A.3. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 44 119 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 46 120 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 48 121 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 50 123 1. Introduction 125 The standardization of network configuration interfaces for use with 126 the Network Configuration Protocol [RFC6241] requires a modular set 127 of data models, which can be reused and extended over time. 129 This document defines a set of usage guidelines for Standards Track 130 documents containing [RFC6020] data models. YANG is used to define 131 the data structures, protocol operations, and notification content 132 used within a NETCONF server. A server that supports a particular 133 YANG module will support client NETCONF operation requests, as 134 indicated by the specific content defined in the YANG module. 136 This document is similar to the Structure of Management Information 137 version 2 (SMIv2) usage guidelines specification [RFC4181] in intent 138 and structure. However, since that document was written a decade 139 after SMIv2 modules had been in use, it was published as a 'Best 140 Current Practice' (BCP). This document is not a BCP, but rather an 141 informational reference, intended to promote consistency in documents 142 containing YANG modules. 144 Many YANG constructs are defined as optional to use, such as the 145 description statement. However, in order to maximize 146 interoperability of NETCONF implementations utilizing YANG data 147 models, it is desirable to define a set of usage guidelines that may 148 require a higher level of compliance than the minimum level defined 149 in the YANG specification. 151 In addition, YANG allows constructs such as infinite length 152 identifiers and string values, or top-level mandatory nodes, that a 153 compliant server is not required to support. Only constructs that 154 all servers are required to support can be used in IETF YANG modules. 156 This document defines usage guidelines related to the NETCONF 157 operations layer and NETCONF content layer, as defined in [RFC6241]. 158 These guidelines are intended to be used by authors and reviewers to 159 improve the readability and interoperability of published YANG data 160 models. 162 Note that this document is not a YANG tutorial and the reader is 163 expected to know the YANG data modeling language before using this 164 document. 166 2. Terminology 168 2.1. Requirements Notation 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 172 document are to be interpreted as described in [RFC2119]. 174 RFC 2119 language is used here to express the views of the NETMOD 175 working group regarding content for YANG modules. YANG modules 176 complying with this document will treat the RFC 2119 terminology as 177 if it were describing best current practices. 179 2.2. NETCONF Terms 181 The following terms are defined in [RFC6241] and are not redefined 182 here: 184 o capabilities 186 o client 188 o operation 190 o server 192 2.3. YANG Terms 194 The following terms are defined in [RFC6020] and are not redefined 195 here: 197 o data node 199 o module 201 o namespace 203 o submodule 205 o version 207 o YANG 209 o YIN 211 Note that the term 'module' may be used as a generic term for a YANG 212 module or submodule. When describing properties that are specific to 213 submodules, the term 'submodule' is used instead. 215 2.4. Terms 217 The following terms are used throughout this document: 219 o published: A stable release of a module or submodule, usually 220 contained in an RFC. 222 o unpublished: An unstable release of a module or submodule, usually 223 contained in an Internet-Draft. 225 3. YANG Tree Diagrams 227 YANG tree diagrams provide a concise representation of a YANG module 228 to help readers understand the module structure. 230 The meaning of the symbols in YANG tree diagrams is as follows: 232 o Brackets "[" and "]" enclose list keys. 234 o Abbreviations before data node names: "rw" means configuration 235 (read-write) and "ro" state data (read-only). 237 o Symbols after data node names: "?" means an optional node, "!" 238 means a presence container, and "*" denotes a list and leaf-list. 240 o Parentheses enclose choice and case nodes, and case nodes are also 241 marked with a colon (":"). 243 o Ellipsis ("...") stands for contents of subtrees that are not 244 shown. 246 4. General Documentation Guidelines 248 YANG data model modules under review are likely to be contained in 249 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 250 followed. The RFC Editor provides guidelines for authors of RFCs, 251 which are first published as Internet-Drafts. These guidelines 252 should be followed and are defined in [RFC2223] and updated in 253 [RFC5741] and "RFC Document Style" [RFC-STYLE]. 255 The following sections MUST be present in an Internet-Draft 256 containing a module: 258 o Narrative sections 260 o Definitions section 262 o Security Considerations section 264 o IANA Considerations section 266 o References section 268 4.1. Module Copyright 270 The module description statement MUST contain a reference to the 271 latest approved IETF Trust Copyright statement, which is available 272 online at: 274 http://trustee.ietf.org/license-info/ 276 Each YANG module or submodule contained within an Internet-Draft or 277 RFC is considered to be a code component. The strings "" and "" MUST be used to identify each code 279 component. 281 The "" tag SHOULD be followed by a string identifying 282 the file name specified in Section 5.2 of [RFC6020]. The following 283 example is for the '2010-01-18' revision of the 'ietf-foo' module: 285 file "ietf-foo@2010-01-18.yang" 286 module ietf-foo { 287 // ... 288 revision 2010-01-18 { 289 description "Latest revision"; 290 reference "RFC XXXX"; 291 } 292 // ... 293 } 295 297 Note that this convention MUST NOT be used for example modules or 298 module fragments. 300 4.2. Terminology Section 302 A terminology section MUST be present if any terms are defined in the 303 document or if any terms are imported from other documents. 305 If YANG tree diagrams are used, then a sub-section explaining the 306 YANG tree diagram syntax MUST be present, containing the following 307 text: 309 A simplified graphical representation of the data model is used in 310 this document. The meaning of the symbols in these diagrams is 311 defined in [RFCXXXX]. 313 -- RFC Editor: Replace XXXX with RFC number and remove note 315 4.3. Tree Diagrams 317 YANG tree diagrams provide a concise representation of a YANG module, 318 and SHOULD be included to help readers understand YANG module 319 structure. Tree diagrams MAY be split into sections to correspond to 320 document structure. 322 The following example shows a simple YANG tree diagram: 324 +--rw top-level-config-container 325 | +--rw config-list* [key-name] 326 | +--rw key-name string 327 | +--rw optional-parm? string 328 | +--rw mandatory-parm identityref 329 | +--ro read-only-leaf string 330 +--ro top-level-nonconfig-container 331 +--ro nonconfig-list* [name] 332 +--ro name string 333 +--ro type string 335 4.4. Narrative Sections 337 The narrative part MUST include an overview section that describes 338 the scope and field of application of the module(s) defined by the 339 specification and that specifies the relationship (if any) of these 340 modules to other standards, particularly to standards containing 341 other YANG modules. The narrative part SHOULD include one or more 342 sections to briefly describe the structure of the modules defined in 343 the specification. 345 If the module(s) defined by the specification imports definitions 346 from other modules (except for those defined in the [RFC6020] or 347 [RFC6991] documents), or are always implemented in conjunction with 348 other modules, then those facts MUST be noted in the overview 349 section, as MUST be noted any special interpretations of definitions 350 in other modules. 352 4.5. Definitions Section 354 This section contains the module(s) defined by the specification. 355 These modules MUST be written using the YANG syntax defined in 356 [RFC6020]. A YIN syntax version of the module MAY also be present in 357 the document. There MAY also be other types of modules present in 358 the document, such as SMIv2, which are not affected by these 359 guidelines. 361 See Section 5 for guidelines on YANG usage. 363 4.6. Security Considerations Section 365 Each specification that defines one or more modules MUST contain a 366 section that discusses security considerations relevant to those 367 modules. 369 This section MUST be patterned after the latest approved template 370 (available at http://trac.tools.ietf.org/area/ops/trac/wiki/ 371 yang-security-guidelines). Section 7.1 contains the security 372 considerations template dated 2013-05-08. Authors MUST check the 373 webpage at the URL listed above in case there is a more recent 374 version available. 376 In particular: 378 o Writable data nodes that could be especially disruptive if abused 379 MUST be explicitly listed by name and the associated security 380 risks MUST be explained. 382 o Readable data nodes that contain especially sensitive information 383 or that raise significant privacy concerns MUST be explicitly 384 listed by name and the reasons for the sensitivity/privacy 385 concerns MUST be explained. 387 o Operations (i.e., YANG 'rpc' statements) that are potentially 388 harmful to system behavior or that raise significant privacy 389 concerns MUST be explicitly listed by name and the reasons for the 390 sensitivity/privacy concerns MUST be explained. 392 4.7. IANA Considerations Section 394 In order to comply with IESG policy as set forth in 395 http://www.ietf.org/id-info/checklist.html, every Internet-Draft that 396 is submitted to the IESG for publication MUST contain an IANA 397 Considerations section. The requirements for this section vary 398 depending on what actions are required of the IANA. If there are no 399 IANA considerations applicable to the document, then the IANA 400 Considerations section stating that there are no actions is removed 401 by the RFC Editor before publication. Refer to the guidelines in 402 [RFC5226] for more details. 404 4.7.1. Documents that Create a New Namespace 406 If an Internet-Draft defines a new namespace that is to be 407 administered by the IANA, then the document MUST include an IANA 408 Considerations section that specifies how the namespace is to be 409 administered. 411 Specifically, if any YANG module namespace statement value contained 412 in the document is not already registered with IANA, then a new YANG 413 Namespace registry entry MUST be requested from the IANA. The 414 [RFC6020] specification includes the procedure for this purpose in 415 its IANA Considerations section. 417 4.7.2. Documents that Extend an Existing Namespace 419 It is possible to extend an existing namespace using a YANG submodule 420 that belongs to an existing module already administered by IANA. In 421 this case, the document containing the main module MUST be updated to 422 use the latest revision of the submodule. 424 4.8. Reference Sections 426 For every import or include statement that appears in a module 427 contained in the specification, which identifies a module in a 428 separate document, a corresponding normative reference to that 429 document MUST appear in the Normative References section. The 430 reference MUST correspond to the specific module version actually 431 used within the specification. 433 For every normative reference statement that appears in a module 434 contained in the specification, which identifies a separate document, 435 a corresponding normative reference to that document SHOULD appear in 436 the Normative References section. The reference SHOULD correspond to 437 the specific document version actually used within the specification. 438 If the reference statement identifies an informative reference, which 439 identifies a separate document, a corresponding informative reference 440 to that document MAY appear in the Informative References section. 442 4.9. Validation Tools 444 All modules need to be validated before submission in an Internet 445 Draft. The 'pyang' YANG compiler is freely available from github: 447 https://github.com/mbj4668/pyang 449 If the 'pyang' compiler is used, then the "--ietf" command line 450 option SHOULD be used to identify any IETF guideline issues. 452 4.10. Module Extraction Tools 454 A version of 'rfcstrip' is available which will extract YANG modules 455 from an Internet Draft or RFC. The 'rfcstrip' tool which supports 456 YANG module extraction is freely available: 458 http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip 460 This tool can be used to verify that the "" and "" tags are used correctly and that the normative YANG modules 462 can be extracted correctly. 464 5. YANG Usage Guidelines 466 In general, modules in IETF Standards Track specifications MUST 467 comply with all syntactic and semantic requirements of YANG 468 [RFC6020]. The guidelines in this section are intended to supplement 469 the YANG specification, which is intended to define a minimum set of 470 conformance requirements. 472 In order to promote interoperability and establish a set of practices 473 based on previous experience, the following sections establish usage 474 guidelines for specific YANG constructs. 476 Only guidelines that clarify or restrict the minimum conformance 477 requirements are included here. 479 5.1. Module Naming Conventions 481 Modules contained in Standards Track documents SHOULD be named 482 according to the guidelines in the IANA Considerations section of 483 [RFC6020]. 485 A distinctive word or acronym (e.g., protocol name or working group 486 acronym) SHOULD be used in the module name. If new definitions are 487 being defined to extend one or more existing modules, then the same 488 word or acronym should be reused, instead of creating a new one. 490 All published module names MUST be unique. For a YANG module 491 published in an RFC, this uniqueness is guaranteed by IANA. For 492 unpublished modules, the authors need to check that no other work in 493 progress is using the same module name. 495 Once a module name is published, it MUST NOT be reused, even if the 496 RFC containing the module is reclassified to 'Historic' status. 498 5.2. Prefixes 500 All YANG definitions are scoped by the module containing the 501 definition being referenced. This allows definitions from multiple 502 modules to be used, even if the names are not unique. In the example 503 below, the identifier "foo" is used in all 3 modules: 505 module example-foo { 506 namespace "http://example.com/ns/foo"; 507 prefix f; 509 container foo; 510 } 512 module example-bar { 513 namespace "http://example.com/ns/bar"; 514 prefix b; 516 typedef foo { type uint32; } 517 } 519 module example-one { 520 namespace "http://example.com/ns/one"; 521 prefix one; 522 import example-foo { prefix f; } 523 import example-bar { prefix b; } 525 augment "/f:foo" { 526 leaf foo { type b:foo; } 527 } 528 } 530 YANG defines the following rules for prefix usage: 532 o Prefixes are never allowed for built in data types and YANG 533 keywords. 535 o A prefix MUST be used for any external statement (i.e., a 536 statement defined with the YANG "extension" statement) 538 o The proper module prefix MUST be used for all identifiers imported 539 from other modules 541 o The proper module prefix MUST be used for all identifiers included 542 from a submodule. 544 The following guidelines apply to prefix usage of the current (local) 545 module: 547 o The local module prefix SHOULD be used instead of no prefix in all 548 path expressions. 550 o The local module prefix MUST be used instead of no prefix in all 551 "default" statements for an "identityref" or "instance-identifier" 552 data type 554 o The lcaol module prefix MAY be used for references to typedefs, 555 groupings, extensions, features, and identities defined in the 556 module. 558 5.3. Identifiers 560 Identifiers for all YANG identifiers in published modules MUST be 561 between 1 and 64 characters in length. These include any construct 562 specified as an 'identifier-arg-str' token in the ABNF in Section 12 563 of [RFC6020]. 565 5.3.1. Identifier Naming Conventions 567 Identifiers SHOULD follow a consistent naming pattern throughout the 568 module. Only lower-case letters, numbers, and dashes SHOULD be used 569 in identifier names. Upper-case characters and the underscore 570 character MAY be used if the identifier represents a well-known value 571 that uses these characters. 573 Identifiers SHOULD include complete words and/or well-known acronyms 574 or abbreviations. Child nodes within a container or list SHOULD NOT 575 replicate the parent identifier. YANG identifiers are hierarchical 576 and are only meant to be unique within the the set of sibling nodes 577 defined in the same module namespace. 579 It is permissible to use common identifiers such as "name" or "id" in 580 data definition statements, especially if these data nodes share a 581 common data type. 583 Identifiers SHOULD NOT carry any special semantics that identify data 584 modelling properties. Only YANG statements and YANG extension 585 statements are designed to convey machine readable data modelling 586 properties. For example, naming an object "config" or "state" does 587 not change whether it is configuration data or state data. Only 588 defined YANG statements or YANG extension statements can be used to 589 assign semantics in a machine readable format in YANG. 591 5.4. Defaults 593 In general, it is suggested that substatements containing very common 594 default values SHOULD NOT be present. The following substatements 595 are commonly used with the default value, which would make the module 596 difficult to read if used everywhere they are allowed. 598 +--------------+---------------+ 599 | Statement | Default Value | 600 +--------------+---------------+ 601 | config | true | 602 | mandatory | false | 603 | max-elements | unbounded | 604 | min-elements | 0 | 605 | ordered-by | system | 606 | status | current | 607 | yin-element | false | 608 +--------------+---------------+ 610 Statement Defaults 612 5.5. Conditional Statements 614 A module may be conceptually partitioned in several ways, using the 615 'if-feature' and/or 'when' statements. 617 Data model designers need to carefully consider all modularity 618 aspects, including the use of YANG conditional statements. 620 If a data definition is optional, depending on server support for a 621 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 622 be defined to indicate that the NETCONF capability is supported 623 within the data model. 625 If any notification data, or any data definition, for a non- 626 configuration data node is not mandatory, then the server may or may 627 not be required to return an instance of this data node. If any 628 conditional requirements exist for returning the data node in a 629 notification payload or retrieval request, they MUST be documented 630 somewhere. For example, a 'when' or 'if-feature' statement could 631 apply to the data node, or the conditional requirements could be 632 explained in a 'description' statement within the data node or one of 633 its ancestors (if any). 635 If any 'if-feature' statements apply to a list node, then the same 636 'if-feature' statements MUST apply to any key leaf nodes for the 637 list. There MUST NOT be any 'if-feature' statements applied to any 638 key leaf that do not also apply to the parent list node. 640 There SHOULD NOT be any 'when' statements applied to a key leaf node. 641 It is possible that a 'when' statement for an ancestor node of a key 642 leaf will have the exact node-set result as the key leaf. In such a 643 case, the 'when' statement for the key leaf is redundant and SHOULD 644 be avoided. 646 5.6. XPath Usage 648 This section describes guidelines for using the XML Path Language 649 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 651 5.6.1. XPath Evaluation Contexts 653 YANG defines 5 separate contexts for evaluation of XPath statements: 655 1) The "running" datastore: collection of all YANG configuration data 656 nodes. The document root is the conceptual container, (e.g., 657 "config" in the "edit-config" operation), which is the parent of all 658 top-level data definition statements with a "config" statement value 659 of "true". 661 2) State data + the "running" datastore: collection of all YANG data 662 nodes. The document root is the conceptual container, parent of all 663 top-level data definition statements. 665 3) Notification: an event notification document. The document root 666 is the notification element. 668 4) RPC Input: The document root is the conceptual "input" node, which 669 is the parent of all RPC input parameter definitions. 671 5) RPC Output: The document root is the conceptual "output" node, 672 which is the parent of all RPC output parameter definitions. 674 Note that these XPath contexts cannot be mixed. For example, a 675 "when" statement in a notification context cannot reference 676 configuration data. 678 notification foo { 679 leaf mtu { 680 // NOT OK because when-stmt context is this notification 681 when "/if:interfaces/if:interface[name='eth0']"; 682 type leafref { 683 // OK because path-stmt has a different context 684 path "/if:interfaces/if:interface/if:mtu"; 685 } 686 } 687 } 689 It is especially important to consider the XPath evaluation context 690 for XPath expressions defined in groupings. An XPath expression 691 defined in a grouping may not be portable, meaning it cannot be used 692 in multiple contexts and produce proper results. 694 If the XPath expressions defined in a grouping are intended for a 695 particular context, then this context SHOULD be identified in the 696 "description" statement for the grouping. 698 5.6.2. Function Library 700 The 'position' and 'last' functions SHOULD NOT be used. This applies 701 to implicit use of the 'position' function as well (e.g., 702 '//chapter[42]'). A server is only required to maintain the relative 703 XML document order of all instances of a particular user-ordered list 704 or leaf-list. The 'position' and 'last' functions MAY be used if 705 they are evaluated in a context where the context node is a user- 706 ordered 'list' or 'leaf-list'. 708 The 'id' function SHOULD NOT be used. The 'ID' attribute is not 709 present in YANG documents so this function has no meaning. The YANG 710 compiler SHOULD return an empty string for this function. 712 The 'namespace-uri' and 'name' functions SHOULD NOT be used. 713 Expanded names in XPath are different than YANG. A specific 714 canonical representation of a YANG expanded name does not exist. 716 The 'lang' function SHOULD NOT be used. This function does not apply 717 to YANG because there is no 'lang' attribute set with the document. 718 The YANG compiler SHOULD return 'false' for this function. 720 The 'local-name', 'namespace-uri', 'name', 'string', and 'number' 721 functions SHOULD NOT be used if the argument is a node-set. If so, 722 the function result will be determined by the document order of the 723 node-set. Since this order can be different on each server, the 724 function results can also be different. Any function call that 725 implicitly converts a node-set to a string will also have this issue. 727 The 'local-name' function SHOULD NOT be used to reference local names 728 outside of the YANG module defining the must or when expression 729 containing the 'local-name' function. Example of a local-name 730 function that should not be used: 732 /*[local-name()='foo'] 734 5.6.3. Axes 736 The 'attribute' and 'namespace' axes are not supported in YANG, and 737 MAY be empty in a NETCONF server implementation. 739 The 'preceding', and 'following' axes SHOULD NOT be used. These 740 constructs rely on XML document order within a NETCONF server 741 configuration database, which may not be supported consistently or 742 produce reliable results across implementations. Predicate 743 expressions based on static node properties (e.g., element name or 744 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 745 'preceding' and 'following' axes MAY be used if document order is not 746 relevant to the outcome of the expression (e.g., check for global 747 uniqueness of a parameter value). 749 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used, 750 however they MAY be used if document order is not relevant to the 751 outcome of the expression. 753 A server is only required to maintain the relative XML document order 754 of all instances of a particular user-ordered list or leaf-list. The 755 'preceding-sibling' and 'following-sibling' axes MAY be used if they 756 are evaluated in a context where the context node is a user-ordered 757 'list' or 'leaf-list'. 759 5.6.4. Types 761 Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT 762 be used within numeric or boolean expressions. There are boundary 763 conditions in which the translation from the YANG 64-bit type to an 764 XPath number can cause incorrect results. Specifically, an XPath 765 'double' precision floating point number cannot represent very large 766 positive or negative 64-bit numbers because it only provides a total 767 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 768 used in numeric expressions if the value can be represented with no 769 more than 53 bits of precision. 771 Data modelers need to be careful not to confuse the YANG value space 772 and the XPath value space. The data types are not the same in both, 773 and conversion between YANG and XPath data types SHOULD be considered 774 carefully. 776 Explicit XPath data type conversions MAY be used (e.g., 'string', 777 'boolean', or 'number' functions), instead of implicit XPath data 778 type conversions. 780 XPath expressions that contain a literal value representing a YANG 781 identity SHOULD always include the declared prefix of the module 782 where the identity is defined. 784 XPath expressions for 'when' statements SHOULD NOT reference the 785 context node or any descendant nodes of the context node. They MAY 786 reference descendant nodes if the 'when' statement is contained 787 within an 'augment' statement, and the referenced nodes are not 788 defined within the 'augment' statement. 790 Example: 792 augment "/rt:active-route/rt:input/rt:destination-address" { 793 when "rt:address-family='v4ur:ipv4-unicast'" { 794 description 795 "This augment is valid only for IPv4 unicast."; 796 } 797 // nodes defined here within the augment-stmt 798 // cannot be referenced in the when-stmt 799 } 801 5.6.5. Wildcards 803 It is possible to construct XPath expressions that will evaluate 804 differently when combined with several modules within a server 805 implementation, then when evaluated within the single module. This 806 is due to augmenting nodes from other modules. 808 Wildcard expansion is done within a server against all the nodes from 809 all namespaces, so it is possible for a 'must' or 'when' expression 810 that uses the '*' operator will always evaluate to false if processed 811 within a single YANG module. In such cases, the 'description' 812 statement SHOULD clarify that augmenting objects are expected to 813 match the wildcard expansion. 815 when /foo/services/*/active { 816 description 817 "No services directly defined in this module. 818 Matches objects that have augmented the services container."; 819 } 821 5.6.6. Boolean Expressions 823 The YANG "must" and "when" statements use an XPath boolean expression 824 to define the test condition for the statement. It is important to 825 specify these expressions in a way that will not cause inadvertent 826 changes in the result if the objects referenced in the expression are 827 updated in future revisions of the module. 829 For example, the leaf "foo2" must exist if the leaf "foo1" is equal 830 to "one" or "three": 832 leaf foo1 { 833 type enumeration { 834 enum one; 835 enum two; 836 enum three; 837 } 838 } 840 leaf foo2 { 841 // INCORRECT 842 must "/f:foo1 != 'two'"; 843 type string; 844 } 846 leaf foo2 { 847 // CORRECT 848 must "/f:foo1 = 'one' or /f:foo1 = 'three'"; 849 type string; 850 } 852 In the next revision of the module, leaf "foo1" is extended with a 853 nem enum named "four": 855 leaf foo1 { 856 type enumeration { 857 enum one; 858 enum two; 859 enum three; 860 enum four; 861 } 862 } 864 Now the first XPath expression will allow the enum "four" to be 865 accepted in addition to the "one" and "three" enum values. 867 5.7. Lifecycle Management 869 The status statement MUST be present if its value is 'deprecated' or 870 'obsolete'. The status SHOULD NOT be changed from 'current' directly 871 to 'obsolete'. An object SHOULD be available for at least one year 872 with 'deprecated' status before it is changed to 'obsolete'. 874 The module or submodule name MUST NOT be changed, once the document 875 containing the module or submodule is published. 877 The module namespace URI value MUST NOT be changed, once the document 878 containing the module is published. 880 The revision-date substatement within the imports statement SHOULD be 881 present if any groupings are used from the external module. 883 The revision-date substatement within the include statement SHOULD be 884 present if any groupings are used from the external submodule. 886 If submodules are used, then the document containing the main module 887 MUST be updated so that the main module revision date is equal or 888 more recent than the revision date of any submodule that is (directly 889 or indirectly) included by the main module. 891 5.8. Module Header, Meta, and Revision Statements 893 For published modules, the namespace MUST be a globally unique URI, 894 as defined in [RFC3986]. This value is usually assigned by the IANA. 896 The organization statement MUST be present. If the module is 897 contained in a document intended for Standards Track status, then the 898 organization SHOULD be the IETF working group chartered to write the 899 document. 901 The contact statement MUST be present. If the module is contained in 902 a document intended for Standards Track status, then the working 903 group web and mailing information MUST be present, and the main 904 document author or editor contact information SHOULD be present. If 905 additional authors or editors exist, their contact information MAY be 906 present. In addition, the Area Director and other contact 907 information MAY be present. 909 The description statement MUST be present. The appropriate IETF 910 Trust Copyright text MUST be present, as described in Section 4.1. 912 If the module relies on information contained in other documents, 913 which are not the same documents implied by the import statements 914 present in the module, then these documents MUST be identified in the 915 reference statement. 917 A revision statement MUST be present for each published version of 918 the module. The revision statement MUST have a reference 919 substatement. It MUST identify the published document that contains 920 the module. Modules are often extracted from their original 921 documents, and it is useful for developers and operators to know how 922 to find the original source document in a consistent manner. The 923 revision statement MAY have a description substatement. 925 Each new revision MUST include a revision date that is higher than 926 any other revision date in the module. The revision date does not 927 need to be updated if the module contents do not change in the new 928 document revision. 930 It is acceptable to reuse the same revision statement within 931 unpublished versions (i.e., Internet-Drafts), but the revision date 932 MUST be updated to a higher value each time the Internet-Draft is re- 933 posted. 935 5.9. Namespace Assignments 937 It is RECOMMENDED that only valid YANG modules be included in 938 documents, whether or not they are published yet. This allows: 940 o the module to compile correctly instead of generating disruptive 941 fatal errors. 943 o early implementors to use the modules without picking a random 944 value for the XML namespace. 946 o early interoperability testing since independent implementations 947 will use the same XML namespace value. 949 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 950 provided for the namespace statement in a YANG module. A value 951 SHOULD be selected that is not likely to collide with other YANG 952 namespaces. Standard module names, prefixes, and URI strings already 953 listed in the YANG Module Registry MUST NOT be used. 955 A standard namespace statement value SHOULD have the following form: 957 : 959 The following URN prefix string SHOULD be used for published and 960 unpublished YANG modules: 962 urn:ietf:params:xml:ns:yang: 964 The following example URNs would be valid namespace statement values 965 for Standards Track modules: 967 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 969 urn:ietf:params:xml:ns:yang:ietf-netconf-state 971 urn:ietf:params:xml:ns:yang:ietf-netconf 973 Note that a different URN prefix string SHOULD be used for non- 974 Standards-Track modules. The string SHOULD be selected according to 975 the guidelines in [RFC6020]. 977 The following examples are for non-Standards-Track modules. The 978 domain "example.com" SHOULD be used in all namespace URIs for example 979 modules. 981 http://example.com/ns/example-interfaces 983 http://example.com/ns/example-system 985 5.10. Top-Level Data Definitions 987 The top-level data organization SHOULD be considered carefully, in 988 advance. Data model designers need to consider how the functionality 989 for a given protocol or protocol family will grow over time. 991 The separation of configuration data and operational state SHOULD be 992 considered carefully. It is often useful to define separate top- 993 level containers for configuration and non-configuration data. 995 The number of top-level data nodes within a module SHOULD be 996 minimized. It is often useful to retrieve related information within 997 a single subtree. If data is too distributed, is becomes difficult 998 to retrieve all at once. 1000 The names and data organization SHOULD reflect persistent 1001 information, such as the name of a protocol. The name of the working 1002 group SHOULD NOT be used because this may change over time. 1004 A mandatory database data definition is defined as a node that a 1005 client must provide for the database to be valid. The server is not 1006 required to provide a value. 1008 Top-level database data definitions MUST NOT be mandatory. If a 1009 mandatory node appears at the top level, it will immediately cause 1010 the database to be invalid. This can occur when the server boots or 1011 when a module is loaded dynamically at runtime. 1013 5.11. Data Types 1015 Selection of an appropriate data type (i.e., built-in type, existing 1016 derived type, or new derived type) is very subjective, and therefore 1017 few requirements can be specified on that subject. 1019 Data model designers SHOULD use the most appropriate built-in data 1020 type for the particular application. 1022 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 1023 'int64') SHOULD NOT be used unless negative values are allowed for 1024 the desired semantics. 1026 5.11.1. Fixed Value Extensibility 1028 If the set of values is fixed and the data type contents are 1029 controlled by a single naming authority, then an enumeration data 1030 type SHOULD be used. 1032 leaf foo { 1033 type enumeration { 1034 enum one; 1035 enum two; 1036 } 1037 } 1039 If extensibility of enumerated values is required, then the 1040 'identityref' data type SHOULD be used instead of an enumeration or 1041 other built-in type. 1043 identity foo-type { 1044 description "Base for the extensible type"; 1045 } 1047 identity one { 1048 base f:foo-type; 1049 } 1050 identity two { 1051 base f:foo-type; 1052 } 1054 leaf foo { 1055 type identityref { 1056 base f:foo-type; 1057 } 1058 } 1060 Note that any module can declare an identity with base "foo-type" 1061 that is valid for the "foo" leaf. Identityref values are considered 1062 to be qualified names. 1064 5.11.2. Patterns and Ranges 1066 For string data types, if a machine-readable pattern can be defined 1067 for the desired semantics, then one or more pattern statements SHOULD 1068 be present. A single quoted string SHOULD be used to specify the 1069 pattern, since a double-quoted string can modify the content. 1071 The following typedef from [RFC6991] demonstrates the proper use of 1072 the "pattern" statement: 1074 typedef ipv4-address-no-zone { 1075 type inet:ipv4-address { 1076 pattern '[0-9\.]*'; 1077 } 1078 ... 1079 } 1081 For string data types, if the length of the string is required to be 1082 bounded in all implementations, then a length statement MUST be 1083 present. 1085 The following typedef from [RFC6991] demonstrates the proper use of 1086 the "length" statement: 1088 typedef yang-identifier { 1089 type string { 1090 length "1..max"; 1091 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1092 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 1093 } 1094 ... 1095 } 1097 For numeric data types, if the values allowed by the intended 1098 semantics are different than those allowed by the unbounded intrinsic 1099 data type (e.g., 'int32'), then a range statement SHOULD be present. 1101 The following typedef from [RFC6991] demonstrates the proper use of 1102 the "range" statement: 1104 typedef dscp { 1105 type uint8 { 1106 range "0..63"; 1107 } 1108 ... 1109 } 1111 5.11.3. Enumerations and Bits 1113 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 1114 or 'bit' SHOULD be documented. A separate description statement 1115 (within each 'enum' or 'bit' statement) SHOULD be present. 1117 leaf foo { 1118 // INCORRECT 1119 type enumeration { 1120 enum one; 1121 enum two; 1122 } 1123 description 1124 "The foo enum... 1125 one: The first enum 1126 two: The second enum"; 1127 } 1129 leaf foo { 1130 // CORRECT 1131 type enumeration { 1132 enum one { 1133 description "The first enum"; 1134 } 1135 enum two { 1136 description "The second enum"; 1137 } 1138 } 1139 description 1140 "The foo enum... "; 1141 } 1143 5.12. Reusable Type Definitions 1145 If an appropriate derived type exists in any standard module, such as 1146 [RFC6991], then it SHOULD be used instead of defining a new derived 1147 type. 1149 If an appropriate units identifier can be associated with the desired 1150 semantics, then a units statement SHOULD be present. 1152 If an appropriate default value can be associated with the desired 1153 semantics, then a default statement SHOULD be present. 1155 If a significant number of derived types are defined, and it is 1156 anticipated that these data types will be reused by multiple modules, 1157 then these derived types SHOULD be contained in a separate module or 1158 submodule, to allow easier reuse without unnecessary coupling. 1160 The description statement MUST be present. 1162 If the type definition semantics are defined in an external document 1163 (other than another YANG module indicated by an import statement), 1164 then the reference statement MUST be present. 1166 5.13. Data Definitions 1168 The description statement MUST be present in the following YANG 1169 statements: 1171 o anyxml 1173 o augment 1175 o choice 1177 o container 1179 o extension 1181 o feature 1183 o grouping 1185 o identity 1187 o leaf 1189 o leaf-list 1191 o list 1193 o notification 1195 o rpc 1197 o typedef 1199 If the data definition semantics are defined in an external document, 1200 (other than another YANG module indicated by an import statement), 1201 then a reference statement MUST be present. 1203 The 'anyxml' construct may be useful to represent an HTML banner 1204 containing markup elements, such as '<b>' and '</b>', and 1205 MAY be used in such cases. However, this construct SHOULD NOT be 1206 used if other YANG data node types can be used instead to represent 1207 the desired syntax and semantics. 1209 It has been found that the 'anyxml' statement is not implemented 1210 consistently across all servers. It is possible that mixed mode XML 1211 will not be supported, or configuration anyxml nodes will not 1212 supported. 1214 If there are referential integrity constraints associated with the 1215 desired semantics that can be represented with XPath, then one or 1216 more 'must' statements SHOULD be present. 1218 For list and leaf-list data definitions, if the number of possible 1219 instances is required to be bounded for all implementations, then the 1220 max-elements statements SHOULD be present. 1222 If any 'must' or 'when' statements are used within the data 1223 definition, then the data definition description statement SHOULD 1224 describe the purpose of each one. 1226 5.14. Operation Definitions 1228 If the operation semantics are defined in an external document (other 1229 than another YANG module indicated by an import statement), then a 1230 reference statement MUST be present. 1232 If the operation impacts system behavior in some way, it SHOULD be 1233 mentioned in the description statement. 1235 If the operation is potentially harmful to system behavior in some 1236 way, it MUST be mentioned in the Security Considerations section of 1237 the document. 1239 5.15. Notification Definitions 1241 The description statement MUST be present. 1243 If the notification semantics are defined in an external document 1244 (other than another YANG module indicated by an import statement), 1245 then a reference statement MUST be present. 1247 If the notification refers to a specific resource instance, then this 1248 instance SHOULD be identified in the notification data. This is 1249 usually done by including 'leafref' leaf nodes with the key leaf 1250 values for the resource instance. For example: 1252 notification interface-up { 1253 description "Sent when an interface is activated."; 1254 leaf name { 1255 type leafref { 1256 path "/if:interfaces/if:interface/if:name"; 1257 } 1258 } 1259 } 1261 Note that there are no formal YANG statements to identify any data 1262 node resources associated with a notification. The description 1263 statement for the notification SHOULD specify if and how the 1264 notification identifies any data node resources associated with the 1265 specific event. 1267 5.16. Feature Definitions 1269 The YANG "feature" statement is used to define a label for a set of 1270 optional functionality within a module. The "if-feature" statement 1271 is used in the YANG statements associated with a feature. 1273 The set of YANG features available in a module should be considered 1274 carefully. The description-stmt within a feature-stmt MUST specify 1275 any interactions with other features. 1277 If there is a large set of objects associated with a YANG feature, 1278 then consider moving those objects to a separate module, instead of 1279 using a YANG feature. Note that the set of features within a module 1280 is easily discovered by the reader, but the set of related modules 1281 within the entire YANG library is not as easy to identity. Module 1282 names with a common prefix can help readers identity the set of 1283 related modules, but this assumes the reader will have discovered and 1284 installed all the relevant modules. 1286 Another consideration for deciding whether to create a new module or 1287 add a YANG feature is the stability of the module in question. It 1288 may be desirable to have a stable base module that is not changed 1289 frequently. If new functionality is placed in a separate module, 1290 then the base module does not need to be republished. If it is 1291 designed as a YANG feature then the module will need to be 1292 republished. 1294 If one feature requires implementation of another feature, then an 1295 "if-feature" statement SHOULD be used in the dependent "feature" 1296 statement. 1298 For example, feature2 requires implementation of feature1: 1300 feature feature1 { 1301 description "Some protocol feature"; 1302 } 1304 feature feature2 { 1305 if-feature "feature1"; 1306 description "Another protocol feature"; 1307 } 1309 5.17. Augment Statements 1311 The YANG "augment" statement is used to define a set of data 1312 definition statements that will be added as child nodes of a target 1313 data node. The module namespace for these data nodes will be the 1314 augmenting module, not the augmented module. 1316 A top-level "augment" statement SHOULD NOT be used if the target data 1317 node is in the same module or submodule as the evaluated "augment" 1318 statement. The data definition statements SHOULD be added inline 1319 instead. 1321 5.17.1. Conditional Augment Statements 1323 The "augment" statement is often used together with the "when" 1324 statement and/or "if-feature" statement to make the augmentation 1325 conditional on some portion of the data model. 1327 The following example from [RFC7223] shows how a conditional 1328 container called "ethernet" is added to the "interface" list only for 1329 entries of the type "ethernetCsmacd". 1331 augment "/if:interfaces/if:interface" { 1332 when "if:type = 'ianaift:ethernetCsmacd'"; 1334 container ethernet { 1335 leaf duplex { 1336 ... 1337 } 1338 } 1339 } 1341 5.17.2. Conditionally Mandatory Data Definition Statements 1343 YANG has very specific rules about how configuration data can be 1344 updated in new releases of a module. These rules allow an "old 1345 client" to continue interoperating with a "new server". 1347 If data nodes are added to an existing entry, the old client MUST NOT 1348 be required to provide any mandatory parameters that were not in the 1349 original module definition. 1351 It is possible to add conditional augment statements such that the 1352 old client would not know about the new condition, and would not 1353 specify the new condition. The conditional augment statement can 1354 contain mandatory objects only if the condition is false unless 1355 explicitly requested by the client. 1357 Only a conditional augment statement that uses the "when" statement 1358 form of condition can be used in this manner. The YANG features 1359 enabled on the server cannot be controlled by the client in any way, 1360 so it is not safe to add mandatory augmenting data nodes based on the 1361 "if-feature" statement. 1363 The XPath "when" statement condition MUST NOT reference data outside 1364 of target data node because the client does not have any control over 1365 this external data. 1367 In the following dummy example, it is OK to augment the "interface" 1368 entry with "mandatory-leaf" because the augmentation depends on 1369 support for "some-new-iftype". The old client does not know about 1370 this type so it would never select this type, and therefore not be 1371 adding a mandatory data node. 1373 module my-module { 1374 ... 1376 identity some-new-iftype { 1377 base iana:iana-interface-type; 1378 } 1380 augment "/if:interfaces/if:interface" { 1381 when "if:type = 'mymod:some-new-iftype'"; 1383 leaf mandatory-leaf { 1384 mandatory true; 1385 ... 1386 } 1387 } 1388 } 1390 Note that this practice is safe only for creating data resources. It 1391 is not safe for replacing or modifying resources if the client does 1392 not know about the new condition. The YANG data model MUST be 1393 packaged in a way that requires the client to be aware of the 1394 mandatory data nodes if it is aware of the condition for this data. 1395 In the example above, the "some-new-iftype" identity is defined in 1396 the same module as the "mandatory-leaf" data definition statement. 1398 This practice is not safe for identities defined in a common module 1399 such as "iana-if-type" because the client is not required to know 1400 about "my-module" just because it knows about the "iana-if-type" 1401 module. 1403 5.18. Data Correlation 1405 Data can be correlated in various ways, using common data types, 1406 common data naming, and common data organization. There are several 1407 ways to extend the functionality of a module, based on the degree of 1408 coupling between the old and new functionality: 1410 o inline: update the module with new protocol-accessible objects. 1411 The naming and data organization of the original objects is used. 1412 The new objects are in the original module namespace. 1414 o augment: create a new module with new protocol-accessible objects 1415 that augment the original data structure. The naming and data 1416 organization of the original objects is used. The new objects are 1417 in the new module namespace. 1419 o mirror: create new objects in a new module or the original module, 1420 except use new a naming scheme and data location. The naming can 1421 be coupled in different ways. Tight coupling is achieved with a 1422 "leafref" data type, with the "require-instance" sub-statement set 1423 to "true". This method SHOULD be used. 1425 If the new data instances are not limited to the values in use in the 1426 original data structure, then the "require-instance" sub-statement 1427 MUST be set to "false". Loose coupling is achieved by using key 1428 leafs with the same data type as the original data structure. This 1429 has the same semantics as setting the "require-instance" sub- 1430 statement to "false". 1432 It is sometimes useful to separate configuration and operational 1433 state, so that they do not not even share the exact same naming 1434 characteristics. The correlation between configuration the 1435 operational state data that is affected by changes in configuration 1436 is a complex problem. There may not be a simple 1:1 relationship 1437 between a configuration data node and an operational data node. 1438 Further work is needed in YANG to clarify this relationship. 1439 Protocol work may also be needed to allow a client to retrieve this 1440 type of information from a server. At this time the best practice is 1441 to clearly document any relationship to other data structures in the 1442 "description" statement. 1444 5.19. Operational State 1446 In YANG, any data that has a "config" statement value of "false" 1447 could be considered operational state. The relationship between 1448 configuration (i.e., "config" statement has a value of "true") and 1449 operational state can be complex. 1451 One challenge for client developers is determining if the configured 1452 value is being used, which requires the developer to know which 1453 operational state parameters are associated with the particular 1454 configuration object (or group of objects). 1456 The simplest interaction between configuration and operational state 1457 is "none". For example, the arbitrary administrative name or 1458 sequence number assigned to an access control rule. The configured 1459 value is always the value that is being used by the system. 1461 However, some configuration parameters interact with routing and 1462 other signalling protocols, such that the operational value in use by 1463 the system may not be the same as the configured value. Other 1464 parameters specify the desired state, but environmental and other 1465 factors can cause the actual state to be different. 1467 For example a "temperature" configuration setting only represents the 1468 desired temperature. An operational state parameter is needed that 1469 reports the actual temperature in order to determine if the cooling 1470 system is operating correctly. YANG has no mechanism other than the 1471 "description" statement to associate the desired temperature and the 1472 actual temperature. 1474 Careful consideration needs to be given to the location of 1475 operational state data. It can either be located within the 1476 configuration subtree for which it applies, or it can be located 1477 outside the particular configuration subtree. Placing operation 1478 state within the configuration subtree is appropriate if the 1479 operational values can only exist if the configuration exists. 1481 The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] 1482 are an example of a complex relationship between configuration and 1483 operational state. The operational values can include interface 1484 entries that have been discovered or initialized by the system. An 1485 interface may be in use that has not been configured at all. 1486 Therefore, the operational state for an interface cannot be located 1487 within the configuration for that same interface. 1489 Sometimes the configured value represents some sort of procedure to 1490 be followed, in which the system will select an actual value, based 1491 on protocol negotiation. 1493 leaf duplex-admin-mode { 1494 type enumeration { 1495 enum auto; 1496 enum half; 1497 enum full; 1498 } 1499 } 1501 leaf duplex-oper-mode { 1502 config false; 1503 type enumeration { 1504 enum half; 1505 enum full; 1506 } 1507 } 1509 For example a "duplex" mode configuration may be "auto" to auto- 1510 negotiate the actual value to be used. The operational parameter 1511 will never contain the value "auto". It will always contain the 1512 result of the auto-negotiation, such as "half" or "full". This is 1513 just one way in which the configuration data model is not exactly the 1514 same as the operational data model. Another is if the detailed 1515 properties of the data are different for configured vs. learned 1516 entries. 1518 If all the data model properties are aligned between configuration 1519 and operational data, then it can be useful to define the 1520 configuration parameters within a grouping, and then replicate that 1521 grouping within the operational state portion of the data model. 1523 grouping parms { 1524 // do not use config-stmt in any of the nodes 1525 // placed in this grouping 1526 } 1528 container foo { 1529 uses parms; // these are all config=true by default 1530 state { 1531 config false; // only exists if foo config exists 1532 uses parms; 1533 } 1534 } 1536 Note that this mechanism can also be used if the configuration and 1537 operational state data are in separate sub-trees: 1539 container bar { // bar config can exist without bar-state 1540 config true; 1541 uses parms; 1542 } 1544 container bar-state { // bar-state can exist without bar 1545 config false; 1546 uses parms; 1547 } 1549 The need to replicate objects or define different operational state 1550 objects depends on the data model. It is not possible to define one 1551 approach that will be optimal for all data models. Designers SHOULD 1552 describe the relationship in detail between configuration objects and 1553 any associated operational state objects. The "description" 1554 statements for both the configuration and the operational state 1555 SHOULD be used for this purpose. 1557 6. IANA Considerations 1559 This document registers one URI in the IETF XML registry [RFC3688]. 1561 The following registration has been made: 1563 URI: urn:ietf:params:xml:ns:yang:ietf-template 1565 Registrant Contact: The NETMOD WG of the IETF. 1567 XML: N/A, the requested URI is an XML namespace. 1569 Per this document, the following assignment has been made in the YANG 1570 Module Names Registry for the YANG module template in Appendix C. 1572 +-----------+-------------------------------------------+ 1573 | Field | Value | 1574 +-----------+-------------------------------------------+ 1575 | Name | ietf-template | 1576 | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | 1577 | Prefix | temp | 1578 | Reference | RFC XXXX | 1579 +-----------+-------------------------------------------+ 1581 YANG Registry Assignment 1583 7. Security Considerations 1585 This document defines documentation guidelines for NETCONF content 1586 defined with the YANG data modeling language. The guidelines for how 1587 to write a Security Considerations section for a YANG module are 1588 defined in the online document 1590 http://trac.tools.ietf.org/area/ops/trac/wiki/ 1591 yang-security-guidelines 1593 This document does not introduce any new or increased security risks 1594 into the management system. 1596 The following section contains the security considerations template 1597 dated 2010-06-16. Be sure to check the webpage at the URL listed 1598 above in case there is a more recent version available. 1600 Each specification that defines one or more YANG modules MUST contain 1601 a section that discusses security considerations relevant to those 1602 modules. This section MUST be patterned after the latest approved 1603 template (available at 1605 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 1607 In particular, writable data nodes that could be especially 1608 disruptive if abused MUST be explicitly listed by name and the 1609 associated security risks MUST be spelled out. 1611 Similarly, readable data nodes that contain especially sensitive 1612 information or that raise significant privacy concerns MUST be 1613 explicitly listed by name and the reasons for the sensitivity/privacy 1614 concerns MUST be explained. 1616 Further, if new RPC operations have been defined, then the security 1617 considerations of each new RPC operation MUST be explained. 1619 7.1. Security Considerations Section Template 1621 X. Security Considerations 1623 The YANG module defined in this memo is designed to be accessed via 1624 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 1625 secure transport layer and the mandatory-to-implement secure 1626 transport is SSH [RFC6242]. 1628 -- if you have any writable data nodes (those are all the 1629 -- "config true" nodes, and remember, that is the default) 1630 -- describe their specific sensitivity or vulnerability. 1632 There are a number of data nodes defined in this YANG module which 1633 are writable/creatable/deletable (i.e., config true, which is the 1634 default). These data nodes may be considered sensitive or vulnerable 1635 in some network environments. Write operations (e.g., edit-config) 1636 to these data nodes without proper protection can have a negative 1637 effect on network operations. These are the subtrees and data nodes 1638 and their sensitivity/vulnerability: 1640 1642 -- for all YANG modules you must evaluate whether any readable data 1643 -- nodes (those are all the "config false" nodes, but also all other 1644 -- nodes, because they can also be read via operations like get or 1645 -- get-config) are sensitive or vulnerable (for instance, if they 1646 -- might reveal customer information or violate personal privacy 1647 -- laws such as those of the European Union if exposed to 1648 -- unauthorized parties) 1650 Some of the readable data nodes in this YANG module may be considered 1651 sensitive or vulnerable in some network environments. It is thus 1652 important to control read access (e.g., via get, get-config, or 1653 notification) to these data nodes. These are the subtrees and data 1654 nodes and their sensitivity/vulnerability: 1656 1658 -- if your YANG module has defined any rpc operations 1659 -- describe their specific sensitivity or vulnerability. 1661 Some of the RPC operations in this YANG module may be considered 1662 sensitive or vulnerable in some network environments. It is thus 1663 important to control access to these operations. These are the 1664 operations and their sensitivity/vulnerability: 1666 1668 8. Acknowledgments 1670 The structure and contents of this document are adapted from 1671 [RFC4181], guidelines for MIB Documents, by C. M. Heard. 1673 The working group thanks Martin Bjorklund, Juergen Schoenwaelder, 1674 Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and 1675 contributions to this document. 1677 9. Changes Since RFC 6087 1679 The following changes have been made to the guidelines published in 1680 [RFC6087]: 1682 o Updated NETCONF reference from RFC 4741 to RFC 6241 1684 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 1686 o Updated YANG Types reference from RFC 6021 to RFC 6991 1688 o Updated obsolete URLs for IETF resources 1690 o Changed top-level data node guideline 1692 o Clarified XPath usage for a literal value representing a YANG 1693 identity 1695 o Clarified XPath usage for a when-stmt 1697 o Clarified XPath usage for 'proceeding-sibling' and 1698 'following-sibling' axes 1700 o Added terminology guidelines 1702 o Added YANG tree diagram definition and guideline 1704 o Updated XPath guidelines for type conversions and function library 1705 usage. 1707 o Updated data types section 1709 o Updated notifications section 1711 o Clarified conditional key leaf nodes 1713 o Clarify usage of 'uint64' and 'int64' data types 1715 o Added text on YANG feature usage 1717 o Added Identifier Naming Conventions 1719 o Clarified use of mandatory nodes with conditional augmentations 1721 o Clarified namespace and domain conventions for example modules 1723 10. References 1725 10.1. Normative References 1727 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1728 Requirement Levels", BCP 14, RFC 2119, March 1997. 1730 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1731 RFC 2223, October 1997. 1733 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1734 January 2004. 1736 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1737 Resource Identifier (URI): Generic Syntax", STD 66, 1738 RFC 3986, January 2005. 1740 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 1741 to the IETF Trust", BCP 78, RFC 5378, November 2008. 1743 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 1744 and Boilerplates", RFC 5741, December 2009. 1746 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1747 Network Configuration Protocol (NETCONF)", RFC 6020, 1748 October 2010. 1750 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1751 and A. Bierman, Ed., "Network Configuration Protocol 1752 (NETCONF)", RFC 6241, June 2011. 1754 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1755 July 2013. 1757 [W3C.REC-xpath-19991116] 1758 Clark, J. and S. DeRose, "XML Path Language (XPath) 1759 Version 1.0", World Wide Web Consortium 1760 Recommendation REC-xpath-19991116, November 1999, 1761 . 1763 10.2. Informative References 1765 [RFC-STYLE] 1766 Braden, R., Ginoza, S., and A. Hagens, "RFC Document 1767 Style", September 2009, 1768 . 1770 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 1771 Documents", BCP 111, RFC 4181, September 2005. 1773 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1774 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1775 May 2008. 1777 [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG 1778 Data Model Documents", RFC 6087, January 2011. 1780 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1781 Management", RFC 7223, May 2014. 1783 Appendix A. Change Log 1785 -- RFC Ed.: remove this section before publication. 1787 A.1. 02 to 03 1789 o Updated draft based on github data tracker issues added by Benoit 1790 Clause (Issues 12 - 18) 1792 A.2. 01 to 02 1794 o Updated draft based on mailing list comments. 1796 A.3. 00 to 01 1798 All issues from the issue tracker have been addressed. 1800 https://github.com/netmod-wg/rfc6087bis/issues 1802 o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules 1803 can use an Informative reference to this RFC for tree diagrams. 1804 Updated guidelines to reference this RFC when tree diagrams are 1805 used 1807 o Issue 2: XPath function restrictions: Added paragraphs in XPath 1808 usage section for 'id', 'namespace-uri', 'name', and 'lang' 1809 functions 1811 o Issue 3: XPath function document order issues: Added paragraph in 1812 XPath usage section about node-set ordering for 'local-name', 1813 'namespace-uri', 'name', 'string' and 'number' functions. Also 1814 any function that implicitly converts a node-set to a string. 1816 o Issue 4: XPath preceding-sibling and following-sibling: Checked 1817 and text in XPath usage section already has proposed text from 1818 Lada. 1820 o Issue 5: XPath 'when-stmt' reference to descendant nodes: Added 1821 exception and example in XPath Usage section for augmented nodes. 1823 o Issue 6: XPath numeric conversions: Changed 'numeric expressions' 1824 to 'numeric and boolean expressions' 1826 o Issue 7: XPath module containment: Added sub-section on XPath 1827 wildcards 1829 o Issue 8: status-stmt usage: Added text to Lifecycle Management 1830 section about transitioning from active to deprecated and then to 1831 obsolete. 1833 o Issue 9: resource identification in notifications: Add text to 1834 Notifications section about identifying resources and using the 1835 leafref data type. 1837 o Issue 10: single quoted strings: Added text to Data Types section 1838 about using a single-quoted string for patterns. 1840 Appendix B. Module Review Checklist 1842 This section is adapted from RFC 4181. 1844 The purpose of a YANG module review is to review the YANG module both 1845 for technical correctness and for adherence to IETF documentation 1846 requirements. The following checklist may be helpful when reviewing 1847 an Internet-Draft: 1849 o I-D Boilerplate -- verify that the draft contains the required 1850 Internet-Draft boilerplate (see 1851 http://www.ietf.org/id-info/guidelines.html), including the 1852 appropriate statement to permit publication as an RFC, and that 1853 I-D boilerplate does not contain references or section numbers. 1855 o Abstract -- verify that the abstract does not contain references, 1856 that it does not have a section number, and that its content 1857 follows the guidelines in 1858 http://www.ietf.org/id-info/guidelines.html. 1860 o Copyright Notice -- verify that the draft has the appropriate text 1861 regarding the rights that document contributers provide to the 1862 IETF Trust [RFC5378]. Verify that it contains the full IETF Trust 1863 copyright notice at the beginning of the document. The IETF Trust 1864 Legal Provisions (TLP) can be found at: 1866 http://trustee.ietf.org/license-info/ 1868 o Security Considerations section -- verify that the draft uses the 1869 latest approved template from the OPS area website (http:// 1870 trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) 1871 and that the guidelines therein have been followed. 1873 o IANA Considerations section -- this section must always be 1874 present. For each module within the document, ensure that the 1875 IANA Considerations section contains entries for the following 1876 IANA registries: 1878 XML Namespace Registry: Register the YANG module namespace. 1880 YANG Module Registry: Register the YANG module name, prefix, 1881 namespace, and RFC number, according to the rules specified 1882 in [RFC6020]. 1884 o References -- verify that the references are properly divided 1885 between normative and informative references, that RFC 2119 is 1886 included as a normative reference if the terminology defined 1887 therein is used in the document, that all references required by 1888 the boilerplate are present, that all YANG modules containing 1889 imported items are cited as normative references, and that all 1890 citations point to the most current RFCs unless there is a valid 1891 reason to do otherwise (for example, it is OK to include an 1892 informative reference to a previous version of a specification to 1893 help explain a feature included for backward compatibility). Be 1894 sure citations for all imported modules are present somewhere in 1895 the document text (outside the YANG module). 1897 o License -- verify that the draft contains the Simplified BSD 1898 License in each YANG module or submodule. Some guidelines related 1899 to this requirement are described in Section 4.1. Make sure that 1900 the correct year is used in all copyright dates. Use the approved 1901 text from the latest Trust Legal Provisions (TLP) document, which 1902 can be found at: 1904 http://trustee.ietf.org/license-info/ 1906 o Other Issues -- check for any issues mentioned in 1907 http://www.ietf.org/id-info/checklist.html that are not covered 1908 elsewhere. 1910 o Technical Content -- review the actual technical content for 1911 compliance with the guidelines in this document. The use of a 1912 YANG module compiler is recommended when checking for syntax 1913 errors. A list of freely available tools and other information 1914 can be found at: 1916 http://trac.tools.ietf.org/wg/netconf/trac/wiki 1918 Checking for correct syntax, however, is only part of the job. 1919 It is just as important to actually read the YANG module document 1920 from the point of view of a potential implementor. It is 1921 particularly important to check that description statements are 1922 sufficiently clear and unambiguous to allow interoperable 1923 implementations to be created. 1925 Appendix C. YANG Module Template 1927 file "ietf-template@2010-05-18.yang" 1929 module ietf-template { 1931 // replace this string with a unique namespace URN value 1932 namespace 1933 "urn:ietf:params:xml:ns:yang:ietf-template"; 1935 // replace this string, and try to pick a unique prefix 1936 prefix "temp"; 1938 // import statements here: e.g., 1939 // import ietf-yang-types { prefix yang; } 1940 // import ietf-inet-types { prefix inet; } 1942 // identify the IETF working group if applicable 1943 organization 1944 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 1946 // update this contact statement with your info 1947 contact 1948 "WG Web: 1949 WG List: 1951 WG Chair: your-WG-chair 1952 1954 Editor: your-name 1955 "; 1957 // replace the first sentence in this description statement. 1958 // replace the copyright notice with the most recent 1959 // version, if it has been updated since the publication 1960 // of this document 1961 description 1962 "This module defines a template for other YANG modules. 1964 Copyright (c) IETF Trust and the persons 1965 identified as authors of the code. All rights reserved. 1967 Redistribution and use in source and binary forms, with or 1968 without modification, is permitted pursuant to, and subject 1969 to the license terms contained in, the Simplified BSD License 1970 set forth in Section 4.c of the IETF Trust's Legal Provisions 1971 Relating to IETF Documents 1972 (http://trustee.ietf.org/license-info). 1974 This version of this YANG module is part of RFC XXXX; see 1975 the RFC itself for full legal notices."; 1977 // RFC Ed.: replace XXXX with actual RFC number and remove 1978 // this note 1980 reference "RFC XXXX"; 1982 // RFC Ed.: remove this note 1983 // Note: extracted from RFC XXXX 1985 // replace '2010-05-18' with the module publication date 1986 // The format is (year-month-day) 1987 revision "2010-05-18" { 1988 description 1989 "Initial version"; 1990 } 1992 // extension statements 1994 // feature statements 1996 // identity statements 1998 // typedef statements 2000 // grouping statements 2002 // data definition statements 2004 // augment statements 2006 // rpc statements 2008 // notification statements 2010 // DO NOT put deviation statements in a published module 2012 } 2014 2016 Author's Address 2018 Andy Bierman 2019 YumaWorks 2021 Email: andy@yumaworks.com