draft-ietf-netmod-rfc6087bis-13.txt   draft-ietf-netmod-rfc6087bis-14.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Obsoletes: 6087 (if approved) June 18, 2017 Obsoletes: 6087 (if approved) September 8, 2017
Intended status: Informational Intended status: Informational
Expires: December 20, 2017 Expires: March 12, 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-13 draft-ietf-netmod-rfc6087bis-14
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 December 20, 2017. This Internet-Draft will expire on March 12, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 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 2, line 16 skipping to change at page 2, line 16
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.5.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7
3. General Documentation Guidelines . . . . . . . . . . . . . . . 8 3. General Documentation Guidelines . . . . . . . . . . . . . . . 8
3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8
3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8
3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9
3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9
3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10
3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10
3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11
3.7. Security Considerations Section . . . . . . . . . . . . . 11 3.7. Security Considerations Section . . . . . . . . . . . . . 11
3.8. IANA Considerations Section . . . . . . . . . . . . . . . 12 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 12
skipping to change at page 3, line 29 skipping to change at page 3, line 30
4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 36 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 36
4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 36 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 36
4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 37 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 37
4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 37 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 37
4.19.1. Conditional Augment Statements . . . . . . . . . . . . 37 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 37
4.19.2. Conditionally Mandatory Data Definition Statements . . 38 4.19.2. Conditionally Mandatory Data Definition Statements . . 38
4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 39 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 39
4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 40 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 40
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 41 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 41
4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 42 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 42
4.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 43 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 43
4.24. Performance Considerations . . . . . . . . . . . . . . . . 43 4.23.1. Combining Operational State and Configuration Data . . 43
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 44 4.23.2. Representing Operational Values of Configuration
4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 44 Data . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 44 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 44
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 44 4.24. Performance Considerations . . . . . . . . . . . . . . . . 48
4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 45 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 48
4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 45 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 49
4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 46 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 49
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 49
6. Security Considerations . . . . . . . . . . . . . . . . . . . 48 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 49
6.1. Security Considerations Section Template . . . . . . . . . 48 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 49
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 50
8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 51 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 6. Security Considerations . . . . . . . . . . . . . . . . . . . 53
9.1. Normative References . . . . . . . . . . . . . . . . . . . 53 6.1. Security Considerations Section Template . . . . . . . . . 53
9.2. Informative References . . . . . . . . . . . . . . . . . . 53 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 56 8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 56
A.1. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 56 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58
A.2. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 56 9.1. Normative References . . . . . . . . . . . . . . . . . . . 58
A.3. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 56 9.2. Informative References . . . . . . . . . . . . . . . . . . 58
A.4. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 56 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61
A.5. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 56 A.1. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.6. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 57 A.2. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.7. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 57 A.3. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.8. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 57 A.4. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.9. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 58 A.5. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 61
A.10. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 58 A.6. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.11. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 58 A.7. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.12. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.8. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.13. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 59 A.9. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 60 A.10. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 62 A.11. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 63
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64 A.12. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.13. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.14. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70
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 [RFC8040] the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040]
requires a modular set of data models, which can be reused and requires a modular set of data models, which can be reused and
extended over time. extended over time.
This document defines a set of usage guidelines for Standards Track This document defines a set of usage guidelines for Standards Track
documents containing [RFC7950] data models. YANG is used to define documents containing [RFC7950] data models. YANG is used to define
skipping to change at page 7, line 5 skipping to change at page 7, line 5
o version o version
o YANG o YANG
o YIN o YIN
Note that the term 'module' may be used as a generic term for a YANG Note that the term 'module' may be used as a generic term for a YANG
module or submodule. When describing properties that are specific to module or submodule. When describing properties that are specific to
submodules, the term 'submodule' is used instead. submodules, the term 'submodule' is used instead.
2.4. Terms 2.4. NMDA Terms
The following terms are defined in the Network Management Datastore
Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are not
redefined here:
o configuration
o conventional configuration datastore
o datastore
o operational state
o operational state datastore
2.5. Terms
The following terms are used throughout this document: The following terms are used throughout this document:
o published: A stable release of a module or submodule. For example o published: A stable release of a module or submodule. For example
the "Request for Comments" described in section 2.1 of [RFC2026] the "Request for Comments" described in section 2.1 of [RFC2026]
is considered a stable publication. is considered a stable publication.
o unpublished: An unstable release of a module or submodule. For o unpublished: An unstable release of a module or submodule. For
example the "Internet-Draft" described in section 2.2 of [RFC2026] example the "Internet-Draft" described in section 2.2 of [RFC2026]
is considered an unstable publication that is a work-in-progress, is considered an unstable publication that is a work-in-progress,
subject to change at any time. subject to change at any time.
o YANG fragment: A set of YANG statements that are not intended to o YANG fragment: A set of YANG statements that are not intended to
represent a complete YANG module or submodule. These statements represent a complete YANG module or submodule. These statements
are not intended for actual use, except to provide an example of are not intended for actual use, except to provide an example of
YANG statement usage. The invalid syntax "..." is sometimes used YANG statement usage. The invalid syntax "..." is sometimes used
to indicate that additional YANG statements would be present in a to indicate that additional YANG statements would be present in a
real YANG module. real YANG module.
2.4.1. YANG Tree Diagrams 2.5.1. YANG Tree Diagrams
A simplified graphical representation of the data model is used in A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is this document. The meaning of the symbols in these diagrams is
defined in [I-D.ietf-netmod-yang-tree-diagrams]. defined in [I-D.ietf-netmod-yang-tree-diagrams].
3. General Documentation Guidelines 3. General Documentation Guidelines
YANG data model modules under review are likely to be contained in YANG data model modules under review are likely to be contained in
Internet-Drafts. All guidelines for Internet-Draft authors MUST be Internet-Drafts. All guidelines for Internet-Draft authors MUST be
followed. The RFC Editor provides guidelines for authors of RFCs, followed. The RFC Editor provides guidelines for authors of RFCs,
skipping to change at page 23, line 12 skipping to change at page 23, line 12
The module namespace URI value MUST NOT be changed, once the document The module namespace URI value MUST NOT be changed, once the document
containing the module is published. containing the module is published.
The revision-date substatement within the import statement SHOULD be The revision-date substatement within the import statement SHOULD be
present if any groupings are used from the external module. present if any groupings are used from the external module.
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
RFC for an IETF module), then a reference-stmt SHOULD be present
within an import statement.
import ietf-yang-types {
prefix yang;
reference "RFC 6991";
}
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:
leaf reserved { leaf reserved {
type string; type string;
skipping to change at page 25, line 40 skipping to change at page 25, line 49
tag:example.com,2017:example-interfaces tag:example.com,2017:example-interfaces
tag:example.com,2017:example-system tag:example.com,2017:example-system
4.10. Top-Level Data Definitions 4.10. Top-Level Data Definitions
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 data 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 data was scope, so only one container representing operational state was
created. created.
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 41, line 44 skipping to change at page 41, line 44
"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 and operational It is sometimes useful to separate configuration data and operational
data, so that they do not not even share the exact same naming state, so that they do not not even share the exact same naming
characteristics. The correlation between configuration the characteristics. The correlation between configuration the
operational data that is affected by changes in configuration is a operational state that is affected by changes in configuration is a
complex problem. There may not be a simple 1:1 relationship between complex problem. There may not be a simple 1:1 relationship between
a configuration data node and an operational data node. Further work a configuration data node and an operational state node. Further
is needed in YANG to clarify this relationship. Protocol work may work is needed in YANG to clarify this relationship. Protocol work
also be needed to allow a client to retrieve this type of information may also be needed to allow a client to retrieve this type of
from a server. At this time the best practice is to clearly document information from a server. At this time the best practice is to
any relationship to other data structures in the "description" clearly document any relationship to other data structures in the
statement. "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 43, line 28 skipping to change at page 43, line 28
path "/foo/name"; path "/foo/name";
require-instance false; require-instance false;
} }
} }
leaf addon { leaf addon {
type string; type string;
mandatory true; mandatory true;
} }
} }
4.23. Operational Data 4.23. Operational State
In YANG, any data that has a "config" statement value of "false" The modeling operational state with YANG has been refined over time.
could be considered operational data. The relationship between At first, only data that has a "config" statement value of "false"
configuration (i.e., "config" statement has a value of "true") and was considered to be operational state. This data was not considered
operational data can be complex. to be part of any datastore, which made YANG XPath definition much
more complicated.
The original set of datastores defined in NETCONF (i.e., candidate, Operational state is now modeled using YANG according to new NMDA,
running, and startup) are not sufficient to fully manage a device and is now conceptually contained in the operational state datastore,
with multiple sources of configuration data. In additional, a which also includes the operational values of configuration data.
separate datastore is needed to store operational state and other There is no longer any need to duplicate data structures to provide
data such as statistics. Refer to separate configuration and operational state sections.
[I-D.ietf-netmod-revised-datastores] for details on this new "revised
datastore" architecture. Guidelines for usage of the new datastores This section describes some data modeling issues related to
(including the operational datastore) is defined in operational state, and guidelines for transitioning YANG data model
[I-D.dsdt-nmda-guidelines]. design to be NMDA-compatible.
4.23.1. Combining Operational State and Configuration Data
If possible, operational state SHOULD be combined with its associated
configuration data. This prevents duplication of key leafs and
ancestor nodes. It also prevents race conditions for retrieval of
dynamic entries, and allows configuration and operational state to be
retrieved together with minimal message overhead.
container foo {
...
// contains config=true and config=false nodes that have
// no corresponding config=true object (e.g., counters)
}
4.23.2. Representing Operational Values of Configuration Data
If possible the same data type SHOULD be used to represent the
configured value and the operational value, for a given leaf or leaf-
list object.
Sometimes the configured value set is different than the operational
value set for that object. For example, the "admin-state" and
"oper-state" leafs in [RFC7223]. In this case a separate object MAY
be used to represent the configured and operational values.
Sometimes the list keys are not identical for configuration data and
the corresponding operational state. In this case separate lists MAY
be used to represent the configured and operational values.
If it is not possible to combine configuration and operational state,
then the keys used to represent list entries SHOULD be the same type.
The "leafref" data type SHOULD be used in operational state for key
leafs that have corresponding configuration instances. The
"require-instance" statement MAY be set to "false" (in YANG 1.1
modules only) to indicate instances are allowed in the operational
state that do not exist in the associated configuration data.
The need to replicate objects or define different operational state
objects depends on the data model. It is not possible to define one
approach that will be optimal for all data models.
Designers SHOULD describe and justify any NMDA exceptions in detail,
such as the use of separate subtrees and/or separate leafs. The
"description" statements for both the configuration and the
operational state SHOULD be used for this purpose.
4.23.3. NMDA Transition Guidelines
YANG modules SHOULD be designed assuming they will be used on servers
supporting the operational state datastore. With this in mind, YANG
modules SHOULD define config "false" wherever they make sense to the
data model. Config "false" nodes SHOULD NOT be defined to provide
the operational value for configuration nodes, except when the value
space of a configured and operational values may differ, in which
case a distinct config "false" node SHOULD be defined to hold the
operational value for the configured node.
The following guidelines are meant to help modelers develop YANG
modules that will maximize the utility of the model with both current
and new implementations.
New modules and modules that are not concerned with the operational
state of configuration information SHOULD immediately be structured
to be NMDA-compatible, as described in Section 4.23.1. This
transition MAY be deferred if the module does not contain any
configuration datastore objects.
The remaining are options that MAY be followed during the time that
NMDA mechanisms are being defined.
(a) Modules that require immediate support for the NMDA features
SHOULD be structured for NMDA. A temporary non-NMDA version of this
type of module MAY exist, either an existing model or a model created
either by hand or with suitable tools that mirror the current
modeling strategies. Both the NMDA and the non-NMDA modules SHOULD
be published in the same document, with NMDA modules in the document
main body and the non-NMDA modules in a non-normative appendix. The
use of the non-NMDA module will allow temporary bridging of the time
period until NMDA implementations are available.
(b) For published models, the model should be republished with an
NMDA-compatible structure, deprecating non-NMDA constructs. For
example, the "ietf-interfaces" model in [RFC7223] will be
restructured as an NMDA-compatible model. The "/interfaces-state"
hierarchy will be marked "status deprecated". Models that mark their
"/foo-state" hierarchy with "status deprecated" will allow NMDA-
capable implementations to avoid the cost of duplicating the state
nodes, while enabling non-NMDA-capable implementations to utilize
them for access to the operational values.
(c) For models that augment models which have not been structured
with the NMDA, the modeler will have to consider the structure of the
base model and the guidelines listed above. Where possible, such
models should move to new revisions of the base model that are NMDA-
compatible. When that is not possible, augmenting "state" containers
SHOULD be avoided, with the expectation that the base model will be
re-released with the state containers marked as deprecated. It is
RECOMMENDED to augment only the "/foo" hierarchy of the base model.
Where this recommendation cannot be followed, then any new "state"
elements SHOULD be included in their own module.
4.23.3.1. Temporary non-NMDA Modules
A temporary non-NMDA module allows a non-NMDA aware client to access
operational state from an NMDA-compliant server. It contains the
top-level config=false data nodes that would have been defined in a
legacy YANG module (before NMDA).
A server that needs to support both NMDA and non-NMDA clients can
advertise both the new NMDA module and the temporary non-NMDA module.
A non-NMDA client can use separate "foo" and "foo-state" subtrees,
except the "foo-state" subtree is located in a different (temporary)
module. The NMDA module can be used by a non-NMDA client to access
the conventional configuration datastores, and the deprecated <get>
operation to access nested config=false data nodes.
To create the temporary non-NMDA model from an NMDA model, the
following steps can be taken:
o Change the module name by appending "-state" to the original
module name
o Change the namespace by appending "-state" to the original
namespace value
o Change the prefix by appending "-s" to the original prefix value
o Add an import to the original module (e.g., for typedef
definitions)
o Retain or create only the top-level nodes that have a "config"
statement value "false". These subtrees represent config=false
data nodes that were combined into the configuration subtree, and
therefore not available to non-NMDA aware clients. Set the
"status" statement to "deprecated" for each new node.
o The module description SHOULD clearly identify the module as a
temporary non-NMDA module
4.23.3.2. Example: Create a New NMDA Module
Create an NMDA-compliant module, using combined configuration and
state subtrees, whenever possible.
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain config=false nodes as needed
}
}
4.23.3.3. Example: Convert an old Non-NMDA Module
Do not remove non-compliant objects from existing modules. Instead,
change the status to "deprecated". At some point, usually after 1
year, the status MAY be changed to "obsolete".
Old Module:
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
}
container foo-state {
config false;
// operational state child nodes
}
}
Converted NMDA Module:
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain config=false nodes as needed
// will contain any data nodes from old foo-state
}
// keep original foo-state but change status to deprecated
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
4.23.3.4. Example: Create a Temporary NMDA Module:
Create a new module that contains the top-level operational state
data nodes that would have been available before they were combined
with configuration data nodes (to be NMDA compliant).
module example-foo-state {
namespace "urn:example.com:params:xml:ns:yang:example-foo-state";
prefix "foo-s";
// import new or converted module; not used in this example
import example-foo { prefix foo; }
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
4.24. Performance Considerations 4.24. Performance Considerations
It is generally likely that certain YANG statements require more It is generally likely that certain YANG statements require more
runtime resources than other statements. Although there are no runtime resources than other statements. Although there are no
performance requirements for YANG validation, the following performance requirements for YANG validation, the following
information MAY be considered when designing YANG data models: information MAY be considered when designing YANG data models:
o Lists are generally more expensive than containers o Lists are generally more expensive than containers
skipping to change at page 50, line 11 skipping to change at page 55, line 11
operations and their sensitivity/vulnerability: operations and their sensitivity/vulnerability:
<list RPC operations and state why they are sensitive> <list RPC operations and state why they are sensitive>
7. Acknowledgments 7. Acknowledgments
The structure and contents of this document are adapted from The structure and contents of this document are adapted from
[RFC4181], guidelines for MIB Documents, by C. M. Heard. [RFC4181], guidelines for MIB Documents, by C. M. Heard.
The working group thanks Martin Bjorklund, Juergen Schoenwaelder, The working group thanks Martin Bjorklund, Juergen Schoenwaelder,
Ladislav Lhotka, and Jernej Tuljak for their extensive reviews and Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive
contributions to this document. reviews and contributions to this document.
8. Changes Since RFC 6087 8. Changes Since RFC 6087
The following changes have been made to the guidelines published in The following changes have been made to the guidelines published in
[RFC6087]: [RFC6087]:
o Updated NETCONF reference from RFC 4741 to RFC 6241 o Updated NETCONF reference from RFC 4741 to RFC 6241
o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242
skipping to change at page 52, line 10 skipping to change at page 57, line 10
o Clarified namespace and domain conventions for example modules o Clarified namespace and domain conventions for example modules
o Clarified conventions for identifying code components o Clarified conventions for identifying code components
o Added YANG 1.1 guidelines o Added YANG 1.1 guidelines
o Added Data Model Constraints section o Added Data Model Constraints section
o Added mention of RESTCONF protocol o Added mention of RESTCONF protocol
o Added mention of Revised Datastores and associated guidelines o Added guidelines for NMDA Revised Datastores
9. References 9. References
9.1. Normative References 9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
skipping to change at page 53, line 41 skipping to change at page 58, line 41
<http://www.rfc-editor.org/info/rfc7950>. <http://www.rfc-editor.org/info/rfc7950>.
[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>.
9.2. Informative References 9.2. Informative References
[I-D.dsdt-nmda-guidelines]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Guidelines for YANG Module Authors
(NMDA)", draft-dsdt-nmda-guidelines-01 (work in progress),
May 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-02 Architecture", draft-ietf-netmod-revised-datastores-04
(work in progress), May 2017. (work in progress), August 2017.
[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-00 (work in draft-ietf-netmod-yang-tree-diagrams-01 (work in
progress), June 2017. progress), June 2017.
[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 56, line 9 skipping to change at page 61, line 9
<http://www.rfc-editor.org/info/rfc7841>. <http://www.rfc-editor.org/info/rfc7841>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<http://www.rfc-editor.org/info/rfc8040>. <http://www.rfc-editor.org/info/rfc8040>.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. v12 to v13 A.1. 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
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.2. v11 to v12 A.3. v11 to v12
o fix incorrect location of new Module Usage Examples section o fix incorrect location of new Module Usage Examples section
A.3. v10 to v11 A.4. 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.4. v09 to v10 A.5. 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.5. v08 to v09 A.6. 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.6. v07 to v08 A.7. 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.7. v06 to v07 A.8. 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.8. v05 to v06 A.9. 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
skipping to change at page 58, line 14 skipping to change at page 63, line 25
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.9. v04 to v05 A.10. 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 58, line 36 skipping to change at page 63, line 47
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.10. v03 ot v04 A.11. 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.11. v02 to v03 A.12. 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.12. v01 to v02 A.13. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.13. v00 to v01 A.14. 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 2.4.1 so RFCs with YANG 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 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
o Issue 2: XPath function restrictions: Added paragraphs in XPath o Issue 2: XPath function restrictions: Added paragraphs in XPath
usage section for 'id', 'namespace-uri', 'name', and 'lang' usage section for 'id', 'namespace-uri', 'name', and 'lang'
functions functions
o Issue 3: XPath function document order issues: Added paragraph in o Issue 3: XPath function document order issues: Added paragraph in
XPath usage section about node-set ordering for 'local-name', XPath usage section about node-set ordering for 'local-name',
 End of changes. 39 change blocks. 
94 lines changed or deleted 351 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/