--- 1/draft-ietf-netmod-rfc6087bis-19.txt 2018-03-13 16:13:21.765069350 -0700 +++ 2/draft-ietf-netmod-rfc6087bis-20.txt 2018-03-13 16:13:21.881072138 -0700 @@ -1,19 +1,19 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Obsoletes: 6087 (if approved) March 11, 2018 +Obsoletes: 6087 (if approved) March 13, 2018 Intended status: BCP -Expires: September 12, 2018 +Expires: September 14, 2018 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-19 + draft-ietf-netmod-rfc6087bis-20 Abstract This memo provides guidelines for authors and reviewers of specifications containing YANG data model modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONF protocol implementations that utilize YANG data model modules. This document obsoletes RFC 6087. @@ -25,21 +25,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 12, 2018. + This Internet-Draft will expire on September 14, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -131,40 +131,41 @@ 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 55 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 55 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 6. Security Considerations . . . . . . . . . . . . . . . . . . . 58 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 8.1. Normative References . . . . . . . . . . . . . . . . . . . 60 8.2. Informative References . . . . . . . . . . . . . . . . . . 61 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 63 - A.1. v18 to v19 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.2. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.3. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.1. v19 to v20 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.2. v18 to v19 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.3. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.4. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.5. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.6. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.7. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.8. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.9. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.10. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.11. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.12. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.13. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 65 - A.14. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 65 - A.15. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 65 - A.16. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 66 - A.17. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 66 - A.18. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 66 - A.19. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 67 - A.20. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 67 + A.6. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.7. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.8. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.9. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.10. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.11. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.12. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.13. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.14. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 65 + A.15. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 65 + A.16. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 65 + A.17. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 66 + A.18. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 66 + A.19. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 66 + A.20. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 67 + A.21. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 67 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 68 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 1. Introduction The standardization of network configuration interfaces for use with network configuration management protocols, such as the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a modular set of data models, which can be reused and extended over @@ -405,21 +406,21 @@ file "ietf-foo@2016-03-20.yang" module ietf-foo { namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; prefix "foo"; organization "..."; contact "..."; description "..."; revision 2016-03-20 { description "Latest revision"; - reference "RFC XXXX"; + reference "RFC XXXX: Foo Protocol"; } // ... more statements } 3.2.1. Example Modules Example modules are not code components. The convention MUST NOT be used for example modules. @@ -1157,21 +1158,21 @@ The revision-date substatement within the include statement SHOULD be present if any groupings are used from the external submodule. If an import statement is for a module from a stable source (e.g., an RFC for an IETF module), then a reference-stmt SHOULD be present within an import statement. import ietf-yang-types { prefix yang; - reference "RFC 6991"; + reference "RFC 6991: Common YANG Data Types"; } If submodules are used, then the document containing the main module MUST be updated so that the main module revision date is equal or more recent than the revision date of any submodule that is (directly or indirectly) included by the main module. Definitions for future use SHOULD NOT be specified in a module. Do not specify placeholder objects like the "reserved" example below: @@ -1327,21 +1328,21 @@ The top-level data organization SHOULD be considered carefully, in advance. Data model designers need to consider how the functionality for a given protocol or protocol family will grow over time. The separation of configuration data and operational state SHOULD be considered carefully. It is sometimes useful to define separate top- level containers for configuration and non-configuration data. For some existing top-level data nodes, configuration data was not in scope, so only one container representing operational state was created. Refer to the Network Management Datastore Architecture - (NMDA) [I-D.ietf-netmod-revised-datastores]. for details. + (NMDA) [I-D.ietf-netmod-revised-datastores] for details. The number of top-level data nodes within a module SHOULD be minimized. It is often useful to retrieve related information within a single subtree. If data is too distributed, is becomes difficult to retrieve all at once. The names and data organization SHOULD reflect persistent information, such as the name of a protocol. The name of the working group SHOULD NOT be used because this may change over time. @@ -2679,165 +2680,170 @@ [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . Appendix A. Change Log -- RFC Ed.: remove this section before publication. -A.1. v18 to v19 +A.1. v19 to v20 + + o fix examples + +A.2. v18 to v19 o address IESG ballot comments -A.2. v17 to v18 +A.3. v17 to v18 o address Area Director review comments Part 2 o clarify preferred list key order -A.3. v16 to v17 +A.4. v16 to v17 o address Area Director review comments Part 1 -A.4. v15 to v16 +A.5. v15 to v16 o address Area Director review comments posted 2018-01-25 -A.5. v15 to v16 +A.6. v15 to v16 o address document shephard comments posted 2018-01-15 o add yang-version to template module -A.6. v14 to v15 +A.7. v14 to v15 o changed Intended status from Informational to BCP o update tree diagram guidelines section o Change IANA template to list IESG instead of NETMOD WG as the Registrant o Update some references -A.7. v13 to v14 +A.8. v13 to v14 o Replaced sec. 4.23 Operational Data with Operational Data from NMDA text by Lou Berger and Kent Watsen o Added NMDA Terms section o Changed term operational data to operational state + o Clarified that reference-stmt SHOULD be present in import-stmt -A.8. v12 to v13 +A.9. v12 to v13 o Clarify that the revision-date SHOULD be used in a CODE BEGINS YANG file extraction macro. o Clarify the IANA requirements section wrt/ XML namespace and YANG module name registries. o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. o Update Operation Data section to consider revised datastores. o Add reference to YANG Tree Diagrams and update 2 sections that use this reference. o Add reference to Revised Datastores and guidelines drafts -A.9. v11 to v12 +A.10. v11 to v12 o fix incorrect location of new Module Usage Examples section -A.10. v10 to v11 +A.11. v10 to v11 o updated YANG tree diagram syntax to align with pyang 1.7.1 o added general guideline to include module usage examples -A.11. v09 to v10 +A.12. v09 to v10 o clarified is only for normative modules o clarified example module namespace URI conventions o clarified pyang usage for normative and example modules o updated YANG tree diagrams section with text from RFC 8022 -A.12. v08 to v09 +A.13. v08 to v09 o fixed references - o added mention of RESTCONF to abstract and intro o created separate section for code components + o fixed document status -A.13. v07 to v08 +A.14. v07 to v08 o changed CODE BEGINS guideline for example modules o updated tree diagram guidelines o clarified published and unpublished terms o added section on Empty and Boolean data types o clarified how to update the revision statement o updated operational state guidelines o added 'YANG fragment' to terminology section -A.14. v06 to v07 +A.15. v06 to v07 o update contact statement guideline o update example modules guidelines o add guidelines on top-level data nodes o add guideline on use of NP containers o added guidelines on union types o add guideline on deviations o added section on open systems considerations o added guideline about definitions reserved for future use -A.15. v05 to v06 +A.16. v05 to v06 o Changed example 'my-module' to 'example-module' o Added section Updating YANG Modules (Published vs. Unpublished) o Added Example Modules section - o Added "" convention for full example modules o Added section on using action vs. rpc + o Changed term "operational state" to "operational data" o Added section on YANG Data Node Constraints o Added guidelines on using must vs. when statements o Made ietf-foo module validate for I-D submission -A.16. v04 to v05 +A.17. v04 to v05 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if no YANG 1.1 features needed o Changed SHOULD follow YANG naming conventions to MUST follow (for standards track documents only) o Clarified module naming conventions for normative modules, example modules, and modules from other SDOs. @@ -2845,39 +2851,39 @@ o Added new section on guidelines for reusable groupings o Made header guidelines less IETF-specific o Added new section on guidelines for extension statements o Added guidelines for nested "choice" statement within a "case" statement -A.17. v03 ot v04 +A.18. v03 ot v04 o Added sections for deviation statements and performance considerations o Added YANG 1.1 section o Updated YANG reference from 1.0 to 1.1 -A.18. v02 to v03 +A.19. v02 to v03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.19. v01 to v02 +A.20. v01 to v02 o Updated draft based on mailing list comments. -A.20. v00 to v01 +A.21. v00 to v01 All issues from the issue tracker have been addressed. https://github.com/netmod-wg/rfc6087bis/issues o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with YANG modules can use an Informative reference to this RFC for tree diagrams. Updated guidelines to reference this RFC when tree diagrams are used @@ -3048,21 +3054,21 @@ to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and remove // this note - reference "RFC XXXX"; + reference "RFC XXXX: "; // RFC Ed.: remove this note // Note: extracted from RFC XXXX // replace '2016-03-20' with the module publication date // The format is (year-month-day) revision "2016-03-20" { description "what changed in this revision"; reference "document containing this module"; }