draft-ietf-netmod-rfc6087bis-11.txt   draft-ietf-netmod-rfc6087bis-12.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Obsoletes: 6087 (if approved) March 5, 2017 Obsoletes: 6087 (if approved) March 5, 2017
Intended status: Informational Intended status: Informational
Expires: September 6, 2017 Expires: September 6, 2017
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-rfc6087bis-11 draft-ietf-netmod-rfc6087bis-12
Abstract Abstract
This memo provides guidelines for authors and reviewers of Standards This memo provides guidelines for authors and reviewers of Standards
Track specifications containing YANG data model modules. Applicable Track specifications containing YANG data model modules. Applicable
portions may be used as a basis for reviews of other YANG data model portions may be used as a basis for reviews of other YANG data model
documents. Recommendations and procedures are defined, which are documents. Recommendations and procedures are defined, which are
intended to increase interoperability and usability of Network intended to increase interoperability and usability of Network
Configuration Protocol (NETCONF) and RESTCONF protocol Configuration Protocol (NETCONF) and RESTCONF protocol
implementations that utilize YANG data model modules. implementations that utilize YANG data model modules.
skipping to change at page 2, line 27 skipping to change at page 2, line 27
4. General Documentation Guidelines . . . . . . . . . . . . . . . 9 4. General Documentation Guidelines . . . . . . . . . . . . . . . 9
4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 9
4.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9 4.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9
4.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 10 4.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 10
4.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10 4.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10
4.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 4.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11
4.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11 4.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 11
4.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 4.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12
4.7. Security Considerations Section . . . . . . . . . . . . . 12 4.7. Security Considerations Section . . . . . . . . . . . . . 12
4.8. IANA Considerations Section . . . . . . . . . . . . . . . 13 4.8. IANA Considerations Section . . . . . . . . . . . . . . . 13
4.9. Module Usage Examples . . . . . . . . . . . . . . . . . . 13 4.8.1. Documents that Create a New Namespace . . . . . . . . 13
4.9.1. Documents that Create a New Namespace . . . . . . . . 13 4.8.2. Documents that Extend an Existing Namespace . . . . . 13
4.9.2. Documents that Extend an Existing Namespace . . . . . 13 4.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 13
4.10. Reference Sections . . . . . . . . . . . . . . . . . . . . 13 4.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14
4.11. Validation Tools . . . . . . . . . . . . . . . . . . . . . 14 4.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 14
4.12. Module Extraction Tools . . . . . . . . . . . . . . . . . 14 4.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 14
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 15
5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 17
5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 17
5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 18
5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 19
5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 19
5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 20
skipping to change at page 3, line 45 skipping to change at page 3, line 45
5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 49
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51
7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52
7.1. Security Considerations Section Template . . . . . . . . . 52 7.1. Security Considerations Section Template . . . . . . . . . 52
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 54
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 55
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
10.1. Normative References . . . . . . . . . . . . . . . . . . . 57 10.1. Normative References . . . . . . . . . . . . . . . . . . . 57
10.2. Informative References . . . . . . . . . . . . . . . . . . 57 10.2. Informative References . . . . . . . . . . . . . . . . . . 57
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 59
A.1. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.1. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.2. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.2. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.3. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.3. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.4. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.4. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.5. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.5. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 59
A.6. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.6. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.7. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60 A.7. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.8. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.8. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 60
A.9. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.9. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.10. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.10. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.11. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.11. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.12. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 63 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 63
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 65 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 65
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 67
1. Introduction 1. Introduction
The standardization of network configuration interfaces for use with The standardization of network configuration interfaces for use with
the Network Configuration Protocol [RFC6241] and RESTCONF the Network Configuration Protocol [RFC6241] and RESTCONF
[I-D.ietf-netconf-restconf] requires a modular set of data models, [I-D.ietf-netconf-restconf] requires a modular set of data models,
which can be reused and extended over time. which can be reused and extended over time.
skipping to change at page 13, line 19 skipping to change at page 13, line 19
In order to comply with IESG policy as set forth in In order to comply with IESG policy as set forth in
http://www.ietf.org/id-info/checklist.html, every Internet-Draft that http://www.ietf.org/id-info/checklist.html, every Internet-Draft that
is submitted to the IESG for publication MUST contain an IANA is submitted to the IESG for publication MUST contain an IANA
Considerations section. The requirements for this section vary Considerations section. The requirements for this section vary
depending on what actions are required of the IANA. If there are no depending on what actions are required of the IANA. If there are no
IANA considerations applicable to the document, then the IANA IANA considerations applicable to the document, then the IANA
Considerations section stating that there are no actions is removed Considerations section stating that there are no actions is removed
by the RFC Editor before publication. Refer to the guidelines in by the RFC Editor before publication. Refer to the guidelines in
[RFC5226] for more details. [RFC5226] for more details.
4.9. Module Usage Examples 4.8.1. Documents that Create a New Namespace
Each specification that defines one or more modules SHOULD contain
usage examples, either throughout the document or in an appendix.
This includes example XML instance document snippets to demonstrate
the intended usage of the YANG module(s).
4.9.1. Documents that Create a New Namespace
If an Internet-Draft defines a new namespace that is to be If an Internet-Draft defines a new namespace that is to be
administered by the IANA, then the document MUST include an IANA administered by the IANA, then the document MUST include an IANA
Considerations section that specifies how the namespace is to be Considerations section that specifies how the namespace is to be
administered. administered.
Specifically, if any YANG module namespace statement value contained Specifically, if any YANG module namespace statement value contained
in the document is not already registered with IANA, then a new YANG in the document is not already registered with IANA, then a new YANG
Namespace registry entry MUST be requested from the IANA. The Namespace registry entry MUST be requested from the IANA. The
[RFC7950] specification includes the procedure for this purpose in [RFC7950] specification includes the procedure for this purpose in
its IANA Considerations section. its IANA Considerations section.
4.9.2. Documents that Extend an Existing Namespace 4.8.2. Documents that Extend an Existing Namespace
It is possible to extend an existing namespace using a YANG submodule It is possible to extend an existing namespace using a YANG submodule
that belongs to an existing module already administered by IANA. In that belongs to an existing module already administered by IANA. In
this case, the document containing the main module MUST be updated to this case, the document containing the main module MUST be updated to
use the latest revision of the submodule. use the latest revision of the submodule.
4.10. Reference Sections 4.9. Reference Sections
For every import or include statement that appears in a module For every import or include statement that appears in a module
contained in the specification, which identifies a module in a contained in the specification, which identifies a module in a
separate document, a corresponding normative reference to that separate document, a corresponding normative reference to that
document MUST appear in the Normative References section. The document MUST appear in the Normative References section. The
reference MUST correspond to the specific module version actually reference MUST correspond to the specific module version actually
used within the specification. used within the specification.
For every normative reference statement that appears in a module For every normative reference statement that appears in a module
contained in the specification, which identifies a separate document, contained in the specification, which identifies a separate document,
a corresponding normative reference to that document SHOULD appear in a corresponding normative reference to that document SHOULD appear in
the Normative References section. The reference SHOULD correspond to the Normative References section. The reference SHOULD correspond to
the specific document version actually used within the specification. the specific document version actually used within the specification.
If the reference statement identifies an informative reference, which If the reference statement identifies an informative reference, which
identifies a separate document, a corresponding informative reference identifies a separate document, a corresponding informative reference
to that document MAY appear in the Informative References section. to that document MAY appear in the Informative References section.
4.11. Validation Tools 4.10. Validation Tools
All modules need to be validated before submission in an Internet All modules need to be validated before submission in an Internet
Draft. The 'pyang' YANG compiler is freely available from github: Draft. The 'pyang' YANG compiler is freely available from github:
https://github.com/mbj4668/pyang https://github.com/mbj4668/pyang
If the 'pyang' compiler is used to validate a normative module, then If the 'pyang' compiler is used to validate a normative module, then
the "--ietf" command line option MUST be used to identify any IETF the "--ietf" command line option MUST be used to identify any IETF
guideline issues. guideline issues.
If the 'pyang' compiler is used to validate an example module, then If the 'pyang' compiler is used to validate an example module, then
the "--ietf" command line option MAY be used to identify any IETF the "--ietf" command line option MAY be used to identify any IETF
guideline issues. guideline issues.
4.12. Module Extraction Tools 4.11. Module Extraction Tools
A version of 'rfcstrip' is available which will extract YANG modules A version of 'rfcstrip' is available which will extract YANG modules
from an Internet Draft or RFC. The 'rfcstrip' tool which supports from an Internet Draft or RFC. The 'rfcstrip' tool which supports
YANG module extraction is freely available: YANG module extraction is freely available:
http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE This tool can be used to verify that the "<CODE BEGINS>" and "<CODE
ENDS>" tags are used correctly and that the normative YANG modules ENDS>" tags are used correctly and that the normative YANG modules
can be extracted correctly. can be extracted correctly.
4.12. Module Usage Examples
Each specification that defines one or more modules SHOULD contain
usage examples, either throughout the document or in an appendix.
This includes example XML instance document snippets to demonstrate
the intended usage of the YANG module(s).
5. YANG Usage Guidelines 5. YANG Usage Guidelines
Modules in IETF Standards Track specifications MUST comply with all Modules in IETF Standards Track specifications MUST comply with all
syntactic and semantic requirements of YANG [RFC7950]. The syntactic and semantic requirements of YANG [RFC7950]. The
guidelines in this section are intended to supplement the YANG guidelines in this section are intended to supplement the YANG
specification, which is intended to define a minimum set of specification, which is intended to define a minimum set of
conformance requirements. conformance requirements.
In order to promote interoperability and establish a set of practices In order to promote interoperability and establish a set of practices
based on previous experience, the following sections establish usage based on previous experience, the following sections establish usage
skipping to change at page 59, line 9 skipping to change at page 59, line 9
[RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed.,
"RFC Streams, Headers, and Boilerplates", RFC 7841, "RFC Streams, Headers, and Boilerplates", RFC 7841,
DOI 10.17487/RFC7841, May 2016, DOI 10.17487/RFC7841, May 2016,
<http://www.rfc-editor.org/info/rfc7841>. <http://www.rfc-editor.org/info/rfc7841>.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. v10 to v11 A.1. v11 to v12
o fix incoorect location of new Module Usage Examples section
A.2. 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.2. v09 to v10 A.3. 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.3. v08 to v09 A.4. 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.4. v07 to v08 A.5. 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
skipping to change at page 59, line 48 skipping to change at page 60, line 4
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.5. v06 to v07 A.6. 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.6. v05 to v06 A.7. 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.7. v04 to v05 A.8. 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 61, line 16 skipping to change at page 61, line 19
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.8. v03 ot v04 A.9. 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.9. v02 to v03 A.10. 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.10. v01 to v02 A.11. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.11. v00 to v01 A.12. 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 Section 3 so RFCs with YANG modules o Issue 1: Tree Diagrams: Added Section 3 so RFCs with YANG modules
can use an Informative reference to this RFC for tree diagrams. can use an Informative reference to this RFC for tree diagrams.
Updated guidelines to reference this RFC when tree diagrams are Updated guidelines to reference this RFC when tree diagrams are
used used
 End of changes. 21 change blocks. 
42 lines changed or deleted 46 lines changed or added

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