idnits 2.17.1 draft-ietf-netmod-yang-usage-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2010) is 5042 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '42' on line 455 ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 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 July 8, 2010 5 Expires: January 9, 2011 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-ietf-netmod-yang-usage-08 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 January 9, 2011. 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 . . . . . . . . . . . . . . . . . . . . 8 62 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 63 3.4. Security Considerations Section . . . . . . . . . . . . . 8 64 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 9 65 3.5.1. Documents that Create a New Name Space . . . . . . . . 9 66 3.5.2. Documents that Extend an Existing Name Space . . . . . 9 67 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 10 68 3.7. Intellectual Property Section . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . 17 82 4.13. Operation Definitions . . . . . . . . . . . . . . . . . . 18 83 4.14. Notification Definitions . . . . . . . . . . . . . . . . . 19 84 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 86 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 87 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 88 8.1. Normative References . . . . . . . . . . . . . . . . . . . 23 89 8.2. Informative References . . . . . . . . . . . . . . . . . . 23 90 Appendix A. Module Review Checklist . . . . . . . . . . . . . . . 24 91 Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 26 92 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 29 93 C.1. Changes from 07 to 08 . . . . . . . . . . . . . . . . . . 29 94 C.2. Changes from 06 to 07 . . . . . . . . . . . . . . . . . . 29 95 C.3. Changes from 05 to 06 . . . . . . . . . . . . . . . . . . 29 96 C.4. Changes from 04 to 05 . . . . . . . . . . . . . . . . . . 29 97 C.5. Changes from 03 to 04 . . . . . . . . . . . . . . . . . . 30 98 C.6. Changes from 02 to 03 . . . . . . . . . . . . . . . . . . 30 99 C.7. Changes from 01 to 02 . . . . . . . . . . . . . . . . . . 31 100 C.8. Changes from 00 to 01 . . . . . . . . . . . . . . . . . . 31 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 1. Introduction 105 The standardization of network configuration interfaces for use with 106 the NETCONF [RFC4741] protocol requires a modular set of data models, 107 which can be reused and extended over time. 109 This document defines a set of usage guidelines for standards track 110 documents containing YANG [I-D.ietf-netmod-yang] data models. It is 111 similar to the SMIv2 usage guidelines specification [RFC4181] in 112 intent and structure. However, since that document was written a 113 decade after SMIv2 modules had been in use, it was published as a 114 'best current practice' (BCP). This document is not a BCP, but 115 rather an informational reference, intended to promote consistency in 116 documents containing YANG modules. 118 Many YANG constructs are defined as optional to use, such as the 119 description statement. However, in order to maximize 120 interoperability of NETCONF implementations utilizing YANG data 121 models, it is desirable to define a set of usage guidelines which may 122 require a higher level of compliance than the minimum level defined 123 in the YANG specification. 125 In addition, YANG allows constructs such as infinite length 126 identifiers and string values, or top-level mandatory nodes, that a 127 compliant server is not required to support. Only constructs which 128 all servers are required to support can be used in IETF YANG modules. 130 This document defines usage guidelines related to the NETCONF 131 operations layer, and NETCONF content layer, as defined in [RFC4741]. 132 These guidelines are intended to be used by authors and reviewers to 133 improve the readability and interoperability of published YANG data 134 models. 136 2. Terminology 138 2.1. Requirements Notation 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 142 document are to be interpreted as described in [RFC2119]. 144 RFC 2119 language is used here to express the views of the NETMOD 145 working group regarding content for YANG modules. YANG modules 146 complying with this document will treat the RFC 2119 terminology as 147 if it were describing best current practices. 149 2.2. NETCONF Terms 151 The following terms are defined in [RFC4741] and are not redefined 152 here: 154 o capabilities 156 o client 158 o operation 160 o server 162 2.3. YANG Terms 164 The following terms are defined in [I-D.ietf-netmod-yang] and are not 165 redefined here: 167 o data node 169 o module 171 o namespace 173 o submodule 175 o version 177 Note that the term 'module' may be used as a generic term for a YANG 178 module or submodule. When describing properties which are specific 179 to submodules, the term 'submodule' is used instead. 181 2.4. Terms 183 The following terms are used throughout this document: 185 published: A stable release of a module or submodule, usually 186 contained in an RFC. 188 unpublished: An unstable release of a module or submodule, usually 189 contained in an Internet-Draft. 191 3. General Documentation Guidelines 193 YANG data model modules under review are likely to be contained in 194 Internet-Drafts. All guidelines for Internet-Draft authors MUST be 195 followed. These guidelines are available online at: 197 http://www.rfc-editor.org/rfc-editor/instructions2authors.txt 199 The following sections MUST be present in an Internet-Draft 200 containing a module: 202 o Narrative sections 204 o Definitions section 206 o Security Considerations section 208 o IANA Considerations section 210 o References section 212 3.1. Module Copyright 214 The module description statement MUST contain a reference to the 215 latest approved IETF Trust Copyright statement, which is available 216 on-line at: 218 http://trustee.ietf.org/license-info/ 220 Each YANG module or submodule contained within an Internet-Draft or 221 RFC is considered to be a code component. The strings '' and '' MUST be used to identify each code 223 component. 225 The '' tag SHOULD be followed by a string identifying 226 the file name specified in section 5.2 of [I-D.ietf-netmod-yang]. 227 The following example is for the '2010-01-18' revision of the 'ietf- 228 foo' module: 230 file "ietf-foo@2010-01-18.yang" 231 module ietf-foo { 232 // ... 233 revision 2010-01-18 { 234 description "Latest revision"; 235 reference "RFC XXXXX"; 236 } 237 // ... 238 } 239 241 Figure 1 243 3.2. Narrative Sections 245 The narrative part MUST include an overview section that describes 246 the scope and field of application of the module(s) defined by the 247 specification and that specifies the relationship (if any) of these 248 modules to other standards, particularly to standards containing 249 other YANG modules. The narrative part SHOULD include one or more 250 sections to briefly describe the structure of the modules defined in 251 the specification. 253 If the module(s) defined by the specification import definitions from 254 other modules (except for those defined in the YANG 255 [I-D.ietf-netmod-yang] or YANG Types [I-D.ietf-netmod-yang-types] 256 documents), or are always implemented in conjunction with other 257 modules, then those facts MUST be noted in the overview section, as 258 MUST be noted any special interpretations of definitions in other 259 modules. 261 3.3. Definitions Section 263 This section contains the module(s) defined by the specification. 264 These modules MUST be written using the YANG syntax defined in 265 [I-D.ietf-netmod-yang]. A YIN syntax version of the module MAY also 266 be present in the document. There MAY also be other types of modules 267 present in the document, such as SMIv2, which are not affected by 268 these guidelines. 270 See Section 4 for guidelines on YANG usage. 272 3.4. Security Considerations Section 274 Each specification that defines one or more modules MUST contain a 275 section that discusses security considerations relevant to those 276 modules. This section MUST be patterned after the latest approved 277 template (available at 278 http://www.ops.ietf.org/netconf/yang-security-considerations.txt). 280 In particular: 282 o Writable data nodes that could be especially disruptive if abused 283 MUST be explicitly listed by name and the associated security 284 risks MUST be explained. 286 o Readable data nodes that contain especially sensitive information 287 or that raise significant privacy concerns MUST be explicitly 288 listed by name and the reasons for the sensitivity/privacy 289 concerns MUST be explained. 291 o Operations (i.e., 'rpc' statements) which are potentially harmful 292 to system behavior or that raise significant privacy concerns MUST 293 be explicitly listed by name and the reasons for the sensitivity/ 294 privacy concerns MUST be explained. 296 3.5. IANA Considerations Section 298 In order to comply with IESG policy as set forth in 299 http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is 300 submitted to the IESG for publication which has action items for IANA 301 MUST contain an IANA Considerations section. The requirements for 302 this section vary depending what actions are required of the IANA. 303 If there are no IANA considerations applicable to the document, then 304 the IANA Considerations section is not required. Refer to the 305 guidelines in [RFC5226] for more details. 307 3.5.1. Documents that Create a New Name Space 309 If an Internet-Draft defines a new name space that is to be 310 administered by the IANA, then the document MUST include an IANA 311 Considerations section, that specifies how the name space is to be 312 administered. 314 Specifically, if any YANG module namespace statement value contained 315 in the document is not already registered with IANA, then a new YANG 316 Namespace registry entry MUST be requested from the IANA. The YANG 317 specification includes the procedure for this purpose in its IANA 318 Considerations section. 320 3.5.2. Documents that Extend an Existing Name Space 322 It is possible to extend an existing namespace using a YANG submodule 323 which belongs to an existing module already administered by IANA. In 324 this case, the document containing the main module MUST be updated to 325 use the latest revision of the submodule. 327 3.6. Reference Sections 329 For every import or include statement which appears in a module 330 contained in the specification, which identifies a module in a 331 separate document, a corresponding normative reference to that 332 document MUST appear in the Normative References section. The 333 reference MUST correspond to the specific module version actually 334 used within the specification. 336 For every normative reference statement which appears in a module 337 contained in the specification, which identifies a separate document, 338 a corresponding normative reference to that document SHOULD appear in 339 the Normative References section. The reference SHOULD correspond to 340 the specific document version actually used within the specification. 341 If the reference statement identifies an informative reference, which 342 identifies a separate document, a corresponding informative reference 343 to that document MAY appear in the Informative References section. 345 3.7. Intellectual Property Section 347 The proper IPR statements MUST be present in the document, according 348 to the most current Internet-Draft boilerplate. Refer to the IETF 349 Trust Legal Provision for the exact legal text that needs to be 350 included. 352 4. YANG Usage Guidelines 354 In general, modules in IETF standards-track specifications MUST 355 comply with all syntactic and semantic requirements of YANG. 356 [I-D.ietf-netmod-yang]. The guidelines in this section are intended 357 to supplement the YANG specification, which is intended to define a 358 minimum set of conformance requirements. 360 In order to promote interoperability and establish a set of practices 361 based on previous experience, the following sections establish usage 362 guidelines for specific YANG constructs. 364 Only guidelines which clarify or restrict the minimum conformance 365 requirements are included here. 367 4.1. Module Naming Conventions 369 Modules contained in standards track documents SHOULD be named 370 according to the guidelines in the IANA considerations section of 371 [I-D.ietf-netmod-yang]. 373 A distinctive word or acronym (e.g., protocol name or working group 374 acronym) SHOULD be used in the module name. If new definitions are 375 being defined to extend one or more existing modules, then the same 376 word or acronym should be reused, instead of creating a new one. 378 All published module names MUST be unique. 380 Once a module name is published, it MUST NOT be reused, even if the 381 RFC containing the module is reclassified to 'Historic' status. 383 4.2. Identifiers 385 Identifiers for all YANG identifiers in published modules MUST be 386 between 1 and 64 characters in length. These include any construct 387 specified as an 'identifier-arg-str' token in the ABNF in section 12 388 of [I-D.ietf-netmod-yang]. 390 4.3. Defaults 392 In general, it is suggested that sub-statements containing very 393 common default values SHOULD NOT be present. The following sub- 394 statements are commonly used with the default value, which would make 395 the module difficult to read if used everywhere they are allowed. 397 +---------------+---------------+ 398 | Statement | Default Value | 399 +---------------+---------------+ 400 | config | true | 401 | | | 402 | mandatory | false | 403 | | | 404 | max-elements | unbounded | 405 | | | 406 | min-elements | 0 | 407 | | | 408 | ordered-by | system | 409 | | | 410 | status | current | 411 | | | 412 | yin-element | false | 413 +---------------+---------------+ 415 4.4. Conditional Statements 417 A module may be conceptually partitioned in several ways, using the 418 'if-feature' and/or 'when' statements. 420 Data model designers need to carefully consider all modularity 421 aspects, including the use of YANG conditional statements. 423 If a data definition is optional, depending on server support for a 424 NETCONF protocol capability, then a YANG 'feature' statement SHOULD 425 be defined to indicate the NETCONF capability is supported within the 426 data model. 428 4.5. XPath Usage 430 This section describes guidelines for using the XML Path Language 431 [W3C.REC-xpath-19991116] (XPath) within YANG modules. 433 The 'attribute' and 'namespace' axes are not supported in YANG, and 434 MAY be empty in a NETCONF server implementation. 436 The 'position' and 'last' functions MAY be used with caution. A 437 server is not required to maintain any particular XML document order 438 for system-ordered data nodes. A server is only required to maintain 439 the relative XML document order of all instances of a particular 440 user-ordered list or leaf-list. 442 The 'preceding', and 'following' axes SHOULD NOT be used. These 443 constructs rely on XML document order within a NETCONF server 444 configuration database, which may not be supported consistently or 445 produce reliable results across implementations. Predicate 446 expressions based on static node properties (e.g., name, value, 447 ancestors, descendants) SHOULD be used instead. 449 The 'preceding-sibling' and 'following-sibling' axes MAY be used, 450 with caution. A server is not required to maintain a persistent or 451 deterministic XML document order, which will affect use of these 452 axes. 454 Implicit 'position' function calls within predicates MAY be used with 455 caution. (e.g., //chapter[42]). Note that a NETCONF server is only 456 required to maintain relative document order for related instances of 457 a user-ordered list or leaf-list data definition (i.e., 'ordered-by' 458 statement set to 'user'). 460 Data nodes which use the 'int64' and 'uint64' built-in type MAY be 461 used with caution, within relational expressions. There are boundary 462 conditions in which the translation from the YANG 64-bit type to an 463 XPath number can cause incorrect results. Specifically, an XPath 464 double precision floating point number cannot represent very large 465 positive or negative 64-bit numbers because it only provides a total 466 precision of 53 bits. 468 Data modelers need to be careful not to confuse the YANG value space 469 and the XPath value space. The data types are not the same in both, 470 and conversion between YANG and XPath data types SHOULD be considered 471 carefully. 473 Explicit XPath data type conversions MAY be used (e.g., 'string', 474 'boolean', or 'number' functions), instead of implicit XPath data 475 type conversions. 477 4.6. Lifecycle Management 479 The status statement MUST be present if its value is 'deprecated' or 480 'obsolete'. 482 The module or submodule name MUST NOT be changed, once the document 483 containing the module or submodule is published. 485 The module namespace URI value MUST NOT be changed, once the document 486 containing the module is published. 488 The revision-date sub-statement within the imports statement SHOULD 489 be present if any groupings are used from the external module. 491 The revision-date sub-statement within the include statement SHOULD 492 be present if any groupings are used from the external sub-module. 494 If submodules are used, then the document containing the main module 495 MUST be updated so that the main module revision date is equal or 496 more recent than the revision date of any submodule which is 497 (directly or indirectly) included by the main module. 499 4.7. Module Header, Meta, and Revision Statements 501 For published modules, the namespace MUST be a globally unique URI, 502 as defined in [RFC3986]. This value is usually assigned by the IANA. 504 The organization statement MUST be present. If the module is 505 contained in a documented intended for standards-track status, then 506 the organization SHOULD be the IETF working group chartered to write 507 the document. 509 The contact statement MUST be present. If the module is contained in 510 a document intended for standards-track status, then the working 511 group WEB and mailing information MUST be present, and the main 512 document author or editor contact information SHOULD be present. If 513 additional authors or editors exist, their contact information MAY be 514 present. In addition, the Area Director and other contact 515 information MAY be present. 517 The description statement MUST be present. The appropriate IETF 518 Trust Copyright text MUST be present, as described in Section 3.1. 520 If the module relies on information contained in other documents, 521 which are not the same documents implied by the import statements 522 present in the module, then these documents MUST be identified in the 523 reference statement. 525 A revision statement MUST be present for each published version of 526 the module. The revision statement MUST have a reference 527 substatement. It MUST identify the published document which contains 528 the module. Modules are often extracted from their original 529 documents and it is useful for developers and operators to know how 530 to find the original source document in a consistent manner. The 531 revision statement MAY have a description substatement. 533 Each new revision MUST include a revision date which is higher than 534 any other revision date in the module. 536 It is acceptable to reuse the same revision statement within 537 unpublished versions (i.e., Internet-Drafts), but the revision date 538 MUST be updated to a higher value each time the Internet-Draft is re- 539 published. 541 4.8. Namespace Assignments 543 It is RECOMMENDED that only valid YANG modules are included in 544 documents, whether they are published yet or not. This allows: 546 o the module to compile correctly instead of generating disruptive 547 fatal errors. 549 o early implementors to use the modules without picking a random 550 value for the XML namespace. 552 o early interoperability testing since independent implementations 553 will use the same XML namespace value. 555 Until a URI is assigned by the IANA, a proposed namespace URI MUST be 556 provided for the namespace statement in a YANG module. A value 557 SHOULD be selected which is not likely to collide with other YANG 558 namespaces. Standard module names, prefixes, and URI strings already 559 listed in the YANG Module Registry MUST NOT be used. 561 A standard namespace statement value SHOULD have the following form: 563 : 565 The following URN prefix string SHOULD be used for published and 566 unpublished YANG modules: 568 urn:ietf:params:xml:ns:yang: 570 The following example URNs would be valid temporary namespace 571 statement values for standards-track modules: 573 urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock 575 urn:ietf:params:xml:ns:yang:ietf-netconf-state 577 urn:ietf:params:xml:ns:yang:ietf-netconf 579 Note that a different URN prefix string SHOULD be used for non- 580 standards track modules. The string SHOULD be selected according to 581 the guidelines in [I-D.ietf-netmod-yang]. 583 The following examples of non-standards track modules are only 584 suggestions. There are no guidelines for this type of URN in this 585 document: 587 http://example.com/ns/example-interfaces 588 http://example.com/ns/example-system 590 4.9. Top Level Data Definitions 592 There SHOULD only be one top-level data node defined in each YANG 593 module, if any data nodes are defined at all. 595 The top-level data organization SHOULD be considered carefully, in 596 advance. Data model designers need to consider how the functionality 597 for a given protocol or protocol family will grow over time. 599 The names and data organization SHOULD reflect persistent 600 information, such as the name of a protocol. The name of the working 601 group SHOULD NOT be used because this may change over time. 603 A mandatory database data definition is defined as a node that a 604 client must provide for the database to be valid. The server is not 605 required to provide a value. 607 Top-level database data definitions MUST NOT be mandatory. If a 608 mandatory node appears at the top-level, it will immediately cause 609 the database to be invalid. This can occur when the server boots or 610 when a module is loaded dynamically at runtime. 612 4.10. Data Types 614 Selection of an appropriate data type (i.e., built-in type, existing 615 derived type, or new derived type) is very subjective and therefore 616 few requirements can be specified on that subject. 618 Data model designers SHOULD use the most appropriate built-in data 619 type for the particular application. 621 If extensibility of enumerated values is required, then the 622 identityref data type SHOULD be used instead of an enumeration or 623 other built-in type. 625 For string data types, if a machine-readable pattern can be defined 626 for the desired semantics, then one or more pattern statements SHOULD 627 be present. 629 For string data types, if the length of the string is required to be 630 bounded in all implementations, then a length statement MUST be 631 present. 633 For numeric data types, if the values allowed by the intended 634 semantics are different than those allowed by the unbounded intrinsic 635 data type (e.g., int32), then a range statement SHOULD be present. 637 The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 638 'int64') SHOULD NOT be used unless negative values are allowed for 639 the desired semantics. 641 For enumeration or bits data types, the semantics for each enum or 642 bit SHOULD be documented. A separate description statement (within 643 each enum or bit statement) SHOULD be present. 645 4.11. Reusable Type Definitions 647 If an appropriate derived type exists in any standard module, such as 648 [I-D.ietf-netmod-yang-types], then it SHOULD be used instead of 649 defining a new derived type. 651 If an appropriate units identifier can be associated with the desired 652 semantics, then a units statement SHOULD be present. 654 If an appropriate default value can be associated with the desired 655 semantics, then a default statement SHOULD be present. 657 If a significant number of derived types are defined, and it is 658 anticipated that these data types will be reused by multiple modules, 659 then these derived types SHOULD be contained in a separate module or 660 submodule, to allow easier reuse without unnecessary coupling. 662 The description statement MUST be present. 664 If the type definition semantics are defined in an external document 665 (other than another YANG module indicated by an import statement), 666 then the reference statement MUST be present. 668 4.12. Data Definitions 670 The description statement MUST be present in the following YANG 671 statements: 673 o anyxml 675 o augment 677 o choice 679 o container 681 o extension 683 o feature 684 o grouping 686 o identity 688 o leaf 690 o leaf-list 692 o list 694 o notification 696 o rpc 698 o typedef 700 If the data definition semantics are defined in an external document, 701 (other than another YANG module indicated by an import statement), 702 then a reference statement MUST be present. 704 The 'anyxml' construct MAY be used with caution within configuration 705 data. This may be useful to represent an HTML banner containing 706 markup elements, such as and . However, this construct 707 SHOULD NOT be used if other YANG data node types can be used instead 708 to represent the desired syntax and semantics. 710 If there are referential integrity constraints associated with the 711 desired semantics that can be represented with XPath, then one or 712 more must statements SHOULD be present. 714 For list and leaf-list data definitions, if the number of possible 715 instances is required to be bounded for all implementations, then the 716 max-elements statements SHOULD be present. 718 If any must or when statements are used within the data definition, 719 then the data definition description statement SHOULD describe the 720 purpose of each one. 722 4.13. Operation Definitions 724 If the operation semantics are defined in an external document (other 725 than another YANG module indicated by an import statement), then a 726 reference statement MUST be present. 728 If the operation impacts system behavior in some way, it SHOULD be 729 mentioned in the description statement. 731 If the operation is potentially harmful to system behavior in some 732 way, it MUST be mentioned in the Security Considerations section of 733 the document. 735 4.14. Notification Definitions 737 The description statement MUST be present. 739 If the notification semantics are defined in an external document 740 (other than another YANG module indicated by an import statement), 741 then a reference statement MUST be present. 743 5. IANA Considerations 745 This document registers one URI in the IETF XML registry [RFC3688]. 746 The following registration is requested: 748 URI: urn:ietf:params:xml:ns:yang:ietf-template 750 Registrant Contact: The NETMOD WG of the IETF. 752 XML: N/A, the requested URI is an XML namespace. 754 This document requests the following assignment in the YANG Module 755 Names Registry for the YANG module template in Appendix B. 757 +---------------+-------------------------------------------+ 758 | Field | Value | 759 +---------------+-------------------------------------------+ 760 | name | ietf-template | 761 | | | 762 | namespace | urn:ietf:params:xml:ns:yang:ietf-template | 763 | | | 764 | prefix | temp | 765 | | | 766 | reference | RFCXXXX | 767 +---------------+-------------------------------------------+ 769 6. Security Considerations 771 This document defines documentation guidelines for NETCONF content 772 defined with the YANG data modeling language. The guidelines for how 773 to write a Security Considerations section for a YANG module are 774 defined in the online document 776 http://www.ops.ietf.org/netconf/yang-security-considerations.txt 778 This document does not introduce any new or increased security risks 779 into the management system. 781 7. Acknowledgments 783 The structure and contents of this document are adapted from 784 Guidelines for MIB Documents [RFC4181], by C. M. Heard. 786 The working group thanks Martin Bjorklund and Juergen Schoenwaelder 787 for their extensive reviews and contributions to this document. 789 8. References 791 8.1. Normative References 793 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 794 Requirement Levels", BCP 14, RFC 2119, March 1997. 796 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 797 January 2004. 799 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 800 Resource Identifier (URI): Generic Syntax", STD 66, 801 RFC 3986, January 2005. 803 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 804 December 2006. 806 [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide 807 to the IETF Trust", BCP 78, RFC 5378, November 2008. 809 [W3C.REC-xpath-19991116] 810 DeRose, S. and J. Clark, "XML Path Language (XPath) 811 Version 1.0", World Wide Web Consortium 812 Recommendation REC-xpath-19991116, November 1999, 813 . 815 [I-D.ietf-netmod-yang] 816 Bjorklund, M., "YANG - A data modeling language for the 817 Network Configuration Protocol (NETCONF)", 818 draft-ietf-netmod-yang-13 (work in progress), June 2010. 820 [I-D.ietf-netmod-yang-types] 821 Schoenwaelder, J., "Common YANG Data Types", 822 draft-ietf-netmod-yang-types-09 (work in progress), 823 April 2010. 825 8.2. Informative References 827 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 828 Documents", BCP 111, RFC 4181, September 2005. 830 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 831 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 832 May 2008. 834 Appendix A. Module Review Checklist 836 This section is adapted from RFC 4181. 838 The purpose of a YANG module review is to review the YANG module both 839 for technical correctness and for adherence to IETF documentation 840 requirements. The following checklist may be helpful when reviewing 841 a draft document: 843 1. I-D Boilerplate -- verify that the draft contains the required 844 Internet-Draft boilerplate (see 845 http://www.ietf.org/ietf/1id-guidelines.txt), including the 846 appropriate statement to permit publication as an RFC, and that 847 I-D boilerplate does not contain references or section numbers. 849 2. Abstract -- verify that the abstract does not contain references, 850 that it does not have a section number, and that its content 851 follows the guidelines in 852 http://www.ietf.org/ietf/1id-guidelines.txt. 854 3. IETF Trust Copyright -- verify that the draft has the appropriate 855 text regarding the rights that document contributers provide to 856 the IETF Trust [RFC5378]. Some guidelines related to this 857 requirement are described in Section 3.1. The IETF Trust license 858 policy (TLP) can be found at: 860 http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf 862 4. Security Considerations Section -- verify that the draft uses the 863 latest approved template from the OPS area web site (http:// 864 www.ops.ietf.org/netconf/yang-security-considerations.txt) and 865 that the guidelines therein have been followed. 867 5. IANA Considerations Section -- this section must always be 868 present. For each module within the document, ensure that the 869 IANA Considerations section contains entries for the following 870 IANA registries: 872 XML Namespace Registry: Register the YANG module namespace. 874 YANG Module Registry: Register the YANG module name, prefix, 875 namespace, and RFC number, according to the rules specified in 876 [I-D.ietf-netmod-yang]. 878 6. References -- verify that the references are properly divided 879 between normative and informative references, that RFC 2119 is 880 included as a normative reference if the terminology defined 881 therein is used in the document, that all references required by 882 the boilerplate are present, that all YANG modules containing 883 imported items are cited as normative references, and that all 884 citations point to the most current RFCs unless there is a valid 885 reason to do otherwise (for example, it is OK to include an 886 informative reference to a previous version of a specification to 887 help explain a feature included for backward compatibility). Be 888 sure citations for all imported modules are present somewhere in 889 the document text (outside the YANG module). 891 7. Copyright Notices -- verify that the draft contains an 892 abbreviated IETF Trust copyright notice in the description 893 statement of each YANG module or sub-module, and that it contains 894 the full IETF Trust copyright notice at the end of the document. 895 Make sure that the correct year is used in all copyright dates. 896 Use the approved text from the latest Trust Legal Provisions 897 (TLP) document, which can be found at: 899 http://trustee.ietf.org/license-info/ 901 8. Other Issues -- check for any issues mentioned in 902 http://www.ietf.org/ID-Checklist.html that are not covered 903 elsewhere. 905 9. Technical Content -- review the actual technical content for 906 compliance with the guidelines in this document. The use of a 907 YANG module compiler is recommended when checking for syntax 908 errors. A list of freely available tools and other information 909 can be found at: 911 http://trac.tools.ietf.org/wg/netconf/trac/wiki 913 Checking for correct syntax, however, is only part of the job. 914 It is just as important to actually read the YANG module document 915 from the point of view of a potential implementor. It is 916 particularly important to check that description statements are 917 sufficiently clear and unambiguous to allow interoperable 918 implementations to be created. 920 Appendix B. YANG Module Template 922 file "ietf-template@2010-05-18.yang" 924 module ietf-template { 926 // replace this string with a unique namespace URN value 927 namespace 928 "urn:ietf:params:xml:ns:yang:ietf-template"; 930 // replace this string, and try to pick a unique prefix 931 prefix "temp"; 933 // import statements here: e.g., 934 // import ietf-yang-types { prefix yang; } 935 // import ietf-inet-types { prefix inet; } 937 // identify the IETF working group if applicable 938 organization 939 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 941 // update this contact statement with your info 942 contact 943 "WG Web: 944 WG List: 946 WG Chair: your-WG-chair 947 949 Editor: your-name 950 "; 952 // replace the first sentence in this description statement. 953 // replace the copyright notice with the most recent 954 // version, if it has been updated since the publication 955 // of this document 956 description 957 "This module defines a template for other YANG modules. 959 Copyright (c) 2010 IETF Trust and the persons identified as 960 the document authors. All rights reserved. 962 Redistribution and use in source and binary forms, with or 963 without modification, is permitted pursuant to, and subject 964 to the license terms contained in, the Simplified BSD License 965 set forth in Section 4.c of the IETF Trust's Legal Provisions 966 Relating to IETF Documents 967 (http://trustee.ietf.org/license-info). 969 This version of this YANG module is part of RFC XXXX; see 970 the RFC itself for full legal notices."; 972 // RFC Ed.: replace XXXX with actual RFC number and remove this note 974 reference "RFC XXXX"; 976 // RFC Ed.: remove this note 977 // Note: extracted from draft-ietf-netmod-yang-usage-04.txt 979 // replace '2010-05-18' with the module publication date 980 // The format is (year-month-day) 981 revision "2010-05-18" { 982 description 983 "Initial version"; 984 } 986 // extension statements 988 // feature statements 990 // identity statements 992 // typedef statements 994 // grouping statements 996 // data definition statements 998 // augment statements 1000 // rpc statements 1002 // notification statements 1004 // DO NOT put deviation statements in a published module 1006 } 1008 1009 Figure 2 1011 Appendix C. Change Log 1013 C.1. Changes from 07 to 08 1015 o Corrected YANG security considerations URL. 1017 o Expanded 'CODE BEGINS' example. 1019 o Added RPC operations to the security considerations guidelines 1020 section. 1022 o Removed guideline about leading and trailing whitespace. 1024 C.2. Changes from 06 to 07 1026 o Corrected title change bug; supposed to be page header instead. 1028 o Fixed typos added to last revision. 1030 o Added sentence to checklist to make sure text outside module 1031 contains citations for imports. 1033 C.3. Changes from 05 to 06 1035 o Several clarifications and corrections, based on the AD review by 1036 Dan Romascanu. 1038 C.4. Changes from 04 to 05 1040 o Changed 'object' terminology to 'data definition'. 1042 o Put XPath guidelines in separate section. 1044 o Clarified XPath usage for XML document order dependencies. 1046 o Updated guidelines to current conventions. 1048 o Added informative reference for IANA considerations guidelines and 1049 XML registry. 1051 o Updated IANA Considerations section to reserve the ietf-template 1052 module in the YANG Module Name Registry so it cannot be reused 1053 accidently. 1055 o Many other clarifications and fixed typos found in WGLC reviews. 1057 C.5. Changes from 03 to 04 1059 o Removed figure 1 to reduce duplication, just refer to 4741bis 1060 draft. 1062 o Fixed bugs and typos found in WGLC reviews. 1064 o Removed some guidelines and referring to YANG draft instead of 1065 duplicating YANG rules here. 1067 o Changed security guidelines so they refer to the IETF Trust TLP 1068 instead of MIB-specific references. 1070 o Change temporary namespace guidelines so the DRAFT-XX and RFC-nnnn 1071 suffix strings are not used. 1073 o Changed some MIB boilerplate so it refers to YANG boilerplate 1074 instead. 1076 o Introduced dangling URL reference to online YANG security 1077 guidelines 1079 http://www.ops.ietf.org/yang-security.html 1081 [ed.: Text from Bert Wijnen will be completed soon and posted 1082 online, and then this URL will be finalized.] 1084 o Moved reference for identifying the source document inside the 1085 each revision statement. 1087 o Removed guideline about valid XPath since YANG already requires 1088 valid XPath. 1090 o Added guideline that strings should not rely on preservation of 1091 leading and trailing whitespace characters. 1093 o Relaxed some XPath and anyxml guidelines from SHOULD NOT or MUST 1094 NOT to MAY use with caution. 1096 o Updated the TLP text within the example module again. 1098 o Reversed order of change log so most recent entries are first. 1100 C.6. Changes from 02 to 03 1102 o Updated figure 1 to align with 4741bis draft. 1104 o Updated guidelines for import-by-revision and include-by-revision. 1106 o Added file name to code begins convention in ietf-template module. 1108 C.7. Changes from 01 to 02 1110 o Updated figure 1 per mailing list comments. 1112 o Updated suggested organization to include the working group name. 1114 o Updated ietf-template.yang to use new organization statement 1115 value. 1117 o Updated Code Component requirements as per new TLP. 1119 o Updated ietf-template.yang to use new Code Component begin and end 1120 markers. 1122 o Updated references to the TLP in a couple sections. 1124 o Change manager/agent terminology to client/server. 1126 C.8. Changes from 00 to 01 1128 o Added transport 'TLS' to figure 1. 1130 o Added note about RFC 2119 terminology. 1132 o Corrected URL for instructions to authors. 1134 o Updated namespace procedures section. 1136 o Updated guidelines on module contact, reference, and organization 1137 statements. 1139 o Added note on use of preceding-sibling and following-sibling axes 1140 in XPath expressions. 1142 o Added section on temporary namespace statement values. 1144 o Added section on top level database objects. 1146 o Added ietf-template.yang appendix. 1148 Author's Address 1150 Andy Bierman 1151 InterWorking Labs 1153 Email: andyb@iwl.com