idnits 2.17.1 draft-ietf-netmod-yang-usage-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 2, 2010) is 4954 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC4742' is mentioned on line 836, but not defined ** Obsolete undefined reference: RFC 4742 (Obsoleted by RFC 6242) ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 5741 (Obsoleted by RFC 7841) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Bierman 3 Internet-Draft Brocade 4 Intended status: Informational October 2, 2010 5 Expires: April 5, 2011 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-yang-usage-11 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 which utilize YANG 18 data model modules. 20 Status of this Memo 22 This Internet-Draft is submitted to IETF in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on April 5, 2011. 37 Copyright Notice 39 Copyright (c) 2010 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. General Documentation Guidelines . . . . . . . . . . . . . . . 7 61 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 7 62 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 8 63 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 64 3.4. Security Considerations Section . . . . . . . . . . . . . 8 65 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 9 66 3.5.1. Documents that Create a New Name Space . . . . . . . . 9 67 3.5.2. Documents that Extend an Existing Name Space . . . . . 9 68 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 10 69 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 11 70 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 11 71 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 11 72 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 12 74 4.5. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 12 75 4.6. Lifecycle Management . . . . . . . . . . . . . . . . . . . 13 76 4.7. Module Header, Meta, and Revision Statements . . . . . . . 14 77 4.8. Namespace Assignments . . . . . . . . . . . . . . . . . . 15 78 4.9. Top Level Data Definitions . . . . . . . . . . . . . . . . 16 79 4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 16 80 4.11. Reusable Type Definitions . . . . . . . . . . . . . . . . 17 81 4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 18 82 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 19 83 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19 84 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 86 6.1. Security Considerations Section Template . . . . . . . . . 21 87 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 88 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 89 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25 90 8.2. Informative References . . . . . . . . . . . . . . . . . . 25 91 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 27 92 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 29 93 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 32 94 C.1. Changes from 10 to 11 . . . . . . . . . . . . . . . . . . 32 95 C.2. Changes from 09 to 10 . . . . . . . . . . . . . . . . . . 32 96 C.3. Changes from 08 to 09 . . . . . . . . . . . . . . . . . . 32 97 C.4. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 32 98 C.5. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 32 99 C.6. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 32 100 C.7. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 33 101 C.8. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 33 102 C.9. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 34 103 C.10. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 34 104 C.11. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 34 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 107 1. Introduction 109 The standardization of network configuration interfaces for use with 110 the Network Configuration Protocol (NETCONF) [RFC4741] requires a 111 modular set of data models, which can be reused and extended over 112 time. 114 This document defines a set of usage guidelines for standards track 115 documents containing YANG [I-D.ietf-netmod-yang] data models. YANG 116 is used to define the data structures, protocol operations, and 117 notification content used within a NETCONF server. A server which 118 supports a particular YANG module will support client NETCONF 119 operation requests, as indicated by the specific content defined in 120 the YANG module. 122 This document is similar to the SMIv2 usage guidelines specification 123 [RFC4181] in intent and structure. However, since that document was 124 written a decade after SMIv2 modules had been in use, it was 125 published as a 'best current practice' (BCP). This document is not a 126 BCP, but rather an informational reference, intended to promote 127 consistency in documents containing YANG modules. 129 Many YANG constructs are defined as optional to use, such as the 130 description statement. However, in order to maximize 131 interoperability of NETCONF implementations utilizing YANG data 132 models, it is desirable to define a set of usage guidelines which may 133 require a higher level of compliance than the minimum level defined 134 in the YANG specification. 136 In addition, YANG allows constructs such as infinite length 137 identifiers and string values, or top-level mandatory nodes, that a 138 compliant server is not required to support. Only constructs which 139 all servers are required to support can be used in IETF YANG modules. 141 This document defines usage guidelines related to the NETCONF 142 operations layer, and NETCONF content layer, as defined in [RFC4741]. 143 These guidelines are intended to be used by authors and reviewers to 144 improve the readability and interoperability of published YANG data 145 models. 147 2. Terminology 149 2.1. Requirements Notation 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. 155 RFC 2119 language is used here to express the views of the NETMOD 156 working group regarding content for YANG modules. YANG modules 157 complying with this document will treat the RFC 2119 terminology as 158 if it were describing best current practices. 160 2.2. NETCONF Terms 162 The following terms are defined in [RFC4741] and are not redefined 163 here: 165 o capabilities 167 o client 169 o operation 171 o server 173 2.3. YANG Terms 175 The following terms are defined in [I-D.ietf-netmod-yang] and are not 176 redefined here: 178 o data node 180 o module 182 o namespace 184 o submodule 186 o version 188 o YANG 190 o YIN 192 Note that the term 'module' may be used as a generic term for a YANG 193 module or submodule. When describing properties which are specific 194 to submodules, the term 'submodule' is used instead. 196 2.4. Terms 198 The following terms are used throughout this document: 200 published: A stable release of a module or submodule, usually 201 contained in an RFC. 203 unpublished: An unstable release of a module or submodule, usually 204 contained in an Internet-Draft. 206 3. General Documentation Guidelines 208 YANG data model modules under review are likely to be contained in 209 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 210 followed. These guidelines are defined in [RFC2223] and updated in 211 [RFC5741]. Additional information is also available online at: 213 http://www.rfc-editor.org/rfc-editor/instructions2authors.txt 215 The following sections MUST be present in an Internet-Draft 216 containing a module: 218 o Narrative sections 220 o Definitions section 222 o Security Considerations section 224 o IANA Considerations section 226 o References section 228 3.1. Module Copyright 230 The module description statement MUST contain a reference to the 231 latest approved IETF Trust Copyright statement, which is available 232 on-line at: 234 http://trustee.ietf.org/license-info/ 236 Each YANG module or submodule contained within an Internet-Draft or 237 RFC is considered to be a code component. The strings '' and '' MUST be used to identify each code 239 component. 241 The '' tag SHOULD be followed by a string identifying 242 the file name specified in section 5.2 of [I-D.ietf-netmod-yang]. 243 The following example is for the '2010-01-18' revision of the 'ietf- 244 foo' module: 246 file "ietf-foo@2010-01-18.yang" 247 module ietf-foo { 248 // ... 249 revision 2010-01-18 { 250 description "Latest revision"; 251 reference "RFC XXXXX"; 252 } 253 // ... 254 } 255 257 Figure 1 259 3.2. Narrative Sections 261 The narrative part MUST include an overview section that describes 262 the scope and field of application of the module(s) defined by the 263 specification and that specifies the relationship (if any) of these 264 modules to other standards, particularly to standards containing 265 other YANG modules. The narrative part SHOULD include one or more 266 sections to briefly describe the structure of the modules defined in 267 the specification. 269 If the module(s) defined by the specification import definitions from 270 other modules (except for those defined in the YANG 271 [I-D.ietf-netmod-yang] or YANG Types [I-D.ietf-netmod-yang-types] 272 documents), or are always implemented in conjunction with other 273 modules, then those facts MUST be noted in the overview section, as 274 MUST be noted any special interpretations of definitions in other 275 modules. 277 3.3. Definitions Section 279 This section contains the module(s) defined by the specification. 280 These modules MUST be written using the YANG syntax defined in 281 [I-D.ietf-netmod-yang]. A YIN syntax version of the module MAY also 282 be present in the document. There MAY also be other types of modules 283 present in the document, such as SMIv2, which are not affected by 284 these guidelines. 286 See Section 4 for guidelines on YANG usage. 288 3.4. Security Considerations Section 290 Each specification that defines one or more modules MUST contain a 291 section that discusses security considerations relevant to those 292 modules. This section MUST be patterned after the latest approved 293 template (available at 294 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 296 In particular: 298 o Writable data nodes that could be especially disruptive if abused 299 MUST be explicitly listed by name and the associated security 300 risks MUST be explained. 302 o Readable data nodes that contain especially sensitive information 303 or that raise significant privacy concerns MUST be explicitly 304 listed by name and the reasons for the sensitivity/privacy 305 concerns MUST be explained. 307 o Operations (i.e., YANG 'rpc' statements) which are potentially 308 harmful to system behavior or that raise significant privacy 309 concerns MUST be explicitly listed by name and the reasons for the 310 sensitivity/privacy concerns MUST be explained. 312 3.5. IANA Considerations Section 314 In order to comply with IESG policy as set forth in 315 http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is 316 submitted to the IESG for publication which has action items for IANA 317 MUST contain an IANA Considerations section. The requirements for 318 this section vary depending what actions are required of the IANA. 319 If there are no IANA considerations applicable to the document, then 320 the IANA Considerations section is not required. Refer to the 321 guidelines in [RFC5226] for more details. 323 3.5.1. Documents that Create a New Name Space 325 If an Internet-Draft defines a new name space that is to be 326 administered by the IANA, then the document MUST include an IANA 327 Considerations section, that specifies how the name space is to be 328 administered. 330 Specifically, if any YANG module namespace statement value contained 331 in the document is not already registered with IANA, then a new YANG 332 Namespace registry entry MUST be requested from the IANA. The YANG 333 [I-D.ietf-netmod-yang] specification includes the procedure for this 334 purpose in its IANA Considerations section. 336 3.5.2. Documents that Extend an Existing Name Space 338 It is possible to extend an existing namespace using a YANG submodule 339 which belongs to an existing module already administered by IANA. In 340 this case, the document containing the main module MUST be updated to 341 use the latest revision of the submodule. 343 3.6. Reference Sections 345 For every import or include statement which appears in a module 346 contained in the specification, which identifies a module in a 347 separate document, a corresponding normative reference to that 348 document MUST appear in the Normative References section. The 349 reference MUST correspond to the specific module version actually 350 used within the specification. 352 For every normative reference statement which appears in a module 353 contained in the specification, which identifies a separate document, 354 a corresponding normative reference to that document SHOULD appear in 355 the Normative References section. The reference SHOULD correspond to 356 the specific document version actually used within the specification. 357 If the reference statement identifies an informative reference, which 358 identifies a separate document, a corresponding informative reference 359 to that document MAY appear in the Informative References section. 361 4. YANG Usage Guidelines 363 In general, modules in IETF standards-track specifications MUST 364 comply with all syntactic and semantic requirements of YANG. 365 [I-D.ietf-netmod-yang]. The guidelines in this section are intended 366 to supplement the YANG specification, which is intended to define a 367 minimum set of conformance requirements. 369 In order to promote interoperability and establish a set of practices 370 based on previous experience, the following sections establish usage 371 guidelines for specific YANG constructs. 373 Only guidelines which clarify or restrict the minimum conformance 374 requirements are included here. 376 4.1. Module Naming Conventions 378 Modules contained in standards track documents SHOULD be named 379 according to the guidelines in the IANA considerations section of 380 [I-D.ietf-netmod-yang]. 382 A distinctive word or acronym (e.g., protocol name or working group 383 acronym) SHOULD be used in the module name. If new definitions are 384 being defined to extend one or more existing modules, then the same 385 word or acronym should be reused, instead of creating a new one. 387 All published module names MUST be unique. For a YANG module 388 published in an RFC, this uniqueness is guaranteed by IANA. For 389 unpublished modules, the authors need to check that no other work in 390 progress is using the same module name. 392 Once a module name is published, it MUST NOT be reused, even if the 393 RFC containing the module is reclassified to 'Historic' status. 395 4.2. Identifiers 397 Identifiers for all YANG identifiers in published modules MUST be 398 between 1 and 64 characters in length. These include any construct 399 specified as an 'identifier-arg-str' token in the ABNF in section 12 400 of [I-D.ietf-netmod-yang]. 402 4.3. Defaults 404 In general, it is suggested that sub-statements containing very 405 common default values SHOULD NOT be present. The following sub- 406 statements are commonly used with the default value, which would make 407 the module difficult to read if used everywhere they are allowed. 409 +---------------+---------------+ 410 | Statement | Default Value | 411 +---------------+---------------+ 412 | config | true | 413 | | | 414 | mandatory | false | 415 | | | 416 | max-elements | unbounded | 417 | | | 418 | min-elements | 0 | 419 | | | 420 | ordered-by | system | 421 | | | 422 | status | current | 423 | | | 424 | yin-element | false | 425 +---------------+---------------+ 427 4.4. Conditional Statements 429 A module may be conceptually partitioned in several ways, using the 430 'if-feature' and/or 'when' statements. 432 Data model designers need to carefully consider all modularity 433 aspects, including the use of YANG conditional statements. 435 If a data definition is optional, depending on server support for a 436 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 437 be defined to indicate that the NETCONF capability is supported 438 within the data model. 440 If any notification data, or any data definition, for a non- 441 configuration data node is not mandatory, then the server may or may 442 not be required to return an instance of this data node. If any 443 conditional requirements exist for returning the data node in a 444 notification payload or retrieval request, they MUST be documented 445 somewhere. For example, a 'when' or 'if-feature' statement could 446 apply to the data node, or the conditional requirements could be 447 explained in a 'description' statement within the data node or one of 448 its ancestors (if any). 450 4.5. XPath Usage 452 This section describes guidelines for using the XML Path Language 453 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 455 The 'attribute' and 'namespace' axes are not supported in YANG, and 456 MAY be empty in a NETCONF server implementation. 458 The 'position' and 'last' functions SHOULD NOT be used. This applies 459 to implicit use of the 'position' function as well (e.g., 460 '//chapter[42]'). A server is only required to maintain the relative 461 XML document order of all instances of a particular user-ordered list 462 or leaf-list. The 'position' and 'last' functions MAY be used if 463 they are evaluated in a context where the context node is a user- 464 ordered 'list' or 'leaf-list'. 466 The 'preceding', and 'following' axes SHOULD NOT be used. These 467 constructs rely on XML document order within a NETCONF server 468 configuration database, which may not be supported consistently or 469 produce reliable results across implementations. Predicate 470 expressions based on static node properties (e.g., element name or 471 value, 'ancestor' or 'descendant' axes) SHOULD be used instead. The 472 'preceding' and 'following' axes MAY be used if document order is not 473 relevant to the outcome of the expression (e.g., check for global 474 uniqueness of a parameter value.) 476 The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used. 477 A server is only required to maintain the relative XML document order 478 of all instances of a particular user-ordered list or leaf-list. The 479 'preceding-sibling' and 'following-sibling' axes MAY be used if they 480 are evaluated in a context where the context node is a user-ordered 481 'list' or 'leaf-list'. 483 Data nodes which use the 'int64' and 'uint64' built-in type SHOULD 484 NOT be used within numeric expressions. There are boundary 485 conditions in which the translation from the YANG 64-bit type to an 486 XPath number can cause incorrect results. Specifically, an XPath 487 'double' precision floating point number cannot represent very large 488 positive or negative 64-bit numbers because it only provides a total 489 precision of 53 bits. The 'int64' and 'uint64' data types MAY be 490 used in numeric expressions if the value can be represented with no 491 more than 53 bits of precision. 493 Data modelers need to be careful not to confuse the YANG value space 494 and the XPath value space. The data types are not the same in both, 495 and conversion between YANG and XPath data types SHOULD be considered 496 carefully. 498 Explicit XPath data type conversions MAY be used (e.g., 'string', 499 'boolean', or 'number' functions), instead of implicit XPath data 500 type conversions. 502 4.6. Lifecycle Management 504 The status statement MUST be present if its value is 'deprecated' or 505 'obsolete'. 507 The module or submodule name MUST NOT be changed, once the document 508 containing the module or submodule is published. 510 The module namespace URI value MUST NOT be changed, once the document 511 containing the module is published. 513 The revision-date sub-statement within the imports statement SHOULD 514 be present if any groupings are used from the external module. 516 The revision-date sub-statement within the include statement SHOULD 517 be present if any groupings are used from the external sub-module. 519 If submodules are used, then the document containing the main module 520 MUST be updated so that the main module revision date is equal or 521 more recent than the revision date of any submodule which is 522 (directly or indirectly) included by the main module. 524 4.7. Module Header, Meta, and Revision Statements 526 For published modules, the namespace MUST be a globally unique URI, 527 as defined in [RFC3986]. This value is usually assigned by the IANA. 529 The organization statement MUST be present. If the module is 530 contained in a document intended for standards-track status, then the 531 organization SHOULD be the IETF working group chartered to write the 532 document. 534 The contact statement MUST be present. If the module is contained in 535 a document intended for standards-track status, then the working 536 group WEB and mailing information MUST be present, and the main 537 document author or editor contact information SHOULD be present. If 538 additional authors or editors exist, their contact information MAY be 539 present. In addition, the Area Director and other contact 540 information MAY be present. 542 The description statement MUST be present. The appropriate IETF 543 Trust Copyright text MUST be present, as described in Section 3.1. 545 If the module relies on information contained in other documents, 546 which are not the same documents implied by the import statements 547 present in the module, then these documents MUST be identified in the 548 reference statement. 550 A revision statement MUST be present for each published version of 551 the module. The revision statement MUST have a reference 552 substatement. It MUST identify the published document which contains 553 the module. Modules are often extracted from their original 554 documents and it is useful for developers and operators to know how 555 to find the original source document in a consistent manner. The 556 revision statement MAY have a description substatement. 558 Each new revision MUST include a revision date which is higher than 559 any other revision date in the module. The revision date does not 560 need to be updated if the module contents do not change in the new 561 document revision. 563 It is acceptable to reuse the same revision statement within 564 unpublished versions (i.e., Internet-Drafts), but the revision date 565 MUST be updated to a higher value each time the Internet-Draft is re- 566 published. 568 4.8. Namespace Assignments 570 It is RECOMMENDED that only valid YANG modules are included in 571 documents, whether they are published yet or not. This allows: 573 o the module to compile correctly instead of generating disruptive 574 fatal errors. 576 o early implementors to use the modules without picking a random 577 value for the XML namespace. 579 o early interoperability testing since independent implementations 580 will use the same XML namespace value. 582 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 583 provided for the namespace statement in a YANG module. A value 584 SHOULD be selected which is not likely to collide with other YANG 585 namespaces. Standard module names, prefixes, and URI strings already 586 listed in the YANG Module Registry MUST NOT be used. 588 A standard namespace statement value SHOULD have the following form: 590 : 592 The following URN prefix string SHOULD be used for published and 593 unpublished YANG modules: 595 urn:ietf:params:xml:ns:yang: 597 The following example URNs would be valid temporary namespace 598 statement values for standards-track modules: 600 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 601 urn:ietf:params:xml:ns:yang:ietf-netconf-state 603 urn:ietf:params:xml:ns:yang:ietf-netconf 605 Note that a different URN prefix string SHOULD be used for non- 606 standards track modules. The string SHOULD be selected according to 607 the guidelines in [I-D.ietf-netmod-yang]. 609 The following examples of non-standards track modules are only 610 suggestions. There are no guidelines for this type of URN in this 611 document: 613 http://example.com/ns/example-interfaces 615 http://example.com/ns/example-system 617 4.9. Top Level Data Definitions 619 There SHOULD only be one top-level data node defined in each YANG 620 module, if any data nodes are defined at all. 622 The top-level data organization SHOULD be considered carefully, in 623 advance. Data model designers need to consider how the functionality 624 for a given protocol or protocol family will grow over time. 626 The names and data organization SHOULD reflect persistent 627 information, such as the name of a protocol. The name of the working 628 group SHOULD NOT be used because this may change over time. 630 A mandatory database data definition is defined as a node that a 631 client must provide for the database to be valid. The server is not 632 required to provide a value. 634 Top-level database data definitions MUST NOT be mandatory. If a 635 mandatory node appears at the top-level, it will immediately cause 636 the database to be invalid. This can occur when the server boots or 637 when a module is loaded dynamically at runtime. 639 4.10. Data Types 641 Selection of an appropriate data type (i.e., built-in type, existing 642 derived type, or new derived type) is very subjective and therefore 643 few requirements can be specified on that subject. 645 Data model designers SHOULD use the most appropriate built-in data 646 type for the particular application. 648 If extensibility of enumerated values is required, then the 649 'identityref' data type SHOULD be used instead of an enumeration or 650 other built-in type. 652 For string data types, if a machine-readable pattern can be defined 653 for the desired semantics, then one or more pattern statements SHOULD 654 be present. 656 For string data types, if the length of the string is required to be 657 bounded in all implementations, then a length statement MUST be 658 present. 660 For numeric data types, if the values allowed by the intended 661 semantics are different than those allowed by the unbounded intrinsic 662 data type (e.g., 'int32'), then a range statement SHOULD be present. 664 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 665 'int64') SHOULD NOT be used unless negative values are allowed for 666 the desired semantics. 668 For 'enumeration' or 'bits' data types, the semantics for each 'enum' 669 or 'bit' SHOULD be documented. A separate description statement 670 (within each 'enum' or 'bit' statement) SHOULD be present. 672 4.11. Reusable Type Definitions 674 If an appropriate derived type exists in any standard module, such as 675 [I-D.ietf-netmod-yang-types], then it SHOULD be used instead of 676 defining a new derived type. 678 If an appropriate units identifier can be associated with the desired 679 semantics, then a units statement SHOULD be present. 681 If an appropriate default value can be associated with the desired 682 semantics, then a default statement SHOULD be present. 684 If a significant number of derived types are defined, and it is 685 anticipated that these data types will be reused by multiple modules, 686 then these derived types SHOULD be contained in a separate module or 687 submodule, to allow easier reuse without unnecessary coupling. 689 The description statement MUST be present. 691 If the type definition semantics are defined in an external document 692 (other than another YANG module indicated by an import statement), 693 then the reference statement MUST be present. 695 4.12. Data Definitions 697 The description statement MUST be present in the following YANG 698 statements: 700 o anyxml 702 o augment 704 o choice 706 o container 708 o extension 710 o feature 712 o grouping 714 o identity 716 o leaf 718 o leaf-list 720 o list 722 o notification 724 o rpc 726 o typedef 728 If the data definition semantics are defined in an external document, 729 (other than another YANG module indicated by an import statement), 730 then a reference statement MUST be present. 732 The 'anyxml' construct may be useful to represent an HTML banner 733 containing markup elements, such as '' and '', and MAY be used 734 in such cases . However, this construct SHOULD NOT be used if other 735 YANG data node types can be used instead to represent the desired 736 syntax and semantics. 738 If there are referential integrity constraints associated with the 739 desired semantics that can be represented with XPath, then one or 740 more must statements SHOULD be present. 742 For list and leaf-list data definitions, if the number of possible 743 instances is required to be bounded for all implementations, then the 744 max-elements statements SHOULD be present. 746 If any must or when statements are used within the data definition, 747 then the data definition description statement SHOULD describe the 748 purpose of each one. 750 4.13. Operation Definitions 752 If the operation semantics are defined in an external document (other 753 than another YANG module indicated by an import statement), then a 754 reference statement MUST be present. 756 If the operation impacts system behavior in some way, it SHOULD be 757 mentioned in the description statement. 759 If the operation is potentially harmful to system behavior in some 760 way, it MUST be mentioned in the Security Considerations section of 761 the document. 763 4.14. Notification Definitions 765 The description statement MUST be present. 767 If the notification semantics are defined in an external document 768 (other than another YANG module indicated by an import statement), 769 then a reference statement MUST be present. 771 5. IANA Considerations 773 This document registers one URI in the IETF XML registry [RFC3688]. 774 The following registration is requested: 776 URI: urn:ietf:params:xml:ns:yang:ietf-template 778 Registrant Contact: The NETMOD WG of the IETF. 780 XML: N/A, the requested URI is an XML namespace. 782 This document requests the following assignment in the YANG Module 783 Names Registry for the YANG module template in Appendix B. 785 +---------------+-------------------------------------------+ 786 | Field | Value | 787 +---------------+-------------------------------------------+ 788 | name | ietf-template | 789 | | | 790 | namespace | urn:ietf:params:xml:ns:yang:ietf-template | 791 | | | 792 | prefix | temp | 793 | | | 794 | reference | RFCXXXX | 795 +---------------+-------------------------------------------+ 797 6. Security Considerations 799 This document defines documentation guidelines for NETCONF content 800 defined with the YANG data modeling language. The guidelines for how 801 to write a Security Considerations section for a YANG module are 802 defined in the online document 804 http://www.ops.ietf.org/netconf/yang-security-considerations.txt 806 This document does not introduce any new or increased security risks 807 into the management system. 809 The following section contains the security considerations template 810 dated 2010-06-16. Be sure to check the WEB page at the URL listed 811 above in case there is a more recent version available. 813 Each specification that defines one or more YANG modules MUST contain 814 a section that discusses security considerations relevant to those 815 modules. This section MUST be patterned after the latest approved 816 template (available at [ed: URL TBD]). 818 In particular, writable data nodes that could be especially 819 disruptive if abused MUST be explicitly listed by name and the 820 associated security risks MUST be spelled out. 822 Similarly, readable data nodes that contain especially sensitive 823 information or that raise significant privacy concerns MUST be 824 explicitly listed by name and the reasons for the sensitivity/privacy 825 concerns MUST be explained. 827 Further, if new RPC operations have been defined, then the security 828 considerations of each new RPC operation MUST be explained. 830 6.1. Security Considerations Section Template 831 X. Security Considerations 833 The YANG module defined in this memo is designed to be accessed 834 via the NETCONF protocol [RFC4741]. The lowest NETCONF layer is 835 the secure transport layer and the mandatory to implement secure 836 transport is SSH [RFC4742]. 838 -- if you have any writeable data nodes (those are all the 839 -- "config true" nodes, and remember, that is the default) 840 -- describe their specific sensitivity or vulnerability. 842 There are a number of data nodes defined in this YANG module 843 which are writable/creatable/deletable (i.e. config true, which 844 is the default). These data nodes may be considered sensitive 845 or vulnerable in some network environments. Write operations 846 (e.g. edit-config) to these data nodes without proper protection 847 can have a negative effect on network operations. These are 848 the subtrees and data nodes and their sensitivity/vulnerability: 850 852 -- for all YANG modules you must evaluate whether any readable data 853 -- nodes (those are all the "config false" nodes, but also all other 854 -- nodes, because they can also be read via operations like get or 855 -- get-config) are sensitive or vulnerable (for instance, if they 856 -- might reveal customer information or violate personal privacy 857 -- laws such as those of the European Union if exposed to 858 -- unauthorized parties) 860 Some of the readable data nodes in this YANG module may be 861 considered sensitive or vulnerable in some network environments. 862 It is thus important to control read access (e.g. via get, 863 get-config or notification) to these data nodes. These are the 864 subtrees and data nodes and their sensitivity/vulnerability: 866 868 -- if your YANG module has defined any rpc operations 869 -- describe their specific sensitivity or vulnerability. 871 Some of the RPC operations in this YANG module may be considered 872 sensitive or vulnerable in some network environments. It is thus 873 important to control access to these operations. These are the 874 operations and their sensitivity/vulnerability: 876 877 Figure 2 879 7. Acknowledgments 881 The structure and contents of this document are adapted from 882 Guidelines for MIB Documents [RFC4181], by C. M. Heard. 884 The working group thanks Martin Bjorklund and Juergen Schoenwaelder 885 for their extensive reviews and contributions to this document. 887 8. References 889 8.1. Normative References 891 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 892 Requirement Levels", BCP 14, RFC 2119, March 1997. 894 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 895 RFC 2223, October 1997. 897 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 898 January 2004. 900 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 901 Resource Identifier (URI): Generic Syntax", STD 66, 902 RFC 3986, January 2005. 904 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 905 December 2006. 907 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 908 to the IETF Trust", BCP 78, RFC 5378, November 2008. 910 [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, 911 and Boilerplates", RFC 5741, December 2009. 913 [W3C.REC-xpath-19991116] 914 DeRose, S. and J. Clark, "XML Path Language (XPath) 915 Version 1.0", World Wide Web Consortium 916 Recommendation REC-xpath-19991116, November 1999, 917 . 919 [I-D.ietf-netmod-yang] 920 Bjorklund, M., "YANG - A data modeling language for the 921 Network Configuration Protocol (NETCONF)", 922 draft-ietf-netmod-yang-13 (work in progress), June 2010. 924 [I-D.ietf-netmod-yang-types] 925 Schoenwaelder, J., "Common YANG Data Types", 926 draft-ietf-netmod-yang-types-09 (work in progress), 927 April 2010. 929 8.2. Informative References 931 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 932 Documents", BCP 111, RFC 4181, September 2005. 934 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 935 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 936 May 2008. 938 Appendix A. Module Review Checklist 940 This section is adapted from RFC 4181. 942 The purpose of a YANG module review is to review the YANG module both 943 for technical correctness and for adherence to IETF documentation 944 requirements. The following checklist may be helpful when reviewing 945 a draft document: 947 1. I-D Boilerplate -- verify that the draft contains the required 948 Internet-Draft boilerplate (see 949 http://www.ietf.org/ietf/1id-guidelines.txt), including the 950 appropriate statement to permit publication as an RFC, and that 951 I-D boilerplate does not contain references or section numbers. 953 2. Abstract -- verify that the abstract does not contain references, 954 that it does not have a section number, and that its content 955 follows the guidelines in 956 http://www.ietf.org/ietf/1id-guidelines.txt. 958 3. IETF Trust Copyright -- verify that the draft has the appropriate 959 text regarding the rights that document contributers provide to 960 the IETF Trust [RFC5378]. Some guidelines related to this 961 requirement are described in Section 3.1. The IETF Trust license 962 policy (TLP) can be found at: 964 http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf 966 4. Security Considerations Section -- verify that the draft uses the 967 latest approved template from the OPS area web site (http:// 968 www.ops.ietf.org/netconf/yang-security-considerations.txt) and 969 that the guidelines therein have been followed. 971 5. IANA Considerations Section -- this section must always be 972 present. For each module within the document, ensure that the 973 IANA Considerations section contains entries for the following 974 IANA registries: 976 XML Namespace Registry: Register the YANG module namespace. 978 YANG Module Registry: Register the YANG module name, prefix, 979 namespace, and RFC number, according to the rules specified in 980 [I-D.ietf-netmod-yang]. 982 6. References -- verify that the references are properly divided 983 between normative and informative references, that RFC 2119 is 984 included as a normative reference if the terminology defined 985 therein is used in the document, that all references required by 986 the boilerplate are present, that all YANG modules containing 987 imported items are cited as normative references, and that all 988 citations point to the most current RFCs unless there is a valid 989 reason to do otherwise (for example, it is OK to include an 990 informative reference to a previous version of a specification to 991 help explain a feature included for backward compatibility). Be 992 sure citations for all imported modules are present somewhere in 993 the document text (outside the YANG module). 995 7. Copyright Notices -- verify that the draft contains an 996 abbreviated IETF Trust copyright notice in the description 997 statement of each YANG module or sub-module, and that it contains 998 the full IETF Trust copyright notice at the end of the document. 999 Make sure that the correct year is used in all copyright dates. 1000 Use the approved text from the latest Trust Legal Provisions 1001 (TLP) document, which can be found at: 1003 http://trustee.ietf.org/license-info/ 1005 8. Other Issues -- check for any issues mentioned in 1006 http://www.ietf.org/ID-Checklist.html that are not covered 1007 elsewhere. 1009 9. Technical Content -- review the actual technical content for 1010 compliance with the guidelines in this document. The use of a 1011 YANG module compiler is recommended when checking for syntax 1012 errors. A list of freely available tools and other information 1013 can be found at: 1015 http://trac.tools.ietf.org/wg/netconf/trac/wiki 1017 Checking for correct syntax, however, is only part of the job. 1018 It is just as important to actually read the YANG module document 1019 from the point of view of a potential implementor. It is 1020 particularly important to check that description statements are 1021 sufficiently clear and unambiguous to allow interoperable 1022 implementations to be created. 1024 Appendix B. YANG Module Template 1026 file "ietf-template@2010-05-18.yang" 1028 module ietf-template { 1030 // replace this string with a unique namespace URN value 1031 namespace 1032 "urn:ietf:params:xml:ns:yang:ietf-template"; 1034 // replace this string, and try to pick a unique prefix 1035 prefix "temp"; 1037 // import statements here: e.g., 1038 // import ietf-yang-types { prefix yang; } 1039 // import ietf-inet-types { prefix inet; } 1041 // identify the IETF working group if applicable 1042 organization 1043 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 1045 // update this contact statement with your info 1046 contact 1047 "WG Web: 1048 WG List: 1050 WG Chair: your-WG-chair 1051 1053 Editor: your-name 1054 "; 1056 // replace the first sentence in this description statement. 1057 // replace the copyright notice with the most recent 1058 // version, if it has been updated since the publication 1059 // of this document 1060 description 1061 "This module defines a template for other YANG modules. 1063 Copyright (c) 2010 IETF Trust and the persons identified as 1064 the document authors. All rights reserved. 1066 Redistribution and use in source and binary forms, with or 1067 without modification, is permitted pursuant to, and subject 1068 to the license terms contained in, the Simplified BSD License 1069 set forth in Section 4.c of the IETF Trust's Legal Provisions 1070 Relating to IETF Documents 1071 (http://trustee.ietf.org/license-info). 1073 This version of this YANG module is part of RFC XXXX; see 1074 the RFC itself for full legal notices."; 1076 // RFC Ed.: replace XXXX with actual RFC number and remove this note 1078 reference "RFC XXXX"; 1080 // RFC Ed.: remove this note 1081 // Note: extracted from draft-ietf-netmod-yang-usage-04.txt 1083 // replace '2010-05-18' with the module publication date 1084 // The format is (year-month-day) 1085 revision "2010-05-18" { 1086 description 1087 "Initial version"; 1088 } 1090 // extension statements 1092 // feature statements 1094 // identity statements 1096 // typedef statements 1098 // grouping statements 1100 // data definition statements 1102 // augment statements 1104 // rpc statements 1106 // notification statements 1108 // DO NOT put deviation statements in a published module 1110 } 1112 1113 Figure 3 1115 Appendix C. Change Log 1117 C.1. Changes from 10 to 11 1119 o Removed Intellectual Property section, since no longer required. 1121 o Reworded XPath guidelines related to XML document order, 'int64' 1122 and 'uint64' data types, and 'anyxml' data nodes. 1124 C.2. Changes from 09 to 10 1126 o Added security considerations section template. 1128 o Added guideline for documenting conditional requirements for non- 1129 mandatory non-configuration data nodes. 1131 o Clarified that revision date update applies to the module 1132 contents. 1134 C.3. Changes from 08 to 09 1136 o Clarifications and corrections to address Gen-ART review comments. 1138 C.4. Changes from 07 to 08 1140 o Corrected YANG security considerations URL. 1142 o Expanded 'CODE BEGINS' example. 1144 o Added RPC operations to the security considerations guidelines 1145 section. 1147 o Removed guideline about leading and trailing whitespace. 1149 C.5. Changes from 06 to 07 1151 o Corrected title change bug; supposed to be page header instead. 1153 o Fixed typos added to last revision. 1155 o Added sentence to checklist to make sure text outside module 1156 contains citations for imports. 1158 C.6. Changes from 05 to 06 1160 o Several clarifications and corrections, based on the AD review by 1161 Dan Romascanu. 1163 C.7. Changes from 04 to 05 1165 o Changed 'object' terminology to 'data definition'. 1167 o Put XPath guidelines in separate section. 1169 o Clarified XPath usage for XML document order dependencies. 1171 o Updated guidelines to current conventions. 1173 o Added informative reference for IANA considerations guidelines and 1174 XML registry. 1176 o Updated IANA Considerations section to reserve the ietf-template 1177 module in the YANG Module Name Registry so it cannot be reused 1178 accidently. 1180 o Many other clarifications and fixed typos found in WGLC reviews. 1182 C.8. Changes from 03 to 04 1184 o Removed figure 1 to reduce duplication, just refer to 4741bis 1185 draft. 1187 o Fixed bugs and typos found in WGLC reviews. 1189 o Removed some guidelines and referring to YANG draft instead of 1190 duplicating YANG rules here. 1192 o Changed security guidelines so they refer to the IETF Trust TLP 1193 instead of MIB-specific references. 1195 o Change temporary namespace guidelines so the DRAFT-XX and RFC-nnnn 1196 suffix strings are not used. 1198 o Changed some MIB boilerplate so it refers to YANG boilerplate 1199 instead. 1201 o Introduced dangling URL reference to online YANG security 1202 guidelines 1204 http://www.ops.ietf.org/yang-security.html 1206 [ed.: Text from Bert Wijnen will be completed soon and posted 1207 online, and then this URL will be finalized.] 1209 o Moved reference for identifying the source document inside the 1210 each revision statement. 1212 o Removed guideline about valid XPath since YANG already requires 1213 valid XPath. 1215 o Added guideline that strings should not rely on preservation of 1216 leading and trailing whitespace characters. 1218 o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST 1219 NOT to MAY use with caution. 1221 o Updated the TLP text within the example module again. 1223 o Reversed order of change log so most recent entries are first. 1225 C.9. Changes from 02 to 03 1227 o Updated figure 1 to align with 4741bis draft. 1229 o Updated guidelines for import-by-revision and include-by-revision. 1231 o Added file name to code begins convention in ietf-template module. 1233 C.10. Changes from 01 to 02 1235 o Updated figure 1 per mailing list comments. 1237 o Updated suggested organization to include the working group name. 1239 o Updated ietf-template.yang to use new organization statement 1240 value. 1242 o Updated Code Component requirements as per new TLP. 1244 o Updated ietf-template.yang to use new Code Component begin and end 1245 markers. 1247 o Updated references to the TLP in a couple sections. 1249 o Change manager/agent terminology to client/server. 1251 C.11. Changes from 00 to 01 1253 o Added transport 'TLS' to figure 1. 1255 o Added note about RFC 2119 terminology. 1257 o Corrected URL for instructions to authors. 1259 o Updated namespace procedures section. 1261 o Updated guidelines on module contact, reference, and organization 1262 statements. 1264 o Added note on use of preceding-sibling and following-sibling axes 1265 in XPath expressions. 1267 o Added section on temporary namespace statement values. 1269 o Added section on top level database objects. 1271 o Added ietf-template.yang appendix. 1273 Author's Address 1275 Andy Bierman 1276 Brocade 1278 Email: andy.bierman@brocade.com