draft-ietf-netmod-rfc6087bis-17.txt   draft-ietf-netmod-rfc6087bis-18.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Obsoletes: 6087 (if approved) February 5, 2018 Obsoletes: 6087 (if approved) February 20, 2018
Intended status: BCP Intended status: BCP
Expires: August 9, 2018 Expires: August 24, 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-17 draft-ietf-netmod-rfc6087bis-18
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. This document implementations that utilize YANG data model modules. This document
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 August 9, 2018. This Internet-Draft will expire on August 24, 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 38 skipping to change at page 3, line 38
4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 45 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 45
4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 46 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 46
4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47
4.23.1. Combining Operational State and Configuration Data . . 47 4.23.1. Combining Operational State and Configuration Data . . 47
4.23.2. Representing Operational Values of Configuration 4.23.2. Representing Operational Values of Configuration
Data . . . . . . . . . . . . . . . . . . . . . . . . . 48 Data . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 48 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 48
4.24. Performance Considerations . . . . . . . . . . . . . . . . 52 4.24. Performance Considerations . . . . . . . . . . . . . . . . 52
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 53 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 53
4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 53 4.26. Guidelines for YANG 1.1 Specific Constructs . . . . . . . 53
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 53 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 53
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 53 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 53
4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 54 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 54
4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 54 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 54
4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 55 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 55
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56
6. Security Considerations . . . . . . . . . . . . . . . . . . . 57 6. Security Considerations . . . . . . . . . . . . . . . . . . . 57
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59
8.1. Normative References . . . . . . . . . . . . . . . . . . . 59 8.1. Normative References . . . . . . . . . . . . . . . . . . . 59
8.2. Informative References . . . . . . . . . . . . . . . . . . 59 8.2. Informative References . . . . . . . . . . . . . . . . . . 59
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 62 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 62
A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.1. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.2. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.2. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.3. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.3. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.4. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.5. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.5. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.6. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.6. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.7. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.7. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.8. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.8. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.9. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.9. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.10. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.10. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.11. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.11. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.12. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.12. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.13. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.13. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.14. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.14. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.15. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.15. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.16. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.16. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.17. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.17. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.18. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.19. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 66
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 67 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 67
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 69 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 69
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71
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 38, line 25 skipping to change at page 38, line 25
describe the purpose of each one. describe the purpose of each one.
The "choice" statement is allowed to be directly present within a The "choice" statement is allowed to be directly present within a
"case" statement in YANG 1.1. This needs to be considered carefully. "case" statement in YANG 1.1. This needs to be considered carefully.
Consider simply including the nested "choice" as additional "case" Consider simply including the nested "choice" as additional "case"
statements within the parent "choice" statement. Note that the statements within the parent "choice" statement. Note that the
"mandatory" and "default" statements within a nested "choice" "mandatory" and "default" statements within a nested "choice"
statement only apply if the "case" containing the nested "choice" statement only apply if the "case" containing the nested "choice"
statement is first selected. statement is first selected.
If a list defines any key leafs, then these leafs SHOULD be defined
in order, as the first child nodes within the list. The key leafs
MAY be in a different order in some cases, e.g., they are defined in
a grouping, not inline in the list statement.
4.14.1. Non-Presence Containers 4.14.1. Non-Presence Containers
A non-presence container is used to organize data into specific A non-presence container is used to organize data into specific
subtrees. It is not intended to have semantics within the data model subtrees. It is not intended to have semantics within the data model
beyond this purpose, although YANG allows it (e.g., "must" statement beyond this purpose, although YANG allows it (e.g., "must" statement
within the non-presence container). within the non-presence container).
Example using container wrappers: Example using container wrappers:
container top { container top {
skipping to change at page 46, line 12 skipping to change at page 46, line 12
"leafref" data type, with the "require-instance" sub-statement set "leafref" data type, with the "require-instance" sub-statement set
to "true". This method SHOULD be used. to "true". This method SHOULD be used.
If the new data instances are not limited to the values in use in the If the new data instances are not limited to the values in use in the
original data structure, then the "require-instance" sub-statement original data structure, then the "require-instance" sub-statement
MUST be set to "false". Loose coupling is achieved by using key MUST be set to "false". Loose coupling is achieved by using key
leafs with the same data type as the original data structure. This leafs with the same data type as the original data structure. This
has the same semantics as setting the "require-instance" sub- has the same semantics as setting the "require-instance" sub-
statement to "false". statement to "false".
It is sometimes useful to separate configuration data and operational The relationship between configuration and operational state has been
state, so that they do not not even share the exact same naming clarified in NMDA [I-D.ietf-netmod-revised-datastores].
characteristics. The correlation between configuration the
operational state that is affected by changes in configuration is a
complex problem. There may not be a simple 1:1 relationship between
a configuration data node and an operational state node. Further
work is needed in YANG to clarify this relationship. Protocol work
may also be needed to allow a client to retrieve this type of
information from a server. At this time the best practice is to
clearly document any relationship to other data structures in the
"description" statement.
4.22.1. Use of Leafref for Key Correlation 4.22.1. Use of Leafref for Key Correlation
Sometimes it is not practical to augment a data structure. For Sometimes it is not practical to augment a data structure. For
example, the correlated data could have different keys or contain example, the correlated data could have different keys or contain
mandatory nodes. mandatory nodes.
The following example shows the use of the "leafref" data type for The following example shows the use of the "leafref" data type for
data correlation purposes: data correlation purposes:
skipping to change at page 47, line 36 skipping to change at page 47, line 36
} }
4.23. Operational State 4.23. Operational State
The modeling of operational state with YANG has been refined over The modeling of operational state with YANG has been refined over
time. At first, only data that has a "config" statement value of time. At first, only data that has a "config" statement value of
"false" was considered to be operational state. This data was not "false" was considered to be operational state. This data was not
considered to be part of any datastore, which made YANG XPath considered to be part of any datastore, which made YANG XPath
definition much more complicated. definition much more complicated.
Operational state is now modeled using YANG according to new NMDA, Operational state is now modeled using YANG according to the new NMDA
and is now conceptually contained in the operational state datastore, [I-D.ietf-netmod-revised-datastores], and is now conceptually
which also includes the operational values of configuration data. contained in the operational state datastore, which also includes the
There is no longer any need to duplicate data structures to provide operational values of configuration data. There is no longer any
separate configuration and operational state sections. need to duplicate data structures to provide separate configuration
and operational state sections.
This section describes some data modeling issues related to This section describes some data modeling issues related to
operational state, and guidelines for transitioning YANG data model operational state, and guidelines for transitioning YANG data model
design to be NMDA-compatible. design to be NMDA-compatible.
4.23.1. Combining Operational State and Configuration Data 4.23.1. Combining Operational State and Configuration Data
If possible, operational state SHOULD be combined with its associated If possible, operational state SHOULD be combined with its associated
configuration data. This prevents duplication of key leafs and configuration data. This prevents duplication of key leafs and
ancestor nodes. It also prevents race conditions for retrieval of ancestor nodes. It also prevents race conditions for retrieval of
skipping to change at page 53, line 28 skipping to change at page 53, line 28
"require-instance" is set to false "require-instance" is set to false
4.25. Open Systems Considerations 4.25. Open Systems Considerations
A YANG module MUST NOT be designed such that the set of modules found A YANG module MUST NOT be designed such that the set of modules found
on a server implementation can be predetermined in advance. Only the on a server implementation can be predetermined in advance. Only the
modules imported by a particular module can be assumed to be present modules imported by a particular module can be assumed to be present
in an implementation. An open system MAY include any combination of in an implementation. An open system MAY include any combination of
YANG modules. YANG modules.
4.26. YANG 1.1 Guidelines 4.26. Guidelines for YANG 1.1 Specific Constructs
The set of YANG 1.1 guidelines will grow as operational experience is The set of YANG 1.1 guidelines will grow as operational experience is
gained with the new language features. This section contains an gained with the new language features. This section contains an
initial set of guidelines. initial set of guidelines for new YANG 1.1 language features.
4.26.1. Importing Multiple Revisions 4.26.1. Importing Multiple Revisions
Standard modules SHOULD NOT import multiple revisions of the same Standard modules SHOULD NOT import multiple revisions of the same
module into a module. This MAY be done if the authors can module into a module. This MAY be done if independent definitions
demonstrate that the "avoided" definitions from the most recent of (e.g. enumeration typedefs) from specific revisions are needed in the
the multiple revisions are somehow broken or harmful to importing module.
interoperability.
4.26.2. Using Feature Logic 4.26.2. Using Feature Logic
The YANG 1.1 feature logic is much more expressive than YANG 1.0. A The YANG 1.1 feature logic is much more expressive than YANG 1.0. A
"description" statement SHOULD describe the "if-feature" logic in "description" statement SHOULD describe the "if-feature" logic in
text, to help readers understand the module. text, to help readers understand the module.
YANG features SHOULD be used instead of the "when" statement, if YANG features SHOULD be used instead of the "when" statement, if
possible. Features are advertised by the server and objects possible. Features are advertised by the server and objects
conditional by if-feature are conceptually grouped together. There conditional by if-feature are conceptually grouped together. There
skipping to change at page 54, line 32 skipping to change at page 54, line 30
node definition. An "action" statement SHOULD be used if the node definition. An "action" statement SHOULD be used if the
protocol operation is specific to a subset of all data nodes instead protocol operation is specific to a subset of all data nodes instead
of all possible data nodes. of all possible data nodes.
The same action name MAY be used in different definitions within The same action name MAY be used in different definitions within
different data node. For example, a "reset" action defined with a different data node. For example, a "reset" action defined with a
data node definition for an interface might have different parameters data node definition for an interface might have different parameters
than for a power supply or a VLAN. The same action name SHOULD be than for a power supply or a VLAN. The same action name SHOULD be
used to represent similar semantics. used to represent similar semantics.
The NETCONF Access Control Model (NACM) [RFC6536] does not support The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis]
parameter access control for RPC operations. The user is given does not support parameter access control for RPC operations. The
permission (or not) to invoke the RPC operation with any parameters. user is given permission (or not) to invoke the RPC operation with
For example, if each client is only allowed to reset their own any parameters. For example, if each client is only allowed to reset
interface, then NACM cannot be used. their own interface, then NACM cannot be used.
For example, NACM cannot enforce access access control based on the For example, NACM cannot enforce access access control based on the
value of the "interface" parameter, only the "reset" operation value of the "interface" parameter, only the "reset" operation
itself: itself:
rpc reset { rpc reset {
input { input {
leaf interface { leaf interface {
type if:interface-ref; type if:interface-ref;
mandatory true; mandatory true;
skipping to change at page 59, line 47 skipping to change at page 59, line 47
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[W3C.REC-xpath-19991116] [W3C.REC-xpath-19991116]
Clark, J. and S. DeRose, "XML Path Language (XPath) Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-netconf-rfc6536bis]
Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Module", draft-ietf-netconf-rfc6536bis-09
(work in progress), December 2017.
[I-D.ietf-netmod-revised-datastores] [I-D.ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-10 Architecture", draft-ietf-netmod-revised-datastores-10
(work in progress), January 2018. (work in progress), January 2018.
[I-D.ietf-netmod-rfc7223bis] [I-D.ietf-netmod-rfc7223bis]
Bjorklund, M., "A YANG Data Model for Interface Bjorklund, M., "A YANG Data Model for Interface
Management", draft-ietf-netmod-rfc7223bis-03 (work in Management", draft-ietf-netmod-rfc7223bis-03 (work in
progress), January 2018. progress), January 2018.
[I-D.ietf-netmod-rfc8022bis] [I-D.ietf-netmod-rfc8022bis]
Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for
Routing Management (NMDA Version)", Routing Management (NMDA Version)",
draft-ietf-netmod-rfc8022bis-11 (work in progress), draft-ietf-netmod-rfc8022bis-11 (work in progress),
January 2018. January 2018.
[I-D.ietf-netmod-yang-tree-diagrams] [I-D.ietf-netmod-yang-tree-diagrams]
Bjorklund, M. and L. Berger, "YANG Tree Diagrams", Bjorklund, M. and L. Berger, "YANG Tree Diagrams",
draft-ietf-netmod-yang-tree-diagrams-05 (work in draft-ietf-netmod-yang-tree-diagrams-06 (work in
progress), January 2018. progress), February 2018.
[RFC-STYLE] [RFC-STYLE]
Braden, R., Ginoza, S., and A. Hagens, "RFC Document Braden, R., Ginoza, S., and A. Hagens, "RFC Document
Style", September 2009, Style", September 2009,
<http://www.rfc-editor.org/rfc-style-guide/rfc-style>. <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
<http://www.rfc-editor.org/info/rfc2026>. <http://www.rfc-editor.org/info/rfc2026>.
skipping to change at page 62, line 9 skipping to change at page 62, 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. v15 to v16 A.1. v17 to v18
o address Area Director review comments Part 2
o clarify preferred list key order
A.2. v16 to v17
o address Area Director review comments Part 1
A.3. v15 to v16
o address Area Director review comments posted 2018-01-25 o address Area Director review comments posted 2018-01-25
A.2. v15 to v16 A.4. 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.3. v14 to v15 A.5. 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.4. v13 to v14 A.6. 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.5. v12 to v13 A.7. 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.6. v11 to v12 A.8. v11 to v12
o fix incorrect location of new Module Usage Examples section o fix incorrect location of new Module Usage Examples section
A.7. v10 to v11 A.9. 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.8. v09 to v10 A.10. 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.9. v08 to v09 A.11. 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.10. v07 to v08 A.12. 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 64, line 4 skipping to change at page 64, line 16
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.11. v06 to v07 A.13. 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.12. v05 to v06 A.14. 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
skipping to change at page 64, line 39 skipping to change at page 65, line 4
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.13. v04 to v05 A.15. 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 65, line 22 skipping to change at page 65, line 32
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.14. v03 ot v04 A.16. 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.15. v02 to v03 A.17. 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.16. v01 to v02 A.18. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.17. v00 to v01 A.19. 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 67, line 47 skipping to change at page 67, line 47
o IANA Considerations section -- this section must always be o IANA Considerations section -- this section must always be
present. For each module within the document, ensure that the present. For each module within the document, ensure that the
IANA Considerations section contains entries for the following IANA Considerations section contains entries for the following
IANA registries: IANA registries:
XML Namespace Registry: Register the YANG module namespace. XML Namespace Registry: Register the YANG module namespace.
YANG Module Registry: Register the YANG module name, prefix, YANG Module Registry: Register the YANG module name, prefix,
namespace, and RFC number, according to the rules specified namespace, and RFC number, according to the rules specified
in [RFC7950]. in [RFC6020].
o References -- verify that the references are properly divided o References -- verify that the references are properly divided
between normative and informative references, that RFC 2119 is between normative and informative references, that RFC 2119 and
included as a normative reference if the terminology defined RFC 8174 are included as normative references if the terminology
therein is used in the document, that all references required by defined therein is used in the document, that all references
the boilerplate are present, that all YANG modules containing required by the boilerplate are present, that all YANG modules
imported items are cited as normative references, and that all containing imported items are cited as normative references, and
citations point to the most current RFCs unless there is a valid that all citations point to the most current RFCs unless there is
reason to do otherwise (for example, it is OK to include an a valid reason to do otherwise (for example, it is OK to include
informative reference to a previous version of a specification to an informative reference to a previous version of a specification
help explain a feature included for backward compatibility). Be to help explain a feature included for backward compatibility).
sure citations for all imported modules are present somewhere in Be sure citations for all imported modules are present somewhere
the document text (outside the YANG module). in the document text (outside the YANG module). If a YANG module
contains reference or description statements that refer to an
Internet Draft (I-D), then the I-D is included as an Informative
Reference.
o License -- verify that the draft contains the Simplified BSD o License -- verify that the draft contains the Simplified BSD
License in each YANG module or submodule. Some guidelines related License in each YANG module or submodule. Some guidelines related
to this requirement are described in Section 3.1. Make sure that to this requirement are described in Section 3.1. Make sure that
the correct year is used in all copyright dates. Use the approved the correct year is used in all copyright dates. Use the approved
text from the latest Trust Legal Provisions (TLP) document, which text from the latest Trust Legal Provisions (TLP) document, which
can be found at: can be found at:
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
 End of changes. 36 change blocks. 
81 lines changed or deleted 97 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/