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

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/