idnits 2.17.1 draft-bierman-netmod-yang-usage-00.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 (January 23, 2009) is 5572 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 606, but not defined -- Looks like a reference, but probably isn't: '42' on line 413 ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-03 == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-types-01 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 Netconf Central 4 Intended status: BCP January 23, 2009 5 Expires: July 27, 2009 7 Guidelines for Authors and Reviewers of YANG Data Model Documents 8 draft-bierman-netmod-yang-usage-00 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on July 27, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. 45 Abstract 47 This memo provides guidelines for authors and reviewers of standards 48 track specifications containing YANG data model modules. Applicable 49 portions may be used as a basis for reviews of other YANG data model 50 documents. Recommendations and procedures are defined, which are 51 intended to increase interoperability and usability of NETCONF 52 implementations which utilize YANG data model modules. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 59 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 60 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 61 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3. General Documentation Guidelines . . . . . . . . . . . . . . . 7 63 3.1. YANG Data Model Boilerplate Section . . . . . . . . . . . 7 64 3.2. Narrative Sections . . . . . . . . . . . . . . . . . . . . 7 65 3.3. Definitions Section . . . . . . . . . . . . . . . . . . . 8 66 3.4. Security Considerations Section . . . . . . . . . . . . . 8 67 3.5. IANA Considerations Section . . . . . . . . . . . . . . . 8 68 3.5.1. Documents that Create a New Name Space . . . . . . . . 8 69 3.5.2. Documents that Extend an Existing Name Space . . . . . 9 70 3.6. Reference Sections . . . . . . . . . . . . . . . . . . . . 9 71 3.7. Copyright Notices . . . . . . . . . . . . . . . . . . . . 9 72 3.8. Intellectual Property Section . . . . . . . . . . . . . . 9 73 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 10 74 4.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 4.3. Conditional Statements . . . . . . . . . . . . . . . . . . 10 77 4.4. Header Contents . . . . . . . . . . . . . . . . . . . . . 11 78 4.5. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 12 79 4.6. Object Definitions . . . . . . . . . . . . . . . . . . . . 13 80 4.7. RPC Definitions . . . . . . . . . . . . . . . . . . . . . 13 81 4.8. Notification Definitions . . . . . . . . . . . . . . . . . 14 82 5. YANG Module Registry . . . . . . . . . . . . . . . . . . . . . 15 83 5.1. YANG Registry Data Model . . . . . . . . . . . . . . . . . 16 84 5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 18 85 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 86 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 87 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24 90 9.2. Informative References . . . . . . . . . . . . . . . . . . 24 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 93 1. Introduction 95 The standardization of network configuration interfaces for use with 96 the NETCONF [RFC4741] protocol requires a modular set of data models, 97 which can be reused and extended over time. 99 This document defines a set of usage guidelines for standards track 100 documents containing YANG [I-D.ietf-netmod-yang] data models. It is 101 similar to the MIB usage guidelines specification [RFC4181] in intent 102 and structure. 104 Many YANG constructs are defined as optional to use, such as the 105 description clause. However, in order to maximize interoperability 106 of NETCONF implementations utilizing YANG data models, it is 107 desirable to define a set of usage guidelines which may require a 108 higher level of compliance than the minimum level defined in the YANG 109 specification. 111 A new IANA registry is needed to support YANG. This registry will 112 allow YANG module namespace and other definitions to be centrally 113 located, minimizing name collisions, and providing an authoritative 114 status of each YANG module. 116 The YANG Module Registry will support YANG modules, as well as YANG 117 submodules which utilize a 'virtual' module definition. A virtual 118 module contains only the module header, submodule include statements, 119 and meta statements. The Submodule Registration procedure [ed: IANA 120 procedure TBD] is used to publish specifications containing YANG 121 submodules which extend a virtual module. This procedure allows the 122 main module revision statement and include statement to be updated, 123 without requiring publication or a separate RFC to contain the main 124 module. Refer to Section 5 for more details. 126 The NETCONF stack can be conceptually partitioned into four layers. 128 Layer Example 129 +-------------+ +--------------------+ +-------------------+ 130 (4) | Content | | Configuration data | | Notification data | 131 +-------------+ +--------------------+ +-------------------+ 132 | | | 133 +-------------+ +-----------------+ +---------------+ 134 (3) | Operations | | | | | 135 +-------------+ +-----------------+ +---------------+ 136 | | | 137 +-------------+ +--------------------+ +----------------+ 138 (2) | RPC | | , | | | 139 +-------------+ +--------------------+ +----------------+ 140 | | | 141 +-------------+ +-----------------------------+ 142 (1) | Transport | | BEEP, SSH, SSL, console | 143 | Protocol | | | 144 +-------------+ +-----------------------------+ 146 Figure 1 148 This document defines usage guidelines related to the NETCONF 149 operations layer (3), and NETCONF content layer (4). 151 It also contains a definition for a registry for YANG Modules, which 152 can be used to locate documents which contain standards-track modules 153 or submodules. 155 2. Terminology 157 2.1. Requirements Notation 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 161 document are to be interpreted as described in [RFC2119]. 163 2.2. NETCONF Terms 165 The following terms are defined in [RFC4741] and are not redefined 166 here: 168 o agent 170 o application 172 o capabilities 174 o manager 176 o operation 178 o RPC 180 2.3. YANG Terms 182 The following terms are defined in [I-D.ietf-netmod-yang] and are not 183 redefined here: 185 o data node 187 o module 189 o submodule 191 o namespace 193 o version 195 2.4. Terms 197 The following terms are used throughout this document: 199 o YAM: Shorthand term for a YANG data model module or submodule, 200 used for properties which apply to both modules and submodules. 201 When describing properties which are specific to modules, the term 202 'YANG module', or simply 'module', is used instead. When 203 describing properties which are specific to submodules, the term 204 'YANG submodule', or simply 'module' is used instead. 206 o Published Document: A stable release of a YAM, usually contained 207 in an RFC. 209 o Unpublished Document: An unstable release of a YAM, usually 210 contained in an Internet Draft. 212 o Virtual Module: A YANG module which does not contain any body 213 statements, and is maintained in a registry. The body statements 214 are defined in submodules, in one or more documents, and 215 'included' in the main module via a registry entry for the main 216 module. 218 3. General Documentation Guidelines 220 YANG data model modules (YAMs) under review are likely to be 221 contained in Internet Drafts. All guidelines for Internet Draft 222 authors MUST be followed. These guidelines are available online at: 224 http://www.isi.edu/in-notes/rfc-editor/instructions2authors.txt 226 The following sections MUST be present in an Internet Draft 227 containing a YAM: 229 o YANG data model boilerplate section 231 o Narrative sections 233 o Definitions section 235 o Security Considerations section 237 o IANA Considerations section 239 o References section 241 3.1. YANG Data Model Boilerplate Section 243 This section MUST contain a verbatim copy of the latest approved 244 Internet-Standard Management Framework boilerplate, which is 245 available on-line at [ed: URL TBD]. 247 3.2. Narrative Sections 249 The narrative part MUST include an overview section that describes 250 the scope and field of application of the YAM(s) defined by the 251 specification and that specifies the relationship (if any) of these 252 YAMs to other standards, particularly to standards containing other 253 YAM modules. The narrative part SHOULD include one or more sections 254 to briefly describe the structure of the YAMs defined in the 255 specification. 257 If the YAM(s) defined by the specification import definitions from 258 other YAMs (except for those defined in the YANG 259 [I-D.ietf-netmod-yang] or YANG Types [I-D.ietf-netmod-yang-types] 260 documents) or are always implemented in conjunction with other YAMs, 261 then those facts MUST be noted in the overview section, as MUST any 262 special interpretations of objects in other YAMs. 264 3.3. Definitions Section 266 This section contains the YAM(s) defined by the specification. These 267 modules MUST be written in YANG [I-D.ietf-netmod-yang]. 269 See Section 4 for guidelines on YANG usage. 271 3.4. Security Considerations Section 273 Each specification that defines one or more YAMs MUST contain a 274 section that discusses security considerations relevant to those 275 modules. This section MUST be patterned after the latest approved 276 template (available at [ed: URL TBD]). 278 In particular, writable YAM objects that could be especially 279 disruptive if abused MUST be explicitly listed by name and the 280 associated security risks MUST be spelled out; similarly, readable 281 YAM objects that contain especially sensitive information or that 282 raise significant privacy concerns MUST be explicitly listed by name 283 and the reasons for the sensitivity/privacy concerns MUST be 284 explained. 286 3.5. IANA Considerations Section 288 In order to comply with IESG policy as set forth in 289 http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is 290 submitted to the IESG for publication MUST contain an IANA 291 Considerations section. The requirements for this section vary 292 depending what actions are required of the IANA. 294 Refer to [TBD] for details on the structure of the YANG registries 295 maintained by the IANA. 297 3.5.1. Documents that Create a New Name Space 299 If an Internet-Draft defines a new name space that is to be 300 administered by the IANA, then the document MUST include an IANA 301 Considerations section, specifies how the name space is to be 302 administered. 304 Specifically, if any YANG module namespace statement value contained 305 in the document is not already registered with IANA, then a new YANG 306 Namespace registry entry must be requested from the IANA [ed: 307 procedure TBD]. 309 3.5.2. Documents that Extend an Existing Name Space 311 If an Internet-Draft defines any extensions to a YANG Namespace 312 already administered by the IANA, then the document MUST include an 313 IANA Considerations section, specifies how the name space extension 314 is to be administered. 316 Specifically, if any YANG submodule belongs-to value contained in the 317 document is associated with a module that contains a namespace 318 statement value equal to a YANG Namespace already administered by the 319 IANA, then a new YANG Module registry entry and YANG Namespace Update 320 Procedure must be requested from the IANA [ed: procedure TBD]. 322 3.6. Reference Sections 324 [ed: 2223bis text TBD] 326 For every import or include statement which appears in a YAM 327 contained in the specification, which identifies a YAM in a separate 328 document, a corresponding normative reference to that document MUST 329 appear in the Normative References section. The reference MUST 330 correspond to the specific YAM version actually used within the 331 specification. 333 If any YANG submodule contained in the specification contains a 334 'belongs-to' statement value which identifies a 'virtual' YANG module 335 maintained in the IANA YANG Module Registry, then a corresponding 336 normative reference to the registry identifier MUST appear in the 337 Normative References section. The registry entry MUST be properly 338 updated, using the appropriate procedures [ed: IANA procedures TBD]. 340 3.7. Copyright Notices 342 The proper copyright notices MUST be present in the module 343 description statement. [ed.: See RFC 4181, 3.7. Exact text for 344 insertion is TBD.] 346 3.8. Intellectual Property Section 348 The proper IPR statements MUST be present in the document, according 349 to the most current Internet Draft boilerplate. [ed.: actual IETF IPR 350 text reference TBD] 352 4. YANG Usage Guidelines 354 In general, YAMs in IETF standards-track specifications MUST comply 355 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. Identifiers 369 Identifiers for modules, submodules, typedefs, groupings, data 370 objects, rpcs, and notifications MUST be between 1 and 63 characters 371 in length. 373 4.2. Defaults 375 In general, it is suggested that sub-statements containing default 376 values SHOULD NOT be present. For example, 'status current;', 377 'config true;', 'mandatory false;', and 'max-elements unbounded;' are 378 common defaults which would make the YAM difficult to read if used 379 everywhere they are allowed. 381 Instead, it is suggested that common statements SHOULD only be used 382 when being set to a value other than the default value. 384 4.3. Conditional Statements 386 A YAM may be conceptually partitioned in several ways, using the 'if- 387 feature' and/or 'when' statements. In addition, NETCONF capabilities 388 are designed to identify optional functionality. 390 Data model designers need to carefully consider all modularity 391 aspects, including the use of YANG conditional statements. 393 Objects SHOULD NOT directly reference NETCONF capabilities, in order 394 to specify optional behavior. Instead, a 'feature' statement SHOULD 395 be defined to represent the NETCONF capability, and the 'if-feature' 396 statement SHOULD be used within the object definition. 398 If the condition associated with the desired semantics is not 399 dependent on any particular instance value within the database, then 400 an 'if-feature' statement SHOULD be used instead of a 'when' 401 statement. 403 All 'must' and 'when' statements MUST contain valid XPath. If any 404 name tests are present, they MUST contain valid module prefixes 405 and/or data node names. 407 The 'attribute', 'namespace', 'preceding', 'preceding-sibling', 408 'following', and 'following-sibling' axis SHOULD NOT be used. 410 The 'position' and 'last' functions SHOULD NOT be used. 412 Implicit 'position' function calls within predicates SHOULD NOT be 413 used. (e.g., //chapter[42]). 415 Data nodes which use the 'int64' and 'uint64' built-in type SHOULD 416 NOT be used within relational expressions. 418 Data modelers need to be careful not to confuse the YANG value space 419 and the XPath value space. The data types are not the same in both, 420 and conversion between YANG and XPath data types SHOULD be considered 421 carefully. 423 Explicit XPath data type conversions SHOULD be used (e.g., 'string', 424 'boolean', or 'number' functions), instead of implicit XPath data 425 type conversions. 427 4.4. Header Contents 429 o The namespace MUST be a globally unique URI, usually assigned by 430 the IANA. 432 o Until a URI is assigned by the IANA, a temporary namespace string 433 SHOULD be selected which is not likely to collide with other YANG 434 namespaces, such as the filename of the Internet Draft containing 435 the YAM. 437 o The organization statement MUST be present. 439 o The contact statement MUST be present. 441 o The description statement MUST be present. 443 o If the YAM represents a model defined in one or more external 444 documents, then a reference statement SHOULD be present. 446 o A revision statement MUST be present for each published version of 447 the YAM. 449 o Each new revision MUST include a revision date which is higher 450 than any other revision date in the YAM. 452 o It is acceptable to reuse the same revision statement within 453 unpublished versions (i.e., Internet Drafts), but the revision 454 date MUST be updated to a higher value each time the Internet 455 Draft is re-published. 457 4.5. Data Types 459 o Selection of an appropriate data type (i.e., built-in type, 460 existing derived type, or new derived type) is very subjective and 461 therefore few requirements can be specified on that subject. 463 o Data model designers SHOULD use the most appropriate built-in data 464 type for the particular application. 466 o If extensibility of enumerated values is required, then the 467 identityref data type SHOULD be used instead of an enumeration or 468 other built-in type. 470 o If an appropriate derived type exists in any standard YAM, such as 471 [I-D.ietf-netmod-yang-types], then it SHOULD be used instead of 472 defining a new derived type. 474 o The description statement MUST be present. 476 o If the type semantics are defined in an external document, then a 477 reference statement SHOULD be present. 479 o For string data types, if a machine-readable pattern can be 480 defined for the desired semantics, then one or more pattern 481 statements SHOULD be present. 483 o For string data types, if the length of the string is not 484 unbounded in all implementations, then a length statement SHOULD 485 be present. 487 o For numeric data types, if the values allowed by the intended 488 semantics are different than those allowed by the unbounded 489 intrinsic data type (e.g., int32), then a range statement SHOULD 490 be present. 492 o The signed numeric data types (i.e., 'int8', 'int16', 'int32', and 493 'int64') SHOULD NOT be used unless negative values are allowed for 494 the desired semantics. 496 o The 'float32' and 'float64' data types SHOULD only be used if the 497 other numeric data types do not fully represent the desired 498 semantics. 500 o For enumeration or bits data types, the semantics for each enum or 501 bit SHOULD be documented. A separate description statement 502 (within each enum or bit statement) SHOULD be used, instead of the 503 description statement for the type itself. 505 o If an appropriate units identifier can be associated with the 506 desired semantics, then a units statement SHOULD be present. 508 o If an appropriate default value can be associated with the desired 509 semantics, then a default statement SHOULD be present. 511 o If a significant number of derived types are defined, and it is 512 anticipated that these data types will be reused by multiple YAMs, 513 then these derived types SHOULD be contained in a separate module 514 or submodule, to allow easier reuse without unnecessary coupling. 516 4.6. Object Definitions 518 o The description statement MUST be present. 520 o If the object semantics are defined in an external document, then 521 a reference statement SHOULD be present. 523 o The 'anyxml' construct MUST NOT be used within configuration data. 525 o If there are referential integrity constraints associated with the 526 desired semantics that can be represented with XPath, then one or 527 more must statements SHOULD be present. 529 o For list and leaf-list objects, if the number of possible 530 instances for all implementations is not unbounded, then the min- 531 elements and/or max-elements statements SHOULD be present. 533 4.7. RPC Definitions 535 o The description statement MUST be present. 537 o If the RPC method semantics are defined in an external document, 538 then a reference statement SHOULD be present. 540 o If the RPC method impacts system behavior in some way, it SHOULD 541 be mentioned in the description statement. 543 o If the RPC method is potentially harmful to system behavior in 544 some way, it MUST be mentioned in the Security Considerations 545 section of the document. 547 4.8. Notification Definitions 549 o The description statement MUST be present. 551 o If the notification semantics are defined in an external document, 552 then a reference statement SHOULD be present. 554 5. YANG Module Registry 556 This section contains a YANG module registry specification, which can 557 be used to document each release of a module. It can also be used to 558 maintain virtual modules, in which all the body statements are 559 contained in submodules specified in the registry, not in a YANG 560 module within a published RFC or Internet Draft. 562 In order for YANG submodules to be used effectively within standards 563 track documents, it is desirable to avoid re-publishing an RFC 564 containing the 'main' module, each time a submodule is added or 565 changed. 567 The use of submodules can effectively reduce the number of XML 568 namespaces used within NETCONF PDUs, but their primary use is to 569 allow flexible partitioning of a single XML namespace into multiple, 570 independent documents, which can be easily extended over time. 572 The YANG Module Registry is an XML instance document which contains 573 minimal information about the modules represented in the registry. 575 Each registry has a unique ID, called the 'registry-id'. There are 576 also zero or more 'module' entries. 578 Each 'module' entry contains the module name, XML namespace, and 579 optional 'url' field to identify its location. If this is a virtual 580 module, then the 'virtual' field will be present. 582 Within each module entry, there are one or more 'release' entries. 584 Each 'release' entry contains the publication date of the release. 585 It also contains zero or more 'submodule' entries. 587 For each submodule included by the main module represented by each 588 'module' entry, a 'submodule' entry SHOULD be present. Each entry 589 provides the name, release date and an optional 'url' if the 590 submodule is available online. 592 It is expected that the IANA will maintain the official YANG Module 593 Registry for YAMs contained in published standards-track documents. 595 It is also expected that procedures for adding a new YANG module, and 596 adding a new release of an existing module, will also be specified. 598 [ed: A YANG data model and example XML instance document are provided 599 below to demonstrate how such a registry might work. This work is 600 very preliminary and subject to change.] 602 5.1. YANG Registry Data Model 604 This section contains a YANG module definition which represents the 605 information stored in the IANA YANG Module Registry. It is provided 606 for informational purposes only. The actual definition is [TBD]. 608 module yang-registry { 610 namespace "yang-registry-TBD"; 612 prefix "yr"; 614 // for the uri data type 615 import yang-types { prefix "yang"; } 617 organization "IETF"; 619 contact 620 "Send comments to ."; 622 description 623 "YANG Module Registry Data Structure"; 625 revision "2009-01-22" { 626 description 627 "Initial version."; 628 } 630 container registry { 632 leaf registry-id { 633 description 634 "Contains the identity of this registry."; 635 type yang:uri; 636 mandatory true; 637 } 639 list module { 640 key "name"; 642 unique "namespace"; 644 leaf name { 645 description "YANG module name."; 646 // TBD: imported name string type 647 type string { length "1..63"; } 648 } 650 leaf namespace { 651 description "YANG module namespace."; 652 type yang:uri; 653 mandatory true; 654 } 656 leaf url { 657 description 658 "URL for this YANG module, if one 659 is available."; 660 type yang:uri; 661 } 663 leaf virtual { 664 description 665 "If present, then this registry entry 666 represents a virtual YANG module, 667 which is a YANG module which does not 668 contain any body statements. Instead, 669 submodules are used to contain all 670 body statements. 672 Each release entry within this entry 673 is expected to contain all 674 the submodule content information for 675 this virtual module."; 676 type empty; 677 } 679 list release { 680 description 681 "Describes the contents of a specific 682 release of a YANG module. At least 683 one entry MUST exist for the most 684 current version of the module."; 686 min-elements 1; 688 key version; 690 leaf version { 691 description "YANG module release date."; 692 // TBD: imported date string type 693 // YYYY-MM-DD 694 type string { length "10"; } 696 } 698 list submodule { 699 key "name"; 701 leaf name { 702 description "YANG submodule name."; 703 // TBD: imported name string type 704 type string { length "1..63"; } 705 } 707 leaf version { 708 description "YANG module revision date."; 709 // TBD: imported date string type 710 // YYYY-MM-DD 711 type string { length "10"; } 712 mandatory true; 713 } 715 leaf url { 716 description 717 "URL for this YANG submodule, if one 718 is available."; 719 type yang:uri; 720 } 721 } // list submodule 722 } // list release 723 } // list module 724 } // container registry 725 } // module yang-registry 727 Figure 2 729 5.2. Examples 731 This section contains some example registry entries, demonstrating 732 the basic use cases. 734 735 736 737 http://example.com/yang-registry 738 739 740 notification 741 742 urn:ietf:params:xml:ns:netconf:notification:1.0 743 744 745 ftp://ftp.rfc-editor.org/in-notes/rfc5277.txt 746 747 748 2008-07-01 749 750 751 752 notification-content 753 754 urn:ietf:params:xml:ns:netmod:notification 755 756 757 ftp://ftp.rfc-editor.org/in-notes/rfc5277.txt 758 759 760 2008-07-01 761 762 763 764 services 765 766 http://example.com/yang/services 767 768 769 http://example.com/yang/monitor-tools.yang 770 771 772 773 2009-01-23 774 775 common-types 776 2008-11-14 777 778 http://example.com/yang/common-types.yang 779 780 781 782 ping 783 2008-11-14 784 785 http://example.com/yang/ping.yang 786 788 789 790 traceroute 791 2009-01-23 792 793 http://example.com/yang/traceroute.yang 794 795 796 797 798 2008-11-14 799 800 common-types 801 2008-11-14 802 803 http://example.com/yang/common-types.yang 804 805 806 807 ping 808 2008-11-14 809 810 http://example.com/yang/ping.yang 811 812 813 814 815 817 Figure 3 819 6. IANA Considerations 821 There are no actions requested of IANA at this time. [ed.: If the 822 YANG Registry approach is pursued, then details for those procedures 823 will need to be defined.] 825 7. Security Considerations 827 This document defines documentation guidelines for NETCONF content 828 defined with the YANG data modeling language. It does not introduce 829 any new or increased security risks into the management system. [ed: 830 RFC 4181 style security section TBD] 832 8. Acknowledgments 834 The structure and contents of this document are adapted from 835 Guidelines for MIB Documents [RFC4181], by C. M. Heard. 837 9. References 839 9.1. Normative References 841 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 842 Requirement Levels", BCP 14, RFC 2119, March 1997. 844 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 845 December 2006. 847 [I-D.ietf-netmod-yang] 848 Bjorklund, M., "YANG - A data modeling language for 849 NETCONF", draft-ietf-netmod-yang-03 (work in progress), 850 January 2009. 852 [I-D.ietf-netmod-yang-types] 853 Schoenwaelder, J., "Common YANG Data Types", 854 draft-ietf-netmod-yang-types-01 (work in progress), 855 November 2008. 857 9.2. Informative References 859 [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB 860 Documents", BCP 111, RFC 4181, September 2005. 862 Author's Address 864 Andy Bierman 865 Netconf Central 866 Simi Valley, CA 867 USA 869 Email: andy@netconfcentral.com