idnits 2.17.1 draft-ietf-netmod-yang-usage-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Once a module name is published, it MUST not be reused, even if the RFC containing the module is reclassified to 'Historic' status. -- The document date (April 20, 2010) is 5117 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '42' on line 396 ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-12 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-types-08 Summary: 1 error (**), 0 flaws (~~), 4 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 InterWorking Labs 4 Intended status: Informational April 20, 2010 5 Expires: October 22, 2010 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-yang-usage-04 10 Abstract 12 This memo provides guidelines for authors and reviewers of standards 13 track specifications containing YANG data model modules. Applicable 14 portions may be used as a basis for reviews of other YANG data model 15 documents. Recommendations and procedures are defined, which are 16 intended to increase interoperability and usability of NETCONF 17 implementations which utilize YANG data model modules. 19 Status of this Memo 21 This Internet-Draft is submitted to IETF in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on October 22, 2010. 36 Copyright Notice 38 Copyright (c) 2010 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 56 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 57 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3. General Documentation Guidelines . . . . . . . . . . . . . . . 7 60 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 7 61 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 7 62 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 63 3.4. Security Considerations Section . . . . . . . . . . . . . 8 64 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 8 65 3.5.1. Documents that Create a New Name Space . . . . . . . . 8 66 3.5.2. Documents that Extend an Existing Name Space . . . . . 9 67 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 9 68 3.7. Copyright Notices . . . . . . . . . . . . . . . . . . . . 9 69 3.8. Intellectual Property Section . . . . . . . . . . . . . . 9 70 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 10 71 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 10 72 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 73 4.3. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 4.4. Conditional Statements . . . . . . . . . . . . . . . . . . 11 75 4.5. Lifecycle Management . . . . . . . . . . . . . . . . . . . 12 76 4.6. Header Contents . . . . . . . . . . . . . . . . . . . . . 12 77 4.7. Temporary Namespace Assignments . . . . . . . . . . . . . 13 78 4.8. Top Level Database Objects . . . . . . . . . . . . . . . . 14 79 4.9. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 15 80 4.10. Reusable Type Definitions . . . . . . . . . . . . . . . . 15 81 4.11. Object Definitions . . . . . . . . . . . . . . . . . . . . 16 82 4.12. Operation Definitions . . . . . . . . . . . . . . . . . . 17 83 4.13. Notification Definitions . . . . . . . . . . . . . . . . . 17 84 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 86 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 87 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 88 8.1. Normative References . . . . . . . . . . . . . . . . . . . 21 89 8.2. Informative References . . . . . . . . . . . . . . . . . . 21 90 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 22 91 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 24 92 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 27 93 C.1. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 27 94 C.2. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 28 95 C.3. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 28 96 C.4. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 28 97 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 29 99 1. Introduction 101 The standardization of network configuration interfaces for use with 102 the NETCONF [RFC4741] protocol requires a modular set of data models, 103 which can be reused and extended over time. 105 This document defines a set of usage guidelines for standards track 106 documents containing YANG [I-D.ietf-netmod-yang] data models. It is 107 similar to the MIB usage guidelines specification [RFC4181] in intent 108 and structure. 110 Many YANG constructs are defined as optional to use, such as the 111 description clause. However, in order to maximize interoperability 112 of NETCONF implementations utilizing YANG data models, it is 113 desirable to define a set of usage guidelines which may require a 114 higher level of compliance than the minimum level defined in the YANG 115 specification. 117 This document defines usage guidelines related to the NETCONF 118 operations layer, and NETCONF content layer, as defined in [RFC4741]. 120 2. Terminology 122 2.1. Requirements Notation 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in [RFC2119]. 128 RFC 2119 language is used here to express the views of the NETMOD 129 working group regarding YANG module content. Yang modules complying 130 with this document will treat the RFC 2119 terminology as if it were 131 describing best current practices. 133 2.2. NETCONF Terms 135 The following terms are defined in [RFC4741] and are not redefined 136 here: 138 o capabilities 140 o client 142 o operation 144 o server 146 2.3. YANG Terms 148 The following terms are defined in [I-D.ietf-netmod-yang] and are not 149 redefined here: 151 o data node 153 o module 155 o namespace 157 o submodule 159 o version 161 Note that the term 'module' may be used as a generic term for a YANG 162 module or submodule. When describing properties which are specific 163 to submodules, the term 'submodule' is used instead. 165 2.4. Terms 167 The following terms are used throughout this document: 169 published: A stable release of a module or submodule, usually 170 contained in an RFC. 172 unpublished: An unstable release of a module or submodule, usually 173 contained in an Internet Draft. 175 3. General Documentation Guidelines 177 YANG data model modules under review are likely to be contained in 178 Internet Drafts. All guidelines for Internet Draft authors MUST be 179 followed. These guidelines are available online at: 181 http://www.rfc-editor.org/rfc-editor/instructions2authors.txt 183 The following sections MUST be present in an Internet Draft 184 containing a module: 186 o YANG data model boilerplate section 188 o Narrative sections 190 o Definitions section 192 o Security Considerations section 194 o IANA Considerations section 196 o References section 198 3.1. Module Copyright 200 The module description statement MUST contain the latest approved 201 IETF Trust Copyright statement, which is available on-line, in 202 section 4 of the Trust Legal Provisions (TLP) document, at: 204 http://trustee.ietf.org/license-info/ 206 Each YANG module or submodule contained within an Internet Draft or 207 RFC MUST be identified as a 'Code Component'. The strings '' and '' SHOULD be used to identify each Code 209 Component. 211 3.2. Narrative Sections 213 The narrative part MUST include an overview section that describes 214 the scope and field of application of the module(s) defined by the 215 specification and that specifies the relationship (if any) of these 216 modules to other standards, particularly to standards containing 217 other module modules. The narrative part SHOULD include one or more 218 sections to briefly describe the structure of the modules defined in 219 the specification. 221 If the module(s) defined by the specification import definitions from 222 other modules (except for those defined in the YANG 224 [I-D.ietf-netmod-yang] or YANG Types [I-D.ietf-netmod-yang-types] 225 documents) or are always implemented in conjunction with other 226 modules, then those facts MUST be noted in the overview section, as 227 MUST any special interpretations of objects in other modules. 229 3.3. Definitions Section 231 This section contains the module(s) defined by the specification. 232 These modules MUST be written in YANG [I-D.ietf-netmod-yang]. 234 See Section 4 for guidelines on YANG usage. 236 3.4. Security Considerations Section 238 Each specification that defines one or more modules MUST contain a 239 section that discusses security considerations relevant to those 240 modules. This section MUST be patterned after the latest approved 241 template (available at http://www.ops.ietf.org/yang-security.html). 243 In particular, writable module objects that could be especially 244 disruptive if abused MUST be explicitly listed by name and the 245 associated security risks MUST be spelled out; similarly, readable 246 module objects that contain especially sensitive information or that 247 raise significant privacy concerns MUST be explicitly listed by name 248 and the reasons for the sensitivity/privacy concerns MUST be 249 explained. 251 3.5. IANA Considerations Section 253 In order to comply with IESG policy as set forth in 254 http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is 255 submitted to the IESG for publication MUST contain an IANA 256 Considerations section. The requirements for this section vary 257 depending what actions are required of the IANA. 259 3.5.1. Documents that Create a New Name Space 261 If an Internet-Draft defines a new name space that is to be 262 administered by the IANA, then the document MUST include an IANA 263 Considerations section, that specifies how the name space is to be 264 administered. 266 Specifically, if any YANG module namespace statement value contained 267 in the document is not already registered with IANA, then a new YANG 268 Namespace registry entry must be requested from the IANA. The YANG 269 specification includes the procedure for this purpose in its IANA 270 Considerations section. 272 3.5.2. Documents that Extend an Existing Name Space 274 It is possible to extend an existing namespace using a YANG submodule 275 which belongs to an existing module already administered by IANA. In 276 this case, the document containing the main module MUST be updated to 277 use the latest revision of the submodule. 279 3.6. Reference Sections 281 For every import or include statement which appears in a module 282 contained in the specification, which identifies a module in a 283 separate document, a corresponding normative reference to that 284 document MUST appear in the Normative References section. The 285 reference MUST correspond to the specific module version actually 286 used within the specification. 288 For every reference statement which appears in a module contained in 289 the specification, which identifies a separate document, a 290 corresponding normative reference to that document SHOULD appear in 291 the Normative References section. The reference SHOULD correspond to 292 the specific document version actually used within the specification. 294 3.7. Copyright Notices 296 The proper copyright notices MUST be present in the module 297 description statement. Refer to the IETF Trust Legal Provision for 298 the exact legal text that needs to be included. 300 3.8. Intellectual Property Section 302 The proper IPR statements MUST be present in the document, according 303 to the most current Internet Draft boilerplate. Refer to the IETF 304 Trust Legal Provision for the exact legal text that needs to be 305 included. 307 4. YANG Usage Guidelines 309 In general, modules in IETF standards-track specifications MUST 310 comply with all syntactic and semantic requirements of YANG. 311 [I-D.ietf-netmod-yang]. The guidelines in this section are intended 312 to supplement the YANG specification, which is intended to define a 313 minimum set of conformance requirements. 315 In order to promote interoperability and establish a set of practices 316 based on previous experience, the following sections establish usage 317 guidelines for specific YANG constructs. 319 Only guidelines which clarify or restrict the minimum conformance 320 requirements are included here. 322 4.1. Module Naming Conventions 324 Modules contained in standards track documents SHOULD be named 325 according to the guidelines in the IANA considerations section of 326 [I-D.ietf-netmod-yang]. 328 A distinctive word or acronym (e.g., protocol name or working group 329 acronym) SHOULD be used in the module name. If new definitions are 330 being defined to extend one or more existing modules, then the same 331 word or acronym should be reused, instead of creating a new one. 333 All published module names MUST be unique. 335 Once a module name is published, it MUST not be reused, even if the 336 RFC containing the module is reclassified to 'Historic' status. 338 4.2. Identifiers 340 Identifiers for all published modules, submodules, typedefs, 341 groupings, data objects, operations, and notifications MUST be 342 between 1 and 64 characters in length. 344 4.3. Defaults 346 In general, it is suggested that sub-statements containing default 347 values SHOULD NOT be present. For example, 'status current;', 348 'config true;', 'mandatory false;', and 'max-elements unbounded;' are 349 common defaults which would make the module difficult to read if used 350 everywhere they are allowed. 352 Instead, it is suggested that common statements SHOULD only be used 353 when being set to a value other than the default value. 355 4.4. Conditional Statements 357 A module may be conceptually partitioned in several ways, using the 358 'if-feature' and/or 'when' statements. 360 Data model designers need to carefully consider all modularity 361 aspects, including the use of YANG conditional statements. 363 Objects SHOULD NOT directly reference NETCONF capabilities, in order 364 to specify optional behavior. Instead, a 'feature' statement SHOULD 365 be defined instead of a NETCONF capability, and the 'if-feature' 366 statement SHOULD be used within the optional object definition. 368 If the condition associated with the desired semantics is not 369 dependent on any particular instance value within the database, then 370 an 'if-feature' statement SHOULD be used instead of a 'when' 371 statement. 373 The 'attribute' and 'namespace' axis SHOULD NOT be used because the 374 associated XML node types are not supported in YANG, and may not be 375 supported consistently across NETCONF server implementations. 377 The 'position' and 'last' functions MAY be used with caution, within 378 a single server implementation. These functions may be useful in 379 some cases when processing user-ordered lists. A server is only 380 required to maintain the XML order of a user-ordered list or leaf- 381 list. 383 The 'preceding', and 'following' axes SHOULD NOT be used. These 384 constructs rely on XML document order within a NETCONF server 385 configuration database, which may not be supported consistently or 386 produce reliable results across implementations. Predicate 387 expressions based on static node properties (e.g., name, value, 388 ancestors, descendants) SHOULD be used instead. 390 The 'preceding-sibling' and 'following-sibling' axes MAY be used, 391 with caution. A server is not required to maintain a persistent or 392 deterministic XML document order, which will affect use of these 393 axes. 395 Implicit 'position' function calls within predicates SHOULD NOT be 396 used. (e.g., //chapter[42]). 398 Data nodes which use the 'int64' and 'uint64' built-in type MAY be 399 used with caution, within relational expressions. There are boundary 400 conditions in which the translation from the YANG 64-bit type to an 401 XPath number can cause incorrect results. Specifically, an XPath 402 double precision floating point number cannot represent very large 403 positive or negative 64-bit numbers because it only provides a total 404 precision of 53 bits. 406 Data modelers need to be careful not to confuse the YANG value space 407 and the XPath value space. The data types are not the same in both, 408 and conversion between YANG and XPath data types SHOULD be considered 409 carefully. 411 Explicit XPath data type conversions MAY be used (e.g., 'string', 412 'boolean', or 'number' functions), instead of implicit XPath data 413 type conversions. 415 4.5. Lifecycle Management 417 The status statement SHOULD NOT be present if its value is 'current'. 418 It MUST be present if its value is 'deprecated' or 'obsolete'. 420 The module or submodule name MUST NOT be changed, once the document 421 containing the module or submodule is published. 423 The module namespace URI value MUST NOT be changed, once the document 424 containing the module is published. 426 The revision-date sub-statement (within the imports statement) SHOULD 427 be present if any groupings are used from the external module. 429 The revision-date sub-statement (within the include statement) SHOULD 430 be present if any groupings are used from the external sub-module. 432 If submodules are used, then the document containing the main module 433 MUST be updated so that the main module revision date is equal or 434 more recent than the revision date of any submodule which is 435 (directly or indirectly) included by the main module. 437 4.6. Header Contents 439 For published modules, the namespace MUST be a globally unique URI, 440 as defined in [RFC3986]. This value is usually assigned by the IANA. 442 The organization statement MUST be present. If the module is 443 contained in a documented intended for standards-track status, then 444 the organization SHOULD be the IETF working group chartered to write 445 the document. 447 The contact statement MUST be present. If the module is contained in 448 a document intended for standards-track status, then the working 449 group WEB and mailing information MUST be present, and the document 450 author contact information SHOULD be present. In addition, the Area 451 Director and other contact information MAY be present. 453 The description statement MUST be present. The appropriate IETF 454 Trust Copyright text MUST be present, as described in Section 3.1. 456 Modules are often extracted from their original documents and it is 457 useful for developers and operators to know how to find the original 458 source document in a consistent manner. 460 If the module relies on information contained in other documents, 461 which are not the same documents implied by the import statements 462 present in the module, then these documents MUST be identified in the 463 reference statement. 465 A revision statement MUST be present for each published version of 466 the module. The revision statement MUST have a reference 467 substatement. It MUST identify the published document which contains 468 the module. 470 Each new revision MUST include a revision date which is higher than 471 any other revision date in the module. 473 It is acceptable to reuse the same revision statement within 474 unpublished versions (i.e., Internet Drafts), but the revision date 475 MUST be updated to a higher value each time the Internet Draft is re- 476 published. 478 4.7. Temporary Namespace Assignments 480 It is desirable to include only valid YANG modules in documents, 481 whether they are published yet or not. This allows: 483 o the module to compile correctly instead of generating disruptive 484 fatal errors. 486 o early implementors to use the modules without picking a random 487 value for the XML namespace. 489 o early interoperability testing since independent implementations 490 will use the same XML namespace value. 492 Until a URI is assigned by the IANA, a temporary namespace URI MUST 493 be provided for the namespace statement in a YANG module. A value 494 SHOULD be selected which is not likely to collide with other YANG 495 namespaces. 497 A standard namespace statement value SHOULD have the following form: 499 : 501 The following URN prefix string SHOULD be used for published and 502 unpublished YANG modules 504 urn:ietf:params:xml:ns:yang: 506 The following example URNs would be valid temporary namespace 507 statement values for standards-track modules: 509 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 511 urn:ietf:params:xml:ns:yang:ietf-netconf-state 513 urn:ietf:params:xml:ns:yang:ietf-netconf 515 Note that a different URN prefix string SHOULD be used for non- 516 standards track modules. The string SHOULD be selected according to 517 the guidelines in [I-D.ietf-netmod-yang]. 519 The following examples of non-standards track modules are only 520 suggestions. There are no guidelines for this type of URN in this 521 document: 523 http://example.com/ns/example-interfaces 525 http://example.com/ns/example-system 527 4.8. Top Level Database Objects 529 There SHOULD only be one top-level data node defined in each YANG 530 module. However, there MAY be more than one if needed. 532 The top-level data organization SHOULD be considered carefully, in 533 advance. Data model designers need to consider how the functionality 534 for a given protocol or protocol family will grow over time. 536 The names and data organization SHOULD reflect persistent 537 information, such as the name of a protocol. The name of the working 538 group SHOULD NOT be used because this may change over time. 540 A mandatory database object is defined as a node that a client must 541 provide for the database to be valid. The server will not provide a 542 value under any conditions. 544 Top-level database objects MUST NOT be mandatory. If a mandatory 545 node appears at the top-level, it will immediately cause the database 546 to be invalid. This can occur when the server boots or when a module 547 is loaded dynamically at runtime. 549 4.9. Data Types 551 Selection of an appropriate data type (i.e., built-in type, existing 552 derived type, or new derived type) is very subjective and therefore 553 few requirements can be specified on that subject. 555 Data model designers SHOULD use the most appropriate built-in data 556 type for the particular application. 558 If extensibility of enumerated values is required, then the 559 identityref data type SHOULD be used instead of an enumeration or 560 other built-in type. 562 For string data types, if a machine-readable pattern can be defined 563 for the desired semantics, then one or more pattern statements SHOULD 564 be present. 566 For string data types, if the length of the string is required to 567 bounded in all implementations, then a length statement SHOULD be 568 present. 570 For string data types, object semantics SHOULD NOT rely on 571 preservation of leading and trailing whitespace characters. 573 For numeric data types, if the values allowed by the intended 574 semantics are different than those allowed by the unbounded intrinsic 575 data type (e.g., int32), then a range statement SHOULD be present. 577 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 578 'int64') SHOULD NOT be used unless negative values are allowed for 579 the desired semantics. 581 For enumeration or bits data types, the semantics for each enum or 582 bit SHOULD be documented. A separate description statement (within 583 each enum or bit statement) SHOULD be present. 585 4.10. Reusable Type Definitions 587 If an appropriate derived type exists in any standard module, such as 588 [I-D.ietf-netmod-yang-types], then it SHOULD be used instead of 589 defining a new derived type. 591 If an appropriate units identifier can be associated with the desired 592 semantics, then a units statement SHOULD be present. 594 If an appropriate default value can be associated with the desired 595 semantics, then a default statement SHOULD be present. 597 If a significant number of derived types are defined, and it is 598 anticipated that these data types will be reused by multiple modules, 599 then these derived types SHOULD be contained in a separate module or 600 submodule, to allow easier reuse without unnecessary coupling. 602 The description statement MUST be present. 604 If the type definition semantics are defined in an external document, 605 then the reference statement SHOULD be present. 607 4.11. Object Definitions 609 The description statement MUST be present in the following body 610 statements: 612 o extension 614 o feature 616 o identity 618 o typedef 620 o grouping 622 o augment 624 o rpc 626 o notification 628 The description statement MUST be present in the following data 629 definition constructs: 631 o container 633 o leaf 635 o leaf-list 637 o list 639 o choice 641 o anyxml 642 If the object semantics are defined in an external document, then a 643 reference statement SHOULD be present. 645 The 'anyxml' construct MAY be used with caution within configuration 646 data. This may be useful to represent an HTML banner for example. 647 However, this construct SHOULD NOT be used if other YANG data node 648 types can be used instead to represent the desired syntax and 649 semantics. 651 If there are referential integrity constraints associated with the 652 desired semantics that can be represented with XPath, then one or 653 more must statements SHOULD be present. 655 For list and leaf-list objects, if the number of possible instances 656 is required to be bounded for all implementations, then the max- 657 elements statements SHOULD be present. 659 If any must or when statements are used within the object definition, 660 then the object description statement SHOULD describe the purpose of 661 each one. 663 4.12. Operation Definitions 665 The description statement MUST be present in 'rpc' statements 666 defining new operations. 668 If the operation semantics are defined in an external document, then 669 a reference statement SHOULD be present. 671 If the operation impacts system behavior in some way, it SHOULD be 672 mentioned in the description statement. 674 If the operation is potentially harmful to system behavior in some 675 way, it MUST be mentioned in the Security Considerations section of 676 the document. 678 4.13. Notification Definitions 680 The description statement MUST be present. 682 If the notification semantics are defined in an external document, 683 then a reference statement SHOULD be present. 685 5. IANA Considerations 687 There are no actions requested of IANA at this time. 689 6. Security Considerations 691 This document defines documentation guidelines for NETCONF content 692 defined with the YANG data modeling language. It does not introduce 693 any new or increased security risks into the management system. 695 7. Acknowledgments 697 The structure and contents of this document are adapted from 698 Guidelines for MIB Documents [RFC4181], by C. M. Heard. 700 8. References 702 8.1. Normative References 704 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 705 Requirement Levels", BCP 14, RFC 2119, March 1997. 707 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 708 Resource Identifier (URI): Generic Syntax", STD 66, 709 RFC 3986, January 2005. 711 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 712 December 2006. 714 [I-D.ietf-netmod-yang] 715 Bjorklund, M., "YANG - A data modeling language for 716 NETCONF", draft-ietf-netmod-yang-12 (work in progress), 717 April 2010. 719 [I-D.ietf-netmod-yang-types] 720 Schoenwaelder, J., "Common YANG Data Types", 721 draft-ietf-netmod-yang-types-08 (work in progress), 722 April 2010. 724 8.2. Informative References 726 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 727 Documents", BCP 111, RFC 4181, September 2005. 729 Appendix A. Module Review Checklist 731 This section is adapted from RFC 4181. 733 The purpose of a YANG module review is to review the YANG module both 734 for technical correctness and for adherence to IETF documentation 735 requirements. The following checklist may be helpful when reviewing 736 a draft document: 738 1. I-D Boilerplate -- verify that the draft contains the required 739 Internet-Draft boilerplate (see 740 http://www.ietf.org/ietf/1id-guidelines.txt), including the 741 appropriate statement to permit publication as an RFC, and that 742 I-D boilerplate does not contain references or section numbers. 744 2. Abstract -- verify that the abstract does not contain references, 745 that it does not have a section number, and that its content 746 follows the guidelines in 747 http://www.ietf.org/ietf/1id-guidelines.txt. 749 3. IETF Trust Copyright -- verify that the draft contains the latest 750 approved TLP boilerplate as described in Section 3.1. 752 4. Security Considerations Section -- verify that the draft uses the 753 latest approved template from the OPS area web site 754 (http://www.ops.ietf.org/yang-security.html) and that the 755 guidelines therein have been followed. 757 5. IANA Considerations Section -- this section must always be 758 present. For each module within the document, ensure that the 759 IANA Considerations section contains entries for the following 760 IANA registries: 762 XML Namespace Registry: Register the YANG module namespace. 764 YANG Module Registry: Register the YANG module name, prefix, 765 namespace, and RFC number, according to the rules specified in 766 [I-D.ietf-netmod-yang]. 768 6. References -- verify that the references are properly divided 769 between normative and informative references, that RFC 2119 is 770 included as a normative reference if the terminology defined 771 therein is used in the document, that all references required by 772 the boilerplate are present, that all YANG modules containing 773 imported items are cited as normative references, and that all 774 citations point to the most current RFCs unless there is a valid 775 reason to do otherwise (for example, it is OK to include an 776 informative reference to a previous version of a specification to 777 help explain a feature included for backward compatibility). 779 7. Copyright Notices -- verify that the draft contains an 780 abbreviated IETF Trust copyright notice in the description 781 statement of each YANG module or sub-module, and that it contains 782 the full IETF Trust copyright notice at the end of the document. 783 Make sure that the correct year is used in all copyright dates. 784 Use the approved text from the latest Trust Legal Provisions 785 (TLP) document, which can be found at: 787 http://trustee.ietf.org/license-info/ 789 8. Other Issues -- check for any issues mentioned in 790 http://www.ietf.org/ID-Checklist.html that are not covered 791 elsewhere. 793 9. Technical Content -- review the actual technical content for 794 compliance with the guidelines in this document. The use of a 795 YANG module compiler is recommended when checking for syntax 796 errors; see [YANG tool URL TBD] for more information. Checking 797 for correct syntax, however, is only part of the job. It is just 798 as important to actually read the YANG module document from the 799 point of view of a potential implementor. It is particularly 800 important to check that description statements are sufficiently 801 clear and unambiguous to allow interoperable implementations to 802 be created. 804 Appendix B. YANG Module Template 806 file "ietf-template.yang" 808 module ietf-template { 810 // replace this string with a unique namespace URN value 811 namespace 812 "urn:ietf:params:xml:ns:yang:ietf-template:DRAFT-02"; 814 // replace this string, and try to pick a unique prefix 815 prefix "temp"; 817 // import statements here: e.g., 818 // import ietf-yang-types { prefix yang; } 819 // import ietf-inet-types { prefix inet; } 821 // identify the IETF working group if applicable 822 organization 823 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 825 // update this contact statement with your info 826 contact 827 "WG Web: 828 WG List: 830 WG Chair: your-WG-chair 831 833 Editor: your-name 834 "; 836 // replace the first sentence in this description statement. 837 // replace the copyright notice with the most recent 838 // version, if it has been updated since the publication 839 // of this document 840 description 841 "This module defines a template for other YANG modules. 843 Copyright (c) 2010 IETF Trust and the persons identified as 844 the document authors. All rights reserved. 846 Redistribution and use in source and binary forms, with or 847 without modification, is permitted pursuant to, and subject 848 to the license terms contained in, the Simplified BSD License 849 set forth in Section 4.c of the IETF Trust's Legal Provisions 850 Relating to IETF Documents 851 (http://trustee.ietf.org/license-info). 853 This version of this YANG module is part of RFC XXXX; see 854 the RFC itself for full legal notices."; 856 // RFC Ed.: replace XXXX with actual RFC number and remove this note 858 reference "RFC XXXX"; 860 // RFC Ed.: remove this note 861 // Note: extracted from draft-ietf-netmod-yang-usage-04.txt 863 // replace YYYY-MM-DD with a real date (year-month-day) 864 // here is an example revision date: 2009-08-12 865 revision YYYY-MM-DD { 866 description 867 "Initial version"; 868 } 870 // extension statements 872 // feature statements 874 // identity statements 876 // typedef statements 878 // grouping statements 880 // data definition statements 882 // augment statements 884 // rpc statements 886 // notification statements 888 // DO NOT put deviation statements in a published module 890 } 892 893 Figure 1 895 Appendix C. Change Log 897 C.1. Changes from 03 to 04 899 o Removed figure 1 to reduce duplication, just refer to 4741bis 900 draft. 902 o Fixed bugs and typos found in WGLC reviews. 904 o Removed some guidelines and referring to YANG draft instead of 905 duplicating YANG rules here. 907 o Changed security guidelines so they refer to the IETF Trust TLP 908 instead of MIB-specific references. 910 o Change temporary namespace guidelines so the DRAFT-XX and RFC-nnnn 911 suffix strings are not used. 913 o Changed some MIB boilerplate so it refers to YANG boilerplate 914 instead. 916 o Introduced dangling URL reference to online YANG security 917 guidelines 919 http://www.ops.ietf.org/yang-security.html 921 Text from Bert Wijnen will be completed soon and posted online, 922 and then this URL will be finalized. 924 o Moved reference for identifying the source document inside the 925 each revision statement. 927 o Removed guideline about valid XPath since YANG already requires 928 valid XPath. 930 o Added guideline that strings should not rely on preservation of 931 leading and trailing whitespace characters. 933 o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST 934 NOT to MAY use with caution. 936 o Updated the TLP text within the example module again. 938 o Reversed order of change log so most recent entries are first. 940 C.2. Changes from 02 to 03 942 o Updated figure 1 to align with 4741bis draft. 944 o Updated guidelines for import-by-revision and include-by-revision. 946 o Added file name to code begins convention in ietf-template module. 948 C.3. Changes from 01 to 02 950 o Updated figure 1 per mailing list comments. 952 o Updated suggested organization to include the working group name. 954 o Updated ietf-template.yang to use new organization statement 955 value. 957 o Updated Code Component requirements as per new TLP. 959 o Updated ietf-template.yang to use new Code Component begin and end 960 markers. 962 o Updated references to the TLP in a couple sections. 964 o Change manager/agent terminology to client/server. 966 C.4. Changes from 00 to 01 968 o Added transport 'TLS' to figure 1. 970 o Added note about RFC 2119 terminology. 972 o Corrected URL for instructions to authors. 974 o Updated namespace procedures section. 976 o Updated guidelines on module contact, reference, and organization 977 statements. 979 o Added note on use of preceding-sibling and following-sibling axes 980 in XPath expressions. 982 o Added section on temporary namespace statement values. 984 o Added section on top level database objects. 986 o Added ietf-template.yang appendix. 988 Author's Address 990 Andy Bierman 991 InterWorking Labs 993 Email: andyb@iwl.com