draft-ietf-netmod-rfc6087bis-05.txt   draft-ietf-netmod-rfc6087bis-06.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track October 19, 2015 Intended status: Standards Track March 20, 2016
Expires: April 21, 2016 Expires: September 21, 2016
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-rfc6087bis-05 draft-ietf-netmod-rfc6087bis-06
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) implementations that utilize YANG Configuration Protocol (NETCONF) implementations that utilize YANG
data model modules. data model modules.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 21, 2016. This Internet-Draft will expire on September 21, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2016 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 18 skipping to change at page 2, line 18
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 5
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7 3. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 7
4. General Documentation Guidelines . . . . . . . . . . . . . . . 8 4. General Documentation Guidelines . . . . . . . . . . . . . . . 8
4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 4.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8
4.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 9
4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9
4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 9 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10
4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10
4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 11
4.6. Security Considerations Section . . . . . . . . . . . . . 10 4.6. Security Considerations Section . . . . . . . . . . . . . 11
4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 12
4.7.1. Documents that Create a New Namespace . . . . . . . . 11 4.7.1. Documents that Create a New Namespace . . . . . . . . 12
4.7.2. Documents that Extend an Existing Namespace . . . . . 12 4.7.2. Documents that Extend an Existing Namespace . . . . . 12
4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 4.8. Reference Sections . . . . . . . . . . . . . . . . . . . . 12
4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13
4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 12 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 13 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 13 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14
5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 15 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16
5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 15 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16
5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 16 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17
5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 17 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18
5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 17 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18
5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 18 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19
5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 19 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20
5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 20 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21
5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 20 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21
5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 21 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22
5.8. Module Header, Meta, and Revision Statements . . . . . . . 22 5.8. Module Header, Meta, and Revision Statements . . . . . . . 23
5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 23 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24
5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 24 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25
5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 24 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 25
5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 25 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26
5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 25 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 26
5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 26 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 27
5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 28
5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 27 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 29
5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 28 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 29
5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 28 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 31
5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 30 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 31
5.16. Notification Definitions . . . . . . . . . . . . . . . . . 30 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 32
5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 31 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 32
5.18. Augment Statements . . . . . . . . . . . . . . . . . . . . 31 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 32
5.18.1. Conditional Augment Statements . . . . . . . . . . . . 32 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 33
5.18.2. Conditionally Mandatory Data Definition Statements . . 32 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 33
5.19. Deviation Statements . . . . . . . . . . . . . . . . . . . 33 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 33
5.20. Extension Statements . . . . . . . . . . . . . . . . . . . 34 5.19.2. Conditionally Mandatory Data Definition Statements . . 34
5.21. Data Correlation . . . . . . . . . . . . . . . . . . . . . 35 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 35
5.22. Operational State . . . . . . . . . . . . . . . . . . . . 36 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 36
5.23. Performance Considerations . . . . . . . . . . . . . . . . 38 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 37
5.24. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 38 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 38
5.24.1. Importing Multiple Revisions . . . . . . . . . . . . . 39 5.24. Performance Considerations . . . . . . . . . . . . . . . . 40
5.24.2. Using Feature Logic . . . . . . . . . . . . . . . . . 39 5.25. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 40
5.24.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 39 5.25.1. Importing Multiple Revisions . . . . . . . . . . . . . 41
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 5.25.2. Using Feature Logic . . . . . . . . . . . . . . . . . 41
7. Security Considerations . . . . . . . . . . . . . . . . . . . 41 5.25.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 41
7.1. Security Considerations Section Template . . . . . . . . . 41 5.25.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 41
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 5.26. Updating YANG Modules (Published vs. Unpublished) . . . . 42
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 44 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7. Security Considerations . . . . . . . . . . . . . . . . . . . 44
10.1. Normative References . . . . . . . . . . . . . . . . . . . 45 7.1. Security Considerations Section Template . . . . . . . . . 44
10.2. Informative References . . . . . . . . . . . . . . . . . . 46 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 47 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 47
A.1. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . . 47 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49
A.2. 03 ot 04 . . . . . . . . . . . . . . . . . . . . . . . . . 47 10.1. Normative References . . . . . . . . . . . . . . . . . . . 49
A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . . 47 10.2. Informative References . . . . . . . . . . . . . . . . . . 50
A.4. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . . 47 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 51
A.5. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 48 A.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 51
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 49 A.2. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 51
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 51 A.3. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 52
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 53 A.4. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 52
A.5. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 52
A.6. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 52
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 54
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 56
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 58
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] requires a modular set the Network Configuration Protocol [RFC6241] requires a modular set
of data models, which can be reused and extended over time. of data models, which can be reused and 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 [I-D.ietf-netmod-rfc6020bis] data models. YANG documents containing [I-D.ietf-netmod-rfc6020bis] data models. YANG
is used to define the data structures, protocol operations, and is used to define the data structures, protocol operations, and
skipping to change at page 9, line 5 skipping to change at page 8, line 45
Each YANG module or submodule contained within an Internet-Draft or Each YANG module or submodule contained within an Internet-Draft or
RFC is considered to be a code component. The strings "<CODE RFC is considered to be a code component. The strings "<CODE
BEGINS>" and "<CODE ENDS>" MUST be used to identify each code BEGINS>" and "<CODE ENDS>" MUST be used to identify each code
component. component.
The "<CODE BEGINS>" tag SHOULD be followed by a string identifying The "<CODE BEGINS>" tag SHOULD be followed by a string identifying
the file name specified in Section 5.2 of the file name specified in Section 5.2 of
[I-D.ietf-netmod-rfc6020bis]. The following example is for the [I-D.ietf-netmod-rfc6020bis]. The following example is for the
'2010-01-18' revision of the 'ietf-foo' module: '2010-01-18' revision of the 'ietf-foo' module:
<CODE BEGINS> file "ietf-foo@2010-01-18.yang" <CODE BEGINS> file "ietf-foo@2016-03-20.yang"
module ietf-foo { module ietf-foo {
// ... namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
revision 2010-01-18 { prefix "foo";
organization "...";
contact "...";
description "...";
revision 2016-03-20 {
description "Latest revision"; description "Latest revision";
reference "RFC XXXX"; reference "RFC XXXX";
} }
// ... more statements
}
<CODE ENDS>
4.1.1. Example Modules
Note that the <CODE BEGINS> convention MUST NOT be used for example
modules or module fragments. Instead the following convention is
defined for complete example modules:
<EXAMPLE BEGINS> file "example-bar@2016-03-20.yang"
module example-bar {
// ...
revision 2016-03-20;
// contains complete module example, intended to compile
// ... // ...
} }
<CODE ENDS> <EXAMPLE ENDS>
Note that this convention MUST NOT be used for example modules or YANG module fragments MUST NOT use the <CODE BEGINS> or <EXAMPLE
module fragments. BEGINS> conventions, in order to make sure module extraction tools
will ignore them:
leaf last-change-time {
type yang:date-and-time;
...
}
4.2. Terminology Section 4.2. Terminology Section
A terminology section MUST be present if any terms are defined in the A terminology section MUST be present if any terms are defined in the
document or if any terms are imported from other documents. document or if any terms are imported from other documents.
If YANG tree diagrams are used, then a sub-section explaining the If YANG tree diagrams are used, then a sub-section explaining the
YANG tree diagram syntax MUST be present, containing the following YANG tree diagram syntax MUST be present, containing the following
text: text:
skipping to change at page 15, line 12 skipping to change at page 16, line 12
The following guidelines apply to prefix usage of the current (local) The following guidelines apply to prefix usage of the current (local)
module: module:
o The local module prefix SHOULD be used instead of no prefix in all o The local module prefix SHOULD be used instead of no prefix in all
path expressions. path expressions.
o The local module prefix MUST be used instead of no prefix in all o The local module prefix MUST be used instead of no prefix in all
"default" statements for an "identityref" or "instance-identifier" "default" statements for an "identityref" or "instance-identifier"
data type data type
o The lcaol module prefix MAY be used for references to typedefs, o The local module prefix MAY be used for references to typedefs,
groupings, extensions, features, and identities defined in the groupings, extensions, features, and identities defined in the
module. module.
Prefix values SHOULD be short, but also likely to be unique. Prefix Prefix values SHOULD be short, but also likely to be unique. Prefix
values SHOULD NOT conflict with known modules that have been values SHOULD NOT conflict with known modules that have been
previously published. previously published.
5.3. Identifiers 5.3. Identifiers
Identifiers for all YANG identifiers in published modules MUST be Identifiers for all YANG identifiers in published modules MUST be
skipping to change at page 22, line 6 skipping to change at page 23, line 6
'obsolete'. The status SHOULD NOT be changed from 'current' directly 'obsolete'. The status SHOULD NOT be changed from 'current' directly
to 'obsolete'. An object SHOULD be available for at least one year to 'obsolete'. An object SHOULD be available for at least one year
with 'deprecated' status before it is changed to 'obsolete'. with 'deprecated' status before it is changed to 'obsolete'.
The module or submodule name MUST NOT be changed, once the document The module or submodule name MUST NOT be changed, once the document
containing the module or submodule is published. containing the module or submodule is published.
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 imports 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 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.
skipping to change at page 24, line 23 skipping to change at page 25, line 23
http://example.com/ns/example-interfaces http://example.com/ns/example-interfaces
http://example.com/ns/example-system http://example.com/ns/example-system
5.10. Top-Level Data Definitions 5.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 state SHOULD be The separation of configuration data and operational data SHOULD be
considered carefully. It is often useful to define separate top- considered carefully. It is often useful to define separate top-
level containers for configuration and non-configuration data. level containers for configuration and non-configuration data.
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
skipping to change at page 31, line 47 skipping to change at page 32, line 47
feature feature1 { feature feature1 {
description "Some protocol feature"; description "Some protocol feature";
} }
feature feature2 { feature feature2 {
if-feature "feature1"; if-feature "feature1";
description "Another protocol feature"; description "Another protocol feature";
} }
5.18. Augment Statements 5.18. YANG Data Node Constraints
5.18.1. Controlling Quantity
The "min-elements" and "max-elements" statements can be use to
control how many list or leaf-list instances are required for a
particular data node. YANG constraint statements SHOULD be used to
identify conditions that apply to all implementations of the data
model. If platform-specific limitations (e.g., the "max-elements"
supported for a particular list) are relevant to operations, then a
data model definition statement (e.g., "max-ports" leaf) SHOULD be
used to identify the limit.
5.18.2. must vs. when
The "must" and "when" YANG statements are used to provide cross-
object referential tests. They have very different behavior. The
"when" statement causes data node instances to be silently deleted as
soon as the condition becomes false. A false "when" expression is
not considered to be an error.
The "when" statement SHOULD be used together with the "augment" or
"uses" statements to achieve conditional model composition. The
condition SHOULD be based on static properties of the augmented entry
(e.g., list key leafs).
The "must" statement causes a datastore validation error if the
condition is false. This statement SHOULD be used for enforcing
parameter value restrictions that involve more than one data node
(e.g., end-time parameter must be after the start-time parameter).
5.19. Augment Statements
The YANG "augment" statement is used to define a set of data The YANG "augment" statement is used to define a set of data
definition statements that will be added as child nodes of a target definition statements that will be added as child nodes of a target
data node. The module namespace for these data nodes will be the data node. The module namespace for these data nodes will be the
augmenting module, not the augmented module. augmenting module, not the augmented module.
A top-level "augment" statement SHOULD NOT be used if the target data A top-level "augment" statement SHOULD NOT be used if the target data
node is in the same module or submodule as the evaluated "augment" node is in the same module or submodule as the evaluated "augment"
statement. The data definition statements SHOULD be added inline statement. The data definition statements SHOULD be added inline
instead. instead.
5.18.1. Conditional Augment Statements 5.19.1. Conditional Augment Statements
The "augment" statement is often used together with the "when" The "augment" statement is often used together with the "when"
statement and/or "if-feature" statement to make the augmentation statement and/or "if-feature" statement to make the augmentation
conditional on some portion of the data model. conditional on some portion of the data model.
The following example from [RFC7223] shows how a conditional The following example from [RFC7223] shows how a conditional
container called "ethernet" is added to the "interface" list only for container called "ethernet" is added to the "interface" list only for
entries of the type "ethernetCsmacd". entries of the type "ethernetCsmacd".
augment "/if:interfaces/if:interface" { augment "/if:interfaces/if:interface" {
when "if:type = 'ianaift:ethernetCsmacd'"; when "if:type = 'ianaift:ethernetCsmacd'";
container ethernet { container ethernet {
leaf duplex { leaf duplex {
... ...
} }
} }
} }
5.18.2. Conditionally Mandatory Data Definition Statements 5.19.2. Conditionally Mandatory Data Definition Statements
YANG has very specific rules about how configuration data can be YANG has very specific rules about how configuration data can be
updated in new releases of a module. These rules allow an "old updated in new releases of a module. These rules allow an "old
client" to continue interoperating with a "new server". client" to continue interoperating with a "new server".
If data nodes are added to an existing entry, the old client MUST NOT If data nodes are added to an existing entry, the old client MUST NOT
be required to provide any mandatory parameters that were not in the be required to provide any mandatory parameters that were not in the
original module definition. original module definition.
It is possible to add conditional augment statements such that the It is possible to add conditional augment statements such that the
skipping to change at page 33, line 13 skipping to change at page 35, line 5
The XPath "when" statement condition MUST NOT reference data outside The XPath "when" statement condition MUST NOT reference data outside
of target data node because the client does not have any control over of target data node because the client does not have any control over
this external data. this external data.
In the following dummy example, it is OK to augment the "interface" In the following dummy example, it is OK to augment the "interface"
entry with "mandatory-leaf" because the augmentation depends on entry with "mandatory-leaf" because the augmentation depends on
support for "some-new-iftype". The old client does not know about support for "some-new-iftype". The old client does not know about
this type so it would never select this type, and therefore not be this type so it would never select this type, and therefore not be
adding a mandatory data node. adding a mandatory data node.
module my-module { module example-module {
... namespace "http://example.com/ns/example-module";
prefix mymod;
import iana-if-type { prefix iana; }
import ietf-interfaces { prefix if; }
identity some-new-iftype { identity some-new-iftype {
base iana:iana-interface-type; base iana:iana-interface-type;
} }
augment "/if:interfaces/if:interface" { augment "/if:interfaces/if:interface" {
when "if:type = 'mymod:some-new-iftype'"; when "if:type = 'mymod:some-new-iftype'";
leaf mandatory-leaf { leaf mandatory-leaf {
mandatory true; mandatory true;
skipping to change at page 33, line 43 skipping to change at page 35, line 39
packaged in a way that requires the client to be aware of the packaged in a way that requires the client to be aware of the
mandatory data nodes if it is aware of the condition for this data. mandatory data nodes if it is aware of the condition for this data.
In the example above, the "some-new-iftype" identity is defined in In the example above, the "some-new-iftype" identity is defined in
the same module as the "mandatory-leaf" data definition statement. the same module as the "mandatory-leaf" data definition statement.
This practice is not safe for identities defined in a common module This practice is not safe for identities defined in a common module
such as "iana-if-type" because the client is not required to know such as "iana-if-type" because the client is not required to know
about "my-module" just because it knows about the "iana-if-type" about "my-module" just because it knows about the "iana-if-type"
module. module.
5.19. Deviation Statements 5.20. Deviation Statements
The YANG "deviation" statement cannot appear in IETF YANG modules, The YANG "deviation" statement cannot appear in IETF YANG modules,
but it can be useful for documenting server capabilities. Deviation but it can be useful for documenting server capabilities. Deviation
statements are not reusable and typically not shared across all statements are not reusable and typically not shared across all
platforms. platforms.
There are several reasons that deviations might be needed in an There are several reasons that deviations might be needed in an
implementation, e.g., an object cannot be supported on all platforms, implementation, e.g., an object cannot be supported on all platforms,
or feature delivery is done in multiple development phases. or feature delivery is done in multiple development phases.
skipping to change at page 34, line 35 skipping to change at page 36, line 30
} }
Correct: (max-elements in a deviation) Correct: (max-elements in a deviation)
deviation /bk:backups/bk:backup { deviation /bk:backups/bk:backup {
deviate add { deviate add {
max-elements 10; max-elements 10;
} }
} }
5.20. Extension Statements 5.21. Extension Statements
The YANG "extension" statement is used to specify external The YANG "extension" statement is used to specify external
definitions. This appears in the YANG syntax as an definitions. This appears in the YANG syntax as an
"unknown-statement". Usage of extension statements in a published "unknown-statement". Usage of extension statements in a published
module needs to be considered carefully. module needs to be considered carefully.
The following guidelines apply to the usage of YANG extensions: The following guidelines apply to the usage of YANG extensions:
o The semantics of the extension MUST NOT contradict any YANG o The semantics of the extension MUST NOT contradict any YANG
statements. Extensions can add semantics not covered by the statements. Extensions can add semantics not covered by the
skipping to change at page 35, line 14 skipping to change at page 37, line 9
not, identify what conditions apply that would require not, identify what conditions apply that would require
implementation of the extension. implementation of the extension.
o The extension MUST clearly identify where it can be used within o The extension MUST clearly identify where it can be used within
other YANG statements. other YANG statements.
o The extension MUST clearly identify if YANG statements or other o The extension MUST clearly identify if YANG statements or other
extensions are allowed or required within the extension as sub- extensions are allowed or required within the extension as sub-
statements. statements.
5.21. Data Correlation 5.22. Data Correlation
Data can be correlated in various ways, using common data types, Data can be correlated in various ways, using common data types,
common data naming, and common data organization. There are several common data naming, and common data organization. There are several
ways to extend the functionality of a module, based on the degree of ways to extend the functionality of a module, based on the degree of
coupling between the old and new functionality: coupling between the old and new functionality:
o inline: update the module with new protocol-accessible objects. o inline: update the module with new protocol-accessible objects.
The naming and data organization of the original objects is used. The naming and data organization of the original objects is used.
The new objects are in the original module namespace. The new objects are in the original module namespace.
skipping to change at page 35, line 44 skipping to change at page 37, line 39
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 and operational
state, so that they do not not even share the exact same naming data, 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 state data that is affected by changes in configuration operational data that is affected by changes in configuration is a
is a complex problem. There may not be a simple 1:1 relationship complex problem. There may not be a simple 1:1 relationship between
between a configuration data node and an operational data node. a configuration data node and an operational data node. Further work
Further work is needed in YANG to clarify this relationship. is needed in YANG to clarify this relationship. Protocol work may
Protocol work may also be needed to allow a client to retrieve this also be needed to allow a client to retrieve this type of information
type of information from a server. At this time the best practice is from a server. At this time the best practice is to clearly document
to clearly document any relationship to other data structures in the any relationship to other data structures in the "description"
"description" statement. statement.
5.22. Operational State 5.23. Operational Data
In YANG, any data that has a "config" statement value of "false" In YANG, any data that has a "config" statement value of "false"
could be considered operational state. The relationship between could be considered operational data. The relationship between
configuration (i.e., "config" statement has a value of "true") and configuration (i.e., "config" statement has a value of "true") and
operational state can be complex. operational data can be complex.
One challenge for client developers is determining if the configured One challenge for client developers is determining if the configured
value is being used, which requires the developer to know which value is being used, which requires the developer to know which
operational state parameters are associated with the particular operational data parameters are associated with the particular
configuration object (or group of objects). configuration object (or group of objects).
The simplest interaction between configuration and operational state In the simplest use-cases , there is no interaction between
is "none". For example, the arbitrary administrative name or configuration and operational data. For example, the arbitrary
sequence number assigned to an access control rule. The configured administrative name or sequence number assigned to an access control
value is always the value that is being used by the system. rule. The configured value is always the value that is being used by
the system.
However, some configuration parameters interact with routing and However, some configuration parameters interact with routing and
other signalling protocols, such that the operational value in use by other signalling protocols, such that the operational value in use by
the system may not be the same as the configured value. Other the system may not be the same as the configured value. Other
parameters specify the desired state, but environmental and other parameters specify the desired state, but environmental and other
factors can cause the actual state to be different. factors can cause the actual state to be different.
For example a "temperature" configuration setting only represents the For example a "temperature" configuration setting only represents the
desired temperature. An operational state parameter is needed that desired temperature. An operational data parameter is needed that
reports the actual temperature in order to determine if the cooling reports the actual temperature in order to determine if the cooling
system is operating correctly. YANG has no mechanism other than the system is operating correctly. YANG has no mechanism other than the
"description" statement to associate the desired temperature and the "description" statement to associate the desired temperature and the
actual temperature. actual temperature.
Careful consideration needs to be given to the location of Careful consideration needs to be given to the location of
operational state data. It can either be located within the operational data. It can either be located within the configuration
configuration subtree for which it applies, or it can be located subtree for which it applies, or it can be located outside the
outside the particular configuration subtree. Placing operation particular configuration subtree. Placing operational data within
state within the configuration subtree is appropriate if the the configuration subtree is appropriate if the operational values
operational values can only exist if the configuration exists. can only exist if the configuration exists.
The "interfaces" and "interfaces-state" subtrees defined in [RFC7223] The "interfaces" and "interfaces-state" subtrees defined in [RFC7223]
are an example of a complex relationship between configuration and are an example of a complex relationship between configuration and
operational state. The operational values can include interface operational data. The operational values can include interface
entries that have been discovered or initialized by the system. An entries that have been discovered or initialized by the system. An
interface may be in use that has not been configured at all. interface may be in use that has not been configured at all.
Therefore, the operational state for an interface cannot be located Therefore, the operational data for an interface cannot be located
within the configuration for that same interface. within the configuration for that same interface.
Sometimes the configured value represents some sort of procedure to Sometimes the configured value represents some sort of procedure to
be followed, in which the system will select an actual value, based be followed, in which the system will select an actual value, based
on protocol negotiation. on protocol negotiation.
leaf duplex-admin-mode { leaf duplex-admin-mode {
type enumeration { type enumeration {
enum auto; enum auto;
enum half; enum half;
skipping to change at page 37, line 37 skipping to change at page 39, line 34
will never contain the value "auto". It will always contain the will never contain the value "auto". It will always contain the
result of the auto-negotiation, such as "half" or "full". This is result of the auto-negotiation, such as "half" or "full". This is
just one way in which the configuration data model is not exactly the just one way in which the configuration data model is not exactly the
same as the operational data model. Another is if the detailed same as the operational data model. Another is if the detailed
properties of the data are different for configured vs. learned properties of the data are different for configured vs. learned
entries. entries.
If all the data model properties are aligned between configuration If all the data model properties are aligned between configuration
and operational data, then it can be useful to define the and operational data, then it can be useful to define the
configuration parameters within a grouping, and then replicate that configuration parameters within a grouping, and then replicate that
grouping within the operational state portion of the data model. grouping within the operational data portion of the data model.
grouping parms { grouping parms {
// do not use config-stmt in any of the nodes // do not use config-stmt in any of the nodes
// placed in this grouping // placed in this grouping
} }
container foo { container foo {
uses parms; // these are all config=true by default uses parms; // these are all config=true by default
state { state {
config false; // only exists if foo config exists config false; // only exists if foo config exists
uses parms; uses parms;
} }
} }
Note that this mechanism can also be used if the configuration and Note that this mechanism can also be used if the configuration and
operational state data are in separate sub-trees: operational data are in separate sub-trees:
container bar { // bar config can exist without bar-state container bar { // bar config can exist without bar-state
config true; config true;
uses parms; uses parms;
} }
container bar-state { // bar-state can exist without bar container bar-state { // bar-state can exist without bar
config false; config false;
uses parms; uses parms;
} }
The need to replicate objects or define different operational state The need to replicate objects or define different operational data
objects depends on the data model. It is not possible to define one objects depends on the data model. It is not possible to define one
approach that will be optimal for all data models. Designers SHOULD approach that will be optimal for all data models. Designers SHOULD
describe the relationship in detail between configuration objects and describe the relationship in detail between configuration objects and
any associated operational state objects. The "description" any associated operational data objects. The "description"
statements for both the configuration and the operational state statements for both the configuration and the operational data SHOULD
SHOULD be used for this purpose. be used for this purpose.
5.23. Performance Considerations 5.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
o "when-stmt" evaluation is generally more expensive than o "when-stmt" evaluation is generally more expensive than
"if-feature" or "choice" statements "if-feature" or "choice" statements
o "must" statement is generally more expensive than "min-entries", o "must" statement is generally more expensive than "min-entries",
"max-entries", "mandatory", or "unique" statements "max-entries", "mandatory", or "unique" statements
o "identityref" leafs are generally more expensive than o "identityref" leafs are generally more expensive than
"enumeration" leafs "enumeration" leafs
o "leafref" and "instance-identifier" types with "requite-instance" o "leafref" and "instance-identifier" types with "require-instance"
set to true are generally more expensive than if set to true are generally more expensive than if
"require-instance" is set to false "require-instance" is set to false
5.24. YANG 1.1 Guidelines 5.25. YANG 1.1 Guidelines
TODO: need more input on YANG 1.1 guidelines The set of YANG 1.1 guidelines will grow as operational experience is
gained with the new language features. This section contains an
initial set of guidelines.
5.24.1. Importing Multiple Revisions 5.25.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 the authors can
demonstrate that the "avoided" definitions from most recent of the demonstrate that the "avoided" definitions from the most recent of
multiple revisions are somehow broken or harmful to interoperability. the multiple revisions are somehow broken or harmful to
interoperability.
5.24.2. Using Feature Logic 5.25.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. This reduces server implementation complexity and might possible. Features are advertised by the server and objects
reduce runtime resource requirements as well. conditional by if-feature are conceptually grouped together. There
is no such commonality supported for "when" statements.
5.24.3. anyxml vs. anydata Features generally require less server implementation complexity and
runtime resources than objects that use "when" statements. Features
are generally static (i.e., set when module is loaded and not changed
at runtime). However every client edit might cause a "when"
statement result to change.
5.25.3. anyxml vs. anydata
The "anyxml" statement MUST NOT be used to represent a conceptual The "anyxml" statement MUST NOT be used to represent a conceptual
subtree of YANG data nodes. The "anydata" statement MUST be used for subtree of YANG data nodes. The "anydata" statement MUST be used for
this purpose. this purpose.
5.25.4. action vs. rpc
The use of "action" statements or "rpc" statements is a subjective
design decision. RPC operations are not associated with any
particular data node. Actions are associated with a specific data
node definition. An "action" statement SHOULD be used if the
protocol operation is specific to a subset of all data nodes instead
of all possible data nodes.
The same action name MAY be used in different definitions within
different data node. For example, a "reset" action defined with a
data node definition for an interface might have different parameters
than for a power supply or a VLAN. The same action name SHOULD be
used to represent similar semantics.
The NETCONF Access Control Model (NACM) [RFC6536] does not support
parameter access control for RPC operations. The user is given
permission (or not) to invoke the RPC operation with any parameters.
For example, if each client is only allowed to reset their own
interface, then NACM cannot be used.
For example, NACM cannot enforce access access control based on the
value of the "interface" parameter, only the "reset" operation
itself:
rpc reset {
input {
leaf interface {
type if:interface-ref;
mandatory true;
description "The interface to reset.";
}
}
}
However, NACM can enforce access access control for individual
interface instances, using a "reset" action, If the user does not
have read access to the specific "interface" instance, then it cannot
invoke the "reset" action for that interface instance:
container interfaces {
list interface {
...
action reset { }
}
}
5.26. Updating YANG Modules (Published vs. Unpublished)
YANG modules can change over time. Typically, new data model
definitions are needed to support new features. YANG update rules
defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be
followed for published modules. They MAY be followed for unpublished
modules.
The YANG update rules only apply to published module revisions. Each
organization will have their own way to identity published work which
is considered to be stable, and unpublished work which is considered
to be unstable. For example, in the IETF, the RFC document is used
for published work, and the Internet-Draft is used for unpublished
work.
6. IANA Considerations 6. IANA Considerations
This document registers one URI in the IETF XML registry [RFC3688]. This document registers one URI in the IETF XML registry [RFC3688].
The following registration has been made: The following registration has been made:
URI: urn:ietf:params:xml:ns:yang:ietf-template URI: urn:ietf:params:xml:ns:yang:ietf-template
Registrant Contact: The NETMOD WG of the IETF. Registrant Contact: The NETMOD WG of the IETF.
skipping to change at page 45, line 5 skipping to change at page 47, line 51
o Clarify usage of 'uint64' and 'int64' data types o Clarify usage of 'uint64' and 'int64' data types
o Added text on YANG feature usage o Added text on YANG feature usage
o Added Identifier Naming Conventions o Added Identifier Naming Conventions
o Clarified use of mandatory nodes with conditional augmentations o Clarified use of mandatory nodes with conditional augmentations
o Clarified namespace and domain conventions for example modules o Clarified namespace and domain conventions for example modules
o Added <EXAMPLE BEGINS> and <EXAMPLE ENDS> convention
o Added YANG 1.1 guidelines
o Added Data Model Constraints section
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-netmod-rfc6020bis] [I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "YANG - A Data Modeling Language for the Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", Network Configuration Protocol (NETCONF)",
draft-ietf-netmod-rfc6020bis-07 (work in progress), draft-ietf-netmod-rfc6020bis-07 (work in progress),
September 2015. September 2015.
skipping to change at page 46, line 22 skipping to change at page 50, line 22
[RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB
Documents", BCP 111, RFC 4181, September 2005. Documents", BCP 111, RFC 4181, September 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG [RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG
Data Model Documents", RFC 6087, January 2011. Data Model Documents", RFC 6087, January 2011.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
March 2012.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, May 2014. Management", RFC 7223, May 2014.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. 04 to 05 A.1. v05 to v06
o Changed example 'my-module' to 'example-module'
o Added section Updating YANG Modules (Published vs. Unpublished)
o Added Example Modules section
o Added "<EXAMPLE BEGINS>" convention for full example modules
o Added section on using action vs. rpc
o Changed term "operational state" to "operational data"
o Added section on YANG Data Node Constraints
o Added guidelines on using must vs. when statements
o Made ietf-foo module validate for I-D submission
A.2. 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 47, line 31 skipping to change at page 52, line 5
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.2. 03 ot 04 A.3. 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.3. 02 to 03 A.4. 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.4. 01 to 02 A.5. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.5. 00 to 01 A.6. 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
skipping to change at page 51, line 7 skipping to change at page 56, line 7
Checking for correct syntax, however, is only part of the job. Checking for correct syntax, however, is only part of the job.
It is just as important to actually read the YANG module document It is just as important to actually read the YANG module document
from the point of view of a potential implementor. It is from the point of view of a potential implementor. It is
particularly important to check that description statements are particularly important to check that description statements are
sufficiently clear and unambiguous to allow interoperable sufficiently clear and unambiguous to allow interoperable
implementations to be created. implementations to be created.
Appendix C. YANG Module Template Appendix C. YANG Module Template
<CODE BEGINS> file "ietf-template@2010-05-18.yang" <CODE BEGINS> file "ietf-template@2016-03-20.yang"
module ietf-template { module ietf-template {
// replace this string with a unique namespace URN value // replace this string with a unique namespace URN value
namespace namespace
"urn:ietf:params:xml:ns:yang:ietf-template"; "urn:ietf:params:xml:ns:yang:ietf-template";
// replace this string, and try to pick a unique prefix // replace this string, and try to pick a unique prefix
prefix "temp"; prefix "temp";
skipping to change at page 52, line 19 skipping to change at page 57, line 17
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove // RFC Ed.: replace XXXX with actual RFC number and remove
// this note // this note
reference "RFC XXXX"; reference "RFC XXXX";
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from RFC XXXX // Note: extracted from RFC XXXX
// replace '2010-05-18' with the module publication date // replace '2016-03-20' with the module publication date
// The format is (year-month-day) // The format is (year-month-day)
revision "2010-05-18" { revision "2016-03-20" {
description description "what changed in this revision";
"Initial version"; reference "document containing this module";
} }
// extension statements // extension statements
// feature statements // feature statements
// identity statements // identity statements
// typedef statements // typedef statements
skipping to change at page 52, line 48 skipping to change at page 57, line 46
// augment statements // augment statements
// rpc statements // rpc statements
// notification statements // notification statements
// DO NOT put deviation statements in a published module // DO NOT put deviation statements in a published module
} }
<CODE ENDS> <CODE ENDS>
Author's Address Author's Address
Andy Bierman Andy Bierman
YumaWorks YumaWorks
Email: andy@yumaworks.com Email: andy@yumaworks.com
 End of changes. 59 change blocks. 
140 lines changed or deleted 310 lines changed or added

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