--- 1/draft-ietf-netmod-rfc6087bis-14.txt 2017-12-18 20:13:10.180043692 -0800 +++ 2/draft-ietf-netmod-rfc6087bis-15.txt 2017-12-18 20:13:10.288046221 -0800 @@ -1,19 +1,19 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Obsoletes: 6087 (if approved) September 8, 2017 -Intended status: Informational -Expires: March 12, 2018 +Obsoletes: 6087 (if approved) December 18, 2017 +Intended status: BCP +Expires: June 21, 2018 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-14 + draft-ietf-netmod-rfc6087bis-15 Abstract This memo provides guidelines for authors and reviewers of Standards Track specifications containing YANG data model modules. Applicable portions may be used as a basis for reviews of other YANG data model documents. 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 @@ -27,21 +27,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 March 12, 2018. + This Internet-Draft will expire on June 21, 2018. Copyright Notice Copyright (c) 2017 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 @@ -61,23 +61,23 @@ 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.5.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7 3. General Documentation Guidelines . . . . . . . . . . . . . . . 8 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 - 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11 + 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 10 3.7. Security Considerations Section . . . . . . . . . . . . . 11 - 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 12 + 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 11 3.8.1. Documents that Create a New Namespace . . . . . . . . 12 3.8.2. Documents that Extend an Existing Namespace . . . . . 12 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 13 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 @@ -134,34 +134,35 @@ 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 50 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 6. Security Considerations . . . . . . . . . . . . . . . . . . . 53 6.1. Security Considerations Section Template . . . . . . . . . 53 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 56 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 9.1. Normative References . . . . . . . . . . . . . . . . . . . 58 9.2. Informative References . . . . . . . . . . . . . . . . . . 58 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61 - A.1. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.2. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.3. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.4. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.5. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.6. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.7. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.8. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.9. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.10. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.11. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.12. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.13. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.14. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.1. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.2. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.3. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.4. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.5. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.6. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.7. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.8. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.9. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.10. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.11. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.12. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.13. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.14. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.15. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 1. Introduction The standardization of network configuration interfaces for use with the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040] requires a modular set of data models, which can be reused and extended over time. @@ -388,48 +389,36 @@ text: A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is defined in [I-D.ietf-netmod-yang-tree-diagrams]. 3.4. Tree Diagrams YANG tree diagrams provide a concise representation of a YANG module, and SHOULD be included to help readers understand YANG module - structure. Tree diagrams MAY be split into sections to correspond to - document structure. + structure. Guidelines on tree diagrams can be found in Section 3 of + [I-D.ietf-netmod-yang-tree-diagrams]. The following example shows a simple YANG tree diagram: +--rw top-level-config-container | +--rw config-list* [key-name] | +--rw key-name string | +--rw optional-parm? string | +--rw mandatory-parm identityref | +--ro read-only-leaf string +--ro top-level-nonconfig-container +--ro nonconfig-list* [name] +--ro name string +--ro type string - The 'pyang' compiler can be used to produce the tree diagram, using - the '-f tree' command line parameter. - - If the YANG module is comprised of groupings only, then the tree - diagram SHOULD contain the groupings. The 'pyang' compiler can be - used to produce a tree diagram with groupings using the '-f tree - --tree-print-groupings" command line parameters. - - If the YANG module contains notifications, then the tree diagram - SHOULD contain the notifications. If the YANG module contains RPC - statements, then the tree diagram SHOULD contain the RPC statements. - 3.5. Narrative Sections The narrative part MUST include an overview section that describes the scope and field of application of the module(s) defined by the specification and that specifies the relationship (if any) of these modules to other standards, particularly to standards containing other YANG modules. The narrative part SHOULD include one or more sections to briefly describe the structure of the modules defined in the specification. @@ -494,21 +483,21 @@ 3.8. IANA Considerations Section In order to comply with IESG policy as set forth in http://www.ietf.org/id-info/checklist.html, every Internet-Draft that is submitted to the IESG for publication MUST contain an IANA Considerations section. The requirements for this section vary depending on what actions are required of the IANA. If there are no IANA considerations applicable to the document, then the IANA Considerations section stating that there are no actions is removed by the RFC Editor before publication. Refer to the guidelines in - [RFC5226] for more details. + [RFC8126] for more details. Each normative YANG module MUST be registered in the XML namespace Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. This applies to new modules and updated modules. Examples of these registrations for the "ietf-template" module can be found in Section 5. 3.8.1. Documents that Create a New Namespace If an Internet-Draft defines a new namespace that is to be @@ -2321,21 +2310,21 @@ RFC instead of RFC 6087 for the ietf-template module, and remove this note. This document registers one URI in the IETF XML registry [RFC3688]. The following registration has been made in [RFC6087] and updated by this document. URI: urn:ietf:params:xml:ns:yang:ietf-template - Registrant Contact: The NETMOD WG of the IETF. + Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. The following assignment has been made in [RFC6087] and updated by this document in the YANG Module Names Registry, or the YANG module template in Appendix C. +-----------+-------------------------------------------+ | Field | Value | +-----------+-------------------------------------------+ @@ -2528,48 +2517,44 @@ Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . 9.2. Informative References [I-D.ietf-netmod-revised-datastores] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore - Architecture", draft-ietf-netmod-revised-datastores-04 - (work in progress), August 2017. + Architecture", draft-ietf-netmod-revised-datastores-07 + (work in progress), November 2017. [I-D.ietf-netmod-yang-tree-diagrams] Bjorklund, M. and L. Berger, "YANG Tree Diagrams", - draft-ietf-netmod-yang-tree-diagrams-01 (work in - progress), June 2017. + draft-ietf-netmod-yang-tree-diagrams-02 (work in + progress), October 2017. [RFC-STYLE] Braden, R., Ginoza, S., and A. Hagens, "RFC Document Style", September 2009, . [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, . [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 4151, DOI 10.17487/RFC4151, October 2005, . [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB Documents", BCP 111, RFC 4181, September 2005. - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - May 2008. - [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", RFC 6087, January 2011. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . @@ -2587,103 +2572,119 @@ [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., "RFC Streams, Headers, and Boilerplates", RFC 7841, DOI 10.17487/RFC7841, May 2016, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . + [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. v13 to v14 +A.1. 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.2. 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.2. v12 to v13 +A.3. 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.3. v11 to v12 +A.4. v11 to v12 o fix incorrect location of new Module Usage Examples section -A.4. v10 to v11 +A.5. 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.5. v09 to v10 +A.6. 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.6. v08 to v09 +A.7. 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.7. v07 to v08 +A.8. 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.8. v06 to v07 +A.9. 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 @@ -2682,41 +2683,41 @@ 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.9. v05 to v06 +A.10. 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.10. v04 to v05 +A.11. 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. @@ -2716,47 +2717,46 @@ 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. o Added prefix value selection guidelines 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.11. v03 ot v04 +A.12. 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.12. v02 to v03 +A.13. v02 to v03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.13. v01 to v02 +A.14. v01 to v02 o Updated draft based on mailing list comments. -A.14. v00 to v01 +A.15. 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 Section 2.5.1 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