draft-ietf-netmod-rfc6087bis-06.txt   draft-ietf-netmod-rfc6087bis-07.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track March 20, 2016 Intended status: Standards Track July 7, 2016
Expires: September 21, 2016 Expires: January 8, 2017
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-rfc6087bis-06 draft-ietf-netmod-rfc6087bis-07
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 September 21, 2016. This Internet-Draft will expire on January 8, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 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
skipping to change at page 2, line 22 skipping to change at page 2, line 22
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.1.1. Example Modules . . . . . . . . . . . . . . . . . . . 9
4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9 4.2. Terminology Section . . . . . . . . . . . . . . . . . . . 9
4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10
4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 4.4. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10
4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 11 4.5. Definitions Section . . . . . . . . . . . . . . . . . . . 10
4.6. Security Considerations Section . . . . . . . . . . . . . 11 4.6. Security Considerations Section . . . . . . . . . . . . . 11
4.7. IANA Considerations Section . . . . . . . . . . . . . . . 12 4.7. IANA Considerations Section . . . . . . . . . . . . . . . 11
4.7.1. Documents that Create a New Namespace . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . . . 13 4.9. Validation Tools . . . . . . . . . . . . . . . . . . . . . 12
4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 4.10. Module Extraction Tools . . . . . . . . . . . . . . . . . 13
5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 5. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14
5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 5.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14
5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 5.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16
5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 5.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16
5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 5.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17
5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 5.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18
5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 5.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18
5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 5.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19
5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 5.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20
5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 5.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21
5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 5.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21
5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 5.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22
5.8. Module Header, Meta, and Revision Statements . . . . . . . 23 5.8. Module Header, Meta, and Revision Statements . . . . . . . 23
5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 5.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24
5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 5.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25
5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 25 5.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26
5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 5.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26
5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 26 5.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27
5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 27 5.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28
5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 28 5.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 28
5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 29 5.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 30
5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 29 5.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 30
5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 31 5.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 31
5.16. Notification Definitions . . . . . . . . . . . . . . . . . 31 5.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 32
5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 32 5.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 33
5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 32 5.15. Operation Definitions . . . . . . . . . . . . . . . . . . 33
5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 32 5.16. Notification Definitions . . . . . . . . . . . . . . . . . 33
5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 33 5.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 34
5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 33 5.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 35
5.19.1. Conditional Augment Statements . . . . . . . . . . . . 33 5.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 35
5.19.2. Conditionally Mandatory Data Definition Statements . . 34 5.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 35
5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 35 5.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 35
5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 36 5.19.1. Conditional Augment Statements . . . . . . . . . . . . 36
5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 37 5.19.2. Conditionally Mandatory Data Definition Statements . . 36
5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 38 5.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 37
5.24. Performance Considerations . . . . . . . . . . . . . . . . 40 5.21. Extension Statements . . . . . . . . . . . . . . . . . . . 38
5.25. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 40 5.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 39
5.25.1. Importing Multiple Revisions . . . . . . . . . . . . . 41 5.23. Operational Data . . . . . . . . . . . . . . . . . . . . . 40
5.25.2. Using Feature Logic . . . . . . . . . . . . . . . . . 41 5.24. Performance Considerations . . . . . . . . . . . . . . . . 42
5.25.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 41 5.25. Open Systems Considerations . . . . . . . . . . . . . . . 43
5.25.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 41 5.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 43
5.26. Updating YANG Modules (Published vs. Unpublished) . . . . 42 5.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 43
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 5.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 43
7. Security Considerations . . . . . . . . . . . . . . . . . . . 44 5.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 44
7.1. Security Considerations Section Template . . . . . . . . . 44 5.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 44
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 5.27. Updating YANG Modules (Published vs. Unpublished) . . . . 45
9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 47 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7. Security Considerations . . . . . . . . . . . . . . . . . . . 47
10.1. Normative References . . . . . . . . . . . . . . . . . . . 49 7.1. Security Considerations Section Template . . . . . . . . . 47
10.2. Informative References . . . . . . . . . . . . . . . . . . 50 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 51 9. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 50
A.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 51 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52
A.2. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 51 10.1. Normative References . . . . . . . . . . . . . . . . . . . 52
A.3. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 52 10.2. Informative References . . . . . . . . . . . . . . . . . . 53
A.4. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 52 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 54
A.5. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 52 A.1. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 54
A.6. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 52 A.2. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 54
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 54 A.3. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 54
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 56 A.4. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 55
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 58 A.5. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 55
A.6. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 55
A.7. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 55
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 57
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 59
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 61
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 8, line 27 skipping to change at page 8, line 27
o Narrative sections o Narrative sections
o Definitions section o Definitions section
o Security Considerations section o Security Considerations section
o IANA Considerations section o IANA Considerations section
o References section o References section
There are three usage scenarios for YANG that can appear in an
Internet-Draft or RFC:
o normative module or submodule
o example module or submodule
o example YANG fragment not part of any module or submodule
The guidelines in this document refer mainly to a normative complete
module or submodule, but may be applicable to example modules and
YANG fragments as well.
4.1. Module Copyright 4.1. Module Copyright
The module description statement MUST contain a reference to the The module description statement MUST contain a reference to the
latest approved IETF Trust Copyright statement, which is available latest approved IETF Trust Copyright statement, which is available
online at: online at:
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
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
skipping to change at page 9, line 21 skipping to change at page 9, line 29
description "Latest revision"; description "Latest revision";
reference "RFC XXXX"; reference "RFC XXXX";
} }
// ... more statements // ... more statements
} }
<CODE ENDS> <CODE ENDS>
4.1.1. Example Modules 4.1.1. Example Modules
Note that the <CODE BEGINS> convention MUST NOT be used for example The <CODE BEGINS> convention SHOULD NOT be used for example modules
modules or module fragments. Instead the following convention is or YANG fragments, in order to make sure module extraction tools will
defined for complete example modules: ignore them.
<EXAMPLE BEGINS> file "example-bar@2016-03-20.yang"
module example-bar {
// ...
revision 2016-03-20;
// contains complete module example, intended to compile
// ...
}
<EXAMPLE ENDS>
YANG module fragments MUST NOT use the <CODE BEGINS> or <EXAMPLE
BEGINS> conventions, in order to make sure module extraction tools
will ignore them:
leaf last-change-time { An example module SHOULD be named using the term "example", followed
type yang:date-and-time; by a hyphen, followed by a descriptive name, e.g., "example-toaster".
...
}
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 23, line 17 skipping to change at page 23, line 17
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.
Definitions for future use SHOULD NOT be specified in a module. Do
not specify placeholder objects like the "reserved" example below:
leaf reserved {
type string;
description
"This object has no purpose at this time, but a future
revision of this module might define a purpose
for this object.";
}
}
5.8. Module Header, Meta, and Revision Statements 5.8. Module Header, Meta, and Revision Statements
For published modules, the namespace MUST be a globally unique URI, For published modules, the namespace MUST be a globally unique URI,
as defined in [RFC3986]. This value is usually assigned by the IANA. as defined in [RFC3986]. This value is usually assigned by the IANA.
The organization statement MUST be present. If the module is The organization statement MUST be present. If the module is
contained in a document intended for IETF Standards Track status, contained in a document intended for IETF Standards Track status,
then the organization SHOULD be the IETF working group chartered to then the organization SHOULD be the IETF working group chartered to
write the document. For other standards organizations, a similar write the document. For other standards organizations, a similar
approach is also suggested. approach is also suggested.
The contact statement MUST be present. If the module is contained in The contact statement MUST be present. If the module is contained in
a document intended for Standards Track status, then the working a document intended for Standards Track status, then the working
group web and mailing information MUST be present, and the main group web and mailing information MUST be present, and the main
document author or editor contact information SHOULD be present. If document author or editor contact information SHOULD be present. If
additional authors or editors exist, their contact information MAY be additional authors or editors exist, their contact information MAY be
present. In addition, the Area Director and other contact present.
information MAY be present.
The description statement MUST be present. For modules published The description statement MUST be present. For modules published
within IETF documents, the appropriate IETF Trust Copyright text MUST within IETF documents, the appropriate IETF Trust Copyright text MUST
be present, as described in Section 4.1. be present, as described in Section 4.1.
If the module relies on information contained in other documents, If the module relies on information contained in other documents,
which are not the same documents implied by the import statements which are not the same documents implied by the import statements
present in the module, then these documents MUST be identified in the present in the module, then these documents MUST be identified in the
reference statement. reference statement.
skipping to change at page 28, line 31 skipping to change at page 28, line 44
description "The first enum"; description "The first enum";
} }
enum two { enum two {
description "The second enum"; description "The second enum";
} }
} }
description description
"The foo enum... "; "The foo enum... ";
} }
5.11.4. Union Types
The YANG "union" type is evaluated by testing a value against each
member type in the union. The first type definition that accepts a
value as valid is the member type used. In general, member types
SHOULD be ordered from most restrictive to least restrictive types.
In the following example, the "enumeration" type will never be
matched because the preceding "string" type will match everything.
Incorrect:
type union {
type string;
type enumeration {
enum up;
enum down;
}
}
Correct:
type union {
type enumeration {
enum up;
enum down;
}
type string;
}
It is possible for different member types to match, depending on the
input encoding format. In XML, all values are passed as string
nodes, but in JSON there are different value types for numbers,
booleans, and strings.
In the following example, a JSON numeric value will always be matched
by the "int32" type but in XML the string value representing a number
will be matched by the "string" type. The second version will match
the "int32" member type no matter how the input is encoded.
Incorrect:
type union {
type string;
type int32;
}
Correct:
type union {
type int32;
type string;
}
5.12. Reusable Type Definitions 5.12. Reusable Type Definitions
If an appropriate derived type exists in any standard module, such as If an appropriate derived type exists in any standard module, such as
[RFC6991], then it SHOULD be used instead of defining a new derived [RFC6991], then it SHOULD be used instead of defining a new derived
type. type.
If an appropriate units identifier can be associated with the desired If an appropriate units identifier can be associated with the desired
semantics, then a units statement SHOULD be present. semantics, then a units statement SHOULD be present.
If an appropriate default value can be associated with the desired If an appropriate default value can be associated with the desired
skipping to change at page 31, line 9 skipping to change at page 32, line 31
describe the purpose of each one. describe the purpose of each one.
The "choice" statement is allowed to be directly present within a The "choice" statement is allowed to be directly present within a
"case" statement in YANG 1.1. This needs to be considered carefully. "case" statement in YANG 1.1. This needs to be considered carefully.
Consider simply including the nested "choice" as additional "case" Consider simply including the nested "choice" as additional "case"
statements within the parent "choice" statement. Note that the statements within the parent "choice" statement. Note that the
"mandatory" and "default" statements within a nested "choice" "mandatory" and "default" statements within a nested "choice"
statement only apply if the "case" containing the nested "choice" statement only apply if the "case" containing the nested "choice"
statement is first selected. statement is first selected.
5.14.1. Non-Presence Containers
A non-presence container is used to organize data into specific
subtrees. It is not intended to have semantics within the data model
beyond this purpose, although YANG allows it (e.g., "must" statement
within the non-presence container).
Example using container wrappers:
container top {
container foos {
list foo { ... }
}
container bars {
list bar { ... }
}
}
Example without container wrappers:
container top {
list foo { ... }
list bar { ... }
}
Use of non-presence containers to organize data is a subjective
matter similar to use of sub-directories in a file system. The
NETCONF and RESTCONF protocols do not currently support the ability
to delete all list (or leaf-list) entries at once. This deficiency
is sometimes avoided by use of a parent container (i.e., deleting the
container also removes all child entries).
5.14.2. Top-Level Data Nodes
Use of top-level objects needs to be considered carefully
-top-level siblings are not ordered -top-level siblings not are not
static, and depends on the modules that are loaded
o for sub-tree filtering, retrieval of a top-level leaf-list will be
treated as a content-match node for all top-level-siblings
o a top-level list with many instances may impact performance
5.15. Operation Definitions 5.15. Operation Definitions
If the operation semantics are defined in an external document (other If the operation semantics are defined in an external document (other
than another YANG module indicated by an import statement), then a than another YANG module indicated by an import statement), then a
reference statement MUST be present. reference statement MUST be present.
If the operation impacts system behavior in some way, it SHOULD be If the operation impacts system behavior in some way, it SHOULD be
mentioned in the description statement. mentioned in the description statement.
If the operation is potentially harmful to system behavior in some If the operation is potentially harmful to system behavior in some
skipping to change at page 35, line 49 skipping to change at page 38, line 9
5.20. 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.
Deviation statements can also be used to add annotations to a module,
which does not affect the conformance requirements for the module.
It is suggested that deviation statements be defined in separate It is suggested that deviation statements be defined in separate
modules from regular YANG definitions. This allows the deviations to modules from regular YANG definitions. This allows the deviations to
be platform-specific and/or temporary. be platform-specific and/or temporary.
The order that deviation statements are evaluated can affect the
result. Therefore multiple deviation statements in the same module,
for the same target object, SHOULD NOT be used.
The "max-elements" statement is intended to describe an architectural The "max-elements" statement is intended to describe an architectural
limit to the number of list entries. It is not intended to describe limit to the number of list entries. It is not intended to describe
platform limitations. It is better to use a "deviation" statement platform limitations. It is better to use a "deviation" statement
for the platforms that have a hard resource limit. for the platforms that have a hard resource limit.
Example documenting platform resource limits: Example documenting platform resource limits:
Wrong: (max-elements in the list itself) Wrong: (max-elements in the list itself)
container backups { container backups {
skipping to change at page 40, line 45 skipping to change at page 43, line 12
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 "require-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.25. YANG 1.1 Guidelines 5.25. Open Systems Considerations
A YANG module MUST NOT be designed such that the set of modules found
on a server implementation can be predetermined in advance. Only the
modules imported by a particular module can be assumed to be present
in an implementation. An open system MAY include any combination of
YANG modules.
5.26. YANG 1.1 Guidelines
The set of YANG 1.1 guidelines will grow as operational experience is The set of YANG 1.1 guidelines will grow as operational experience is
gained with the new language features. This section contains an gained with the new language features. This section contains an
initial set of guidelines. initial set of guidelines.
5.25.1. Importing Multiple Revisions 5.26.1. Importing Multiple Revisions
Standard modules SHOULD NOT import multiple revisions of the same Standard modules SHOULD NOT import multiple revisions of the same
module into a module. This MAY be done if the authors can module into a module. This MAY be done if the authors can
demonstrate that the "avoided" definitions from the most recent of demonstrate that the "avoided" definitions from the most recent of
the multiple revisions are somehow broken or harmful to the multiple revisions are somehow broken or harmful to
interoperability. interoperability.
5.25.2. Using Feature Logic 5.26.2. Using Feature Logic
The YANG 1.1 feature logic is much more expressive than YANG 1.0. A The YANG 1.1 feature logic is much more expressive than YANG 1.0. A
"description" statement SHOULD describe the "if-feature" logic in "description" statement SHOULD describe the "if-feature" logic in
text, to help readers understand the module. text, to help readers understand the module.
YANG features SHOULD be used instead of the "when" statement, if YANG features SHOULD be used instead of the "when" statement, if
possible. Features are advertised by the server and objects possible. Features are advertised by the server and objects
conditional by if-feature are conceptually grouped together. There conditional by if-feature are conceptually grouped together. There
is no such commonality supported for "when" statements. is no such commonality supported for "when" statements.
Features generally require less server implementation complexity and Features generally require less server implementation complexity and
runtime resources than objects that use "when" statements. Features runtime resources than objects that use "when" statements. Features
are generally static (i.e., set when module is loaded and not changed are generally static (i.e., set when module is loaded and not changed
at runtime). However every client edit might cause a "when" at runtime). However every client edit might cause a "when"
statement result to change. statement result to change.
5.25.3. anyxml vs. anydata 5.26.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 5.26.4. action vs. rpc
The use of "action" statements or "rpc" statements is a subjective The use of "action" statements or "rpc" statements is a subjective
design decision. RPC operations are not associated with any design decision. RPC operations are not associated with any
particular data node. Actions are associated with a specific data particular data node. Actions are associated with a specific data
node definition. An "action" statement SHOULD be used if the node definition. An "action" statement SHOULD be used if the
protocol operation is specific to a subset of all data nodes instead protocol operation is specific to a subset of all data nodes instead
of all possible data nodes. of all possible data nodes.
The same action name MAY be used in different definitions within The same action name MAY be used in different definitions within
different data node. For example, a "reset" action defined with a different data node. For example, a "reset" action defined with a
skipping to change at page 42, line 34 skipping to change at page 45, line 12
have read access to the specific "interface" instance, then it cannot have read access to the specific "interface" instance, then it cannot
invoke the "reset" action for that interface instance: invoke the "reset" action for that interface instance:
container interfaces { container interfaces {
list interface { list interface {
... ...
action reset { } action reset { }
} }
} }
5.26. Updating YANG Modules (Published vs. Unpublished) 5.27. Updating YANG Modules (Published vs. Unpublished)
YANG modules can change over time. Typically, new data model YANG modules can change over time. Typically, new data model
definitions are needed to support new features. YANG update rules definitions are needed to support new features. YANG update rules
defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be defined in section 11 of [I-D.ietf-netmod-rfc6020bis] MUST be
followed for published modules. They MAY be followed for unpublished followed for published modules. They MAY be followed for unpublished
modules. modules.
The YANG update rules only apply to published module revisions. Each The YANG update rules only apply to published module revisions. Each
organization will have their own way to identity published work which organization will have their own way to identity published work which
is considered to be stable, and unpublished work which is considered is considered to be stable, and unpublished work which is considered
skipping to change at page 51, line 9 skipping to change at page 54, line 9
Protocol (NETCONF) Access Control Model", RFC 6536, Protocol (NETCONF) Access Control Model", RFC 6536,
March 2012. 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. v05 to v06 A.1. v06 to v07
o update contact statement guideline
o update example modules guidelines
o add guidelines on top-level data nodes
o add guideline on use of NP containers
o added guidelines on union types
o add guideline on deviations
o added section on open systems considerations
o added guideline about definitions reserved for future use
A.2. v05 to v06
o Changed example 'my-module' to 'example-module' o Changed example 'my-module' to 'example-module'
o Added section Updating YANG Modules (Published vs. Unpublished) o Added section Updating YANG Modules (Published vs. Unpublished)
o Added Example Modules section o Added Example Modules section
o Added "<EXAMPLE BEGINS>" convention for full example modules o Added "<EXAMPLE BEGINS>" convention for full example modules
o Added section on using action vs. rpc o Added section on using action vs. rpc
o Changed term "operational state" to "operational data" o Changed term "operational state" to "operational data"
o Added section on YANG Data Node Constraints o Added section on YANG Data Node Constraints
o Added guidelines on using must vs. when statements o Added guidelines on using must vs. when statements
o Made ietf-foo module validate for I-D submission o Made ietf-foo module validate for I-D submission
A.2. v04 to v05 A.3. 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 52, line 5 skipping to change at page 55, line 22
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.3. v03 ot v04 A.4. 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.4. v02 to v03 A.5. 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.5. v01 to v02 A.6. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.6. v00 to v01 A.7. 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 56, line 31 skipping to change at page 59, line 31
// identify the IETF working group if applicable // identify the IETF working group if applicable
organization organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group"; "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
// update this contact statement with your info // update this contact statement with your info
contact contact
"WG Web: <http://tools.ietf.org/wg/your-wg-name/> "WG Web: <http://tools.ietf.org/wg/your-wg-name/>
WG List: <mailto:your-wg-name@ietf.org> WG List: <mailto:your-wg-name@ietf.org>
WG Chair: your-WG-chair
<mailto:your-WG-chair@example.com>
Editor: your-name Editor: your-name
<mailto:your-email@example.com>"; <mailto:your-email@example.com>";
// replace the first sentence in this description statement. // replace the first sentence in this description statement.
// replace the copyright notice with the most recent // replace the copyright notice with the most recent
// version, if it has been updated since the publication // version, if it has been updated since the publication
// of this document // of this document
description description
"This module defines a template for other YANG modules. "This module defines a template for other YANG modules.
 End of changes. 30 change blocks. 
89 lines changed or deleted 229 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/